<dataset>

<dataset>
Prev	Data	Next

<dataset>
An in-memory xml-style data hierarchy.

JavaScript: lz.dataset

extends <node> » lz.Eventable »

with lz.DataElementMixin, lz.DataNodeMixin

A <dataset> tag defines a local dataset. The name of the dataset is used in the datapath attribute of a view.

The src attribute of the <dataset> element specifies whether the data is compiled into the application or fetched at runtime:

If the src attribute is a URL, the value of the dataset is the XML data that a request to the URL named by the src attribute returns when the application is run.
If the src attribute is a pathname, the value of the dataset is the content of the XML file that the pathname refers to, and is compiled into the application.
If the src attribute is not present, the value of the dataset is the content of the <dataset> element.

All data in an OpenLazlo application is contained within one or more datasets. A given dataset usually represents a single conceptual set that may or may not be modified or reloaded during the execution of the application. The data within a dataset is accessed using a datapointer or a instance of one of its subclasses. Datasets can represent

local data (i.e. data which is static after compile time), or
http-data (data which is returned as XML over HTTP)

If a dataset is not explictly contained within in a lz.DataProvider, it will make an instance of datasource and be contained inside that. A dataset can be populated or re-poplulated at runtime by calling doRequest on the dataset. The result of the request is then returned to the application and the dataset's ondata event is run. Any <datapointer> that is bound to the dataset will also run its ondata event at this time as well.

See the Developers's Guide for more discussion of data and datasets.

Datasets in SOLO applications. Datasets are implemented differently in proxied and SOLO applications, with slight differences in functionality. For example, in SOLO applications in the SWF8 and SWF9 runtimes is it not possible to retrieve http response headers. Also, white space may be handled differently. See the Developer's Guide.

The example below makes a request of the cgi script on Laszlo's website that serves up weather information in xml form.

Example 12. Making a request using a dataset

<canvas height="250" debug="true">
  <debug y="100"/> 
  <dataset type="http" name="weatherdata" src="http://www.laszlosystems.com/cgi-pub/weather.cgi"/> 
  <view>
     <inputtext width="90" name="t">zip</inputtext>
     <button>  submit
       <handler name="onclick"> var d = canvas.datasets.weatherdata;
         Debug.debug("sending request for weather data.");
         d.setQueryString({zip : parent.t.text});
         d.doRequest(); 
       </handler>
     </button>
     <datapointer xpath="weatherdata:/weather">
       <handler name="ondata">
         var duplicate_pointer = this.dupePointer();
         duplicate_pointer.selectChild();
         while (duplicate_pointer.selectNext()){
           Debug.debug("%w", duplicate_pointer.serialize());
         }
       </handler>
     </datapointer>
     <simplelayout axis="x"/>
   </view>
 </canvas>

Flash

HTML5

Attributes

Name (CSS property)	Type (tag)	Type (js)	Default	Category
`acceptencodings`	boolean	Boolean		readonly
	When true, the server will accept encoded responses for this request. Encoded responses require more work for the LPS (encoding the response) and client (decoding the response) in trade for lower network bandwidth usage.
`autorequest`	boolean	Boolean	false	read/write
	If true, changes to src or querystring attributes cause doRequest() to be called automatically. If false, doRequest() must be called manually when src or querystring attributes change.
`cacheable`	boolean	Boolean	false	readonly
	When true, the server will attempt to cache response (defaults to false). There are security concerns when this field is true. When this field is true, you will usually want the getresponseheaders field to be false.
`clientcacheable`		Boolean	false	read/write
	When true, data responses can be cached by the client (browser). When false, a unique valued argument will be added to the request string in the format '__lzbc__=1204685840777' to defeat the browser's cache.
`dataprovider`	expression	any		read/write
	Holds a pointer to the DataProvider which handles data load requests for this dataset. Default value is canvas.defaultdataprovider
`getresponseheaders`	boolean	Boolean		read/write
	When true, the proxy server (if making a proxied request) will encode and send the HTTP response headers along with the data (defaults to false). Due to a lack of a native API to get this information, SOLO SWF applications will always return an empty set. When making a proxied request, `getresponseheaders` must be true in order for the response headers to be retrieved via the `getResponseHeader` or `getAllResponseHeaders` methods.
`multirequest`		Boolean	false	read/write
	Create a new data request object for each request.
`nsprefix`	boolean	Boolean	false	readonly
	When true, the server will preserve namespace prefixes on data node names and attribute names
`params`		lz.params		read/write
	An lz.Param object which holds query key-value pairs.
`postbody`	string	String		read/write
	Used to send a string as the entire body of a POST request. For a POST request, setting postbody to a non-null string value will send that string as the complete body of the POST request. In this case any other query parameters that have been set via setQueryParam dataset will be ignored. The behavior of a GET request with a non-null postbody is not defined. Note, the swf8 runtime is forced to XML-quote the postbody, due to limitations in the Flash 8 player API. This restriction is not present in later swf runtimes, or in the DHTML runtime.
`proxied`		inheritableBoolean	"inherit"	read/write
	Sets whether or not the dataset makes its request directly to the target server or via the server proxy. Inherits value from canvas.proxied flag.
`proxyurl`	string	String		read/write
	The URL of the proxy server, for proxied requests
`querystring`	string	String		readonly
	A string to be appended to the request that the dataset makes.
`querytype`	get\|post\|GET\|POST	String		read/write
	HTTP request method. Value must be one of "GET" or "POST".
`rawdata`		String	null	read/write
	Holds raw data response string from data source
`request`	boolean	Boolean	false	read/write
	If true, the datset will make a request upon initialization
`secureport`	integer	uint	443	read/write
	TCP port number to use for secure (HTTPS) requests
`src`	string	String		read/write
	The source for requests made by this dataset. The value can be a pathname or an absolute or relative URL. If the value is a URL (starts with "http:"), the dataset will be configured to load its data at runtime. Otherwise, the data is included inline into the application at compile time.
`timeout`	Number	Number		read/write
	The numer of milliseconds to wait before the request times out, and an ontimeout event is sent.
`trimwhitespace`	boolean	Boolean		initialize-only
	When true, the server will trim whitespace in the XML data (defaults to false).
`type`	http\|soap	String		readonly
	When set to "http" or "soap", the dataset interprets it's src attribute as a URL to be loaded at runtime. If the "src" attribute is set to a URL (e.g., starts with "http:") then the type attribute implicitly becomes "http".

Methods

abort()

dataset.abort();

Stops the load of the dataset's current request

clearRequestHeaderParams()

dataset.clearRequestHeaderParams();

Clears all request header parameters which were set from setHeader

doRequest()

dataset.doRequest(ignore);

Does a request immediately using the current values. If autorequest is true, this method is called automatically when the src or querystring attributes change.

Parameter Name	Type	Description
ignore

getAllResponseHeaders()

dataset.getAllResponseHeaders();

Returns all response headers as an object of name/value pairs, or false if there were none.

Returns	Type	Description
	lz.params	A hash table object containing the response headers.

getErrorString()

dataset.getErrorString();

Returns an error string if there was an error, or undefined if there was none.

Returns	Type	Description
	String	An error string, or `undefined` if none.

getLoadTime()

dataset.getLoadTime();

Returns the number of miliseconds it took to load the dataset's request

Returns	Type	Description
	Int	Number of miliseconds it took to load the last request.

getParams()

dataset.getParams();

Returns an lz.Param object holding any set request parameters for the dataset.

Returns	Type	Description
	lz.params	The request parameters for the dataset.

getPointer()

dataset.getPointer();

Returns a datapointer pointing to the root of the dataset.

Returns	Type	Description
	lz.datapointer	A datapointer that points to the root of the dataset.

getQueryString()

dataset.getQueryString();

Returns the querystring attribute of the dataset, if there is one

Returns	Type	Description
	String	The querystring attribute of the dataset

getRequestHeaderParams()

dataset.getRequestHeaderParams();

Retrieves the lz.Param object which represents the headers sent with the dataset's last request

Returns	Type	Description
	lz.params	The headers from the dataset's last request

getResponseHeader()

dataset.getResponseHeader(name : String);

Returns the value for the specified response header, or null if there was no header with that name.

Parameter Name	Type	Description
name	String	The name of the header to return

Returns	Type	Description
	String

getSrc()

dataset.getSrc();

Return the src attribute of the dataset, if one was given.

Returns	Type	Description
	String	The src of attribute of the dataset

setHeader()

dataset.setHeader(k : String, val : String);

Sets a header for the next request

Parameter Name	Type	Description
k	String	Key for the header
val	String	Value for the header

setQueryParam()

dataset.setQueryParam(key : String, val : String);

Sets a named query parameter to the given value. The query parameters are sent with every request. The key 'lzpostbody' has a specific interpretation, see setQueryType() for details.

Parameter Name	Type	Description
key	String	The name of the parameter
val	String	The value for the parameter

setQueryParams()

dataset.setQueryParams(obj : Object);

Sets multiple query parameters from using the keys in the argument as keys and the values of those keys as values. This method can also be used to clear the query params, by passing null to it.

Parameter Name	Type	Description
obj	Object	An object whose keys are keys of parameters and whose values are those parameters' values. Passing a value of null to this method clears the query parameters. The key 'lzpostbody' has a specific interpretation, see setQueryType() for details.

setQueryString()

dataset.setQueryString(s : String);

Sets the querystring parameter of the dataset to the given string. If an object is given instead of a string, the object will be automatically converted to a string and used instead. The dataset's querystring will be pre-pended to any request made for the dataset.

Parameter Name	Type	Description
s	String	A string to be appended to any query made on behalf of this dataset.

Methods inherited from lz.DataElementMixin

appendChild, getAttr, getElementsByTagName, getFirstChild, getLastChild, handleDocumentChange, hasAttr, hasChildNodes, insertBefore, removeAttr, removeChild, replaceChild, setAttr

Methods inherited from lz.DataNodeMixin

childOf, cloneNode, getNextSibling, getOffset, getParent, getPreviousSibling, getUserData, serialize, setUserData

Methods inherited from lz.Eventable

destroy, setAttribute

Class Methods

queryStringToTable()

lz.dataset.queryStringToTable(query);

Produce a hash table of key-value pairs. In the case of a duplicated key, creates an array of values.

Parameter Name	Type	Description
query

Events

Name	Description
`onerror`	Sent when the dataset's request results in an error.
`ontimeout`	Sent when the request made by the dataset times out.

Events inherited from lz.DataNodeMixin

onattributes, onchildNode, onchildNodes, onDocumentChange, onnodeName, onownerDocument, onparentNode

Events inherited from <node>

onconstruct, ondata, oninit

Events inherited from lz.Eventable

ondestroy

Copyright © 2002-2010 Laszlo Systems, Inc. All Rights Reserved. Unauthorized use, duplication or distribution is strictly prohibited. This is the proprietary information of Laszlo Systems, Inc. Use is subject to license terms.

Prev	Up	Next
lz.DataRequest	Home	lz.DataText

<dataset> An in-memory xml-style data hierarchy.

Attributes inherited from lz.DataElementMixin

Attributes inherited from lz.DataNodeMixin

Attributes inherited from <node>