<dataset>
Prev  Data  Next

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

JavaScript: lz.dataset
extends <node> » lz.Eventable »

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 25. 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>
edit

Attributes

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 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.
proxied   inheritableBoolean "inherit" read/write
  Proxy data requests via the proxy server. 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   read/write
  If true, the datset will make a request when it inits. The default for this is false.
secureport integer uint 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, inited, initstage, name, nodeLevel, options, parent, placement, subnodes

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 values 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
setPostBody()
dataset.setPostBody(str : String);
[Caution] This method is deprecated
Use setAttribute('postbody', ...) instead.
Sets the raw content of a POST body. This replaces the old "lzpostbody" convention for passing raw POST data.
Parameter Name Type Description
str String The string to use as the raw POST body content
setProxyRequests()
dataset.setProxyRequests(val : String);
[Caution] This method is deprecated
Use setAttribute('proxied', ...) instead.
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()
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.
setQueryType()
dataset.setQueryType(reqtype : String);
[Caution] This method is deprecated
Use setAttribute('querytype', ...) instead.
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 String 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()
dataset.setRequest(b : Boolean);
[Caution] This method is deprecated
Use setAttribute('request', ...) instead.
Sets whether or not the dataset makes its request upon initialization
Parameter Name Type Description
b Boolean If true, the dataset will make its request when it is initialized
setSrc()
dataset.setSrc(src : String);
[Caution] This method is deprecated
Use setAttribute('src', ...) instead.
Sets the src attribute of the data request.
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 <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

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 <node>

onconstruct, ondata, oninit

Events inherited from lz.Eventable

ondestroy

Copyright © 2002-2008 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