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 LzDataProvider, 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 SWF7 and SWF8 runtime 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 20. Making a request using a dataset
<canvas height="250" width="800" 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.write("sending request for weather data.");
d.setQueryString({zip : parent.t.getText()});
d.doRequest();
</handler>
</button>
<datapointer xpath="weatherdata:/weather">
<handler name="ondata">
var duplicate_pointer = this.dupePointer();
duplicate_pointer.selectChild();
while (duplicate_pointer.selectNext()){
Debug.write(duplicate_pointer.serialize());
}
</handler>
</datapointer>
<simplelayout axis="x"/>
</view>
</canvas>
| Name | 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 | false | read/write | |
| If autorequest is true, a new request will be issued automatically when the source or query params are modified. | ||||
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 | read/write | ||
| When true, an argument will be added to the request string in the format '__lzbc__=1204685840777'. This is to prevent client caching. | ||||
dataprovider
|
read/write | |||
| Holds a pointer to the DataProvider which handles data load requests for this dataset. Default value is canvas.defaultdataprovider | ||||
getresponseheaders
|
boolean | Boolean | readonly | |
| When true, the server 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. | ||||
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.Param | read/write | ||
| An LzParams object which holds query key-value pairs. | ||||
proxied
|
Boolean | null | read/write | |
| Proxy data requests via the proxy server. Inherits value from canvas.proxied flag. | ||||
proxyurl
|
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". | ||||
request
|
boolean | Boolean | read/write | |
| If true, the datset will make a request when it inits. The default for this is false. | ||||
secureport
|
integer | Number | 443 | read/write |
| TCP port number to use for secure (HTTPS) requests | ||||
src
|
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". | ||||
Attributes inherited from <node>
classroot, cloneManager, datapath, defaultplacement, id, ignoreplacement, immediateparent, initstage, name, nodeLevel, options, parent, placement, subnodes
Methods
-
abort() -
-
clearRequestHeaderParams() -
-
doRequest() -
Does a request immediately using the current values. If autorequest is true, this method is called automatically when values change.
-
getAllResponseHeaders() -
-
getErrorString() -
-
getLoadTime() -
-
getParams() -
-
getPointer() -
-
getQueryString() -
-
getRequestHeaderParams() -
-
getResponseHeader() -
Returns the value for the specified response header, or false if there was no header with that name. If name is omitted, all response headers are returned as an object of name/value pairs.
-
getSrc() -
-
getStatusCode() -
![[Caution]](images/caution.png)
This method is deprecated Use onerrororontimeoutevents insteadReturns the status of the dataset's request. Always returns 200 since the server will respond with an error if the request fails.
-
LzDataset() -
-
setHeader() -
-
setPostBody() -
Sets the raw content of a POST body. This replaces the old "lzpostbody" convention for passing raw POST data.
-
setProxyRequests() -
Sets whether or not the dataset makes its request directly to the target server or via the LPS server proxy.
Parameter Name Type Description val String If 'true', the dataset will make its request when it is initialized, if 'false', request will be direct, if 'inherit', it will inherit from its datasource.
-
setQueryParam() -
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() -
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 o 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() -
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.
-
setQueryType() -
Sets the query type of for the datasource to one of "POST" or "GET" by calling the method of the same name on this dataset's datasource. Note that this controls how the LPS server makes a request of the backend, as well as how the client communicates with the LPS
Parameter Name Type Description reqtype Sring A string -- either "GET" or "POST". GET is the default. When the type is "POST", the query parameters will be sent in the request body, encoded as application/x-www-form-urlencoded If the type is "POST" and there is a exactly one request parameter and it is named "lzpostbody", it will be used as the raw request body (unencoded). Use of "lzpostbody" with a request that has more than one request parameter is undefined.
-
setRequest() -
This method is deprecated Use setAttribute('request', ...) instead. Parameter Name Type Description b Boolean If true, the dataset will make its request when it is initialized
-
setSrc() -
This method is deprecated Use setAttribute('src', ...) instead. Parameter Name Type Description src String A new src URL for data request. Need to handle these cases http:foo.html http:/foo/bar.html http:foo.ksp?q=12 http:/foo.ksp?q=12 http:/foo/bar.ksp?q=12
Methods inherited from lz.DataElementMixin
appendChild, getAttr, getElementsByTagName, getFirstChild, getLastChild, handleDocumentChange, hasAttr, hasChildNodes, insertBefore, removeAttr, removeChild, replaceChild, setAttr, setAttrs, setChildNodes, setNodeName
Methods inherited from lz.DataNodeMixin
childOf, cloneNode, getNextSibling, getOffset, getParent, getPreviousSibling, serialize, setOwnerDocument
Methods inherited from <node>
animate, applyConstraint, applyConstraintMethod, applyData, childOf, completeInstantiation, construct, createChildren, dataBindAttribute, destroy, determinePlacement, getAttribute, getOption, getUID, init, lookupSourceLocator, releaseConstraint, releaseConstraintMethod, searchImmediateSubnodes, searchSubnodes, setData, setDatapath, setOption, setSelected, updateData
Class Methods
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