Table of Contents
This chapter describes various methods of tying XML data structures into your LZX application. See Chapter 35, Data, XML, and XPath for discussion of some of the concepts used in this chapter. For a gentle introduction to databinding and manipulation in OpenLaszlo applications, you may start with the tutorials.
By "databinding" we mean the automatic association of a value in an XML data structure with an element in the LZX view hierarchy of the application. This chapter explores various aspects of databinding and manipulation in OpenLaszlo applications. Before going into spefici details, we'll start with a conceptual overview of how data is represented in LZX applications, and the APIs for manipulating it.
A dataset (LzDataset) is two things:
-
Firstly, it is the client side store for XML data. It's where a single XML document lives in an OpenLaszlo application.
-
Secondly, it's the mechanism by which OpenLaszlo applications make HTTP GET or POST requests.
An LzDataElement is the LZX class that represents a single XML data tag in OpenLaszlo applications. LzDataElements are usually kept in a dataset, although data-bound views can get pointers to them even if they are not in a dataset. Inside of a dataset, LzDataElements are linked in a tree-like structure, but that doesn't mean to say that an LzDataElement must go inside of a dataset.
LzDataElement is a subclass of LzDataNode, as is LzDataText..
Finally, note that a dataset is a subclass of LzDataElement, which means that all of the methods which work on LzDataElements also work on LzDataSets, although the usual method of manipulating datasets is with datapaths and datapointers, as explained below.
As we have said, all data in OpenLaszlo applications is in XML format. There are two related but distinct ways of using and manipulating that data in OpenLaszlo applications; that is, there two API models:
-
The DOM model—in which the APIs allow you to directly manipulate elements of a Document Object Model using DOM conventions.
-
The DataPointer model—in which the APIs allow you to position a logical cursor within the dataset using XPATH syntax
These two categories of APIs have similar functionality with large areas of overlap. However, there are some things that can only be done (or can best be done) using one specific approach (and not the other). This means that in many situations there are two logically distinct ways to achieve the same result. Learning to master data manipulation in LZX is a matter of becoming fluent in both approaches and knowing when to use each.
The Document Object Model is, according to the W3C specification, "a platform- and language-neutral interface that will allow programs and scripts to dynamically access and update the content, structure and style of documents." In the LZX context, the "document" is that LzDatanode.
LzDataNode is the base class for the classes that represent LZX's hierarchical data format. An LzDataNode comprises LzDataElements. An LzDataElement represents a node in a hierarchical dataset. An LzDataElement can contain other LzDataElements, or LzDataText, which represents a text node. More advanced data manipulation in OpenLaszlo applications employ the various methods on the LzDataElement class, such as appendChild(), getNextSibling(), and so forth. These classes can only be created in script, not by tags. For tag-based data manipulation, use <dataset> and the related concepts of datapointers and datapaths.
In addition to LzDataNodes, which can only be manipulated in script, LZX includes the notions of <datapath> and <datapointer>, which provide a convenient, tag-based mechanism for typical data manipulation. By using datapointers to move through the data, you control the behavior of views that are bound to that data.
Data in OpenLaszlo applications can be declared with a tag, or built up using procedural (script) APIs. The script APIs operate on LzDataNodes.
All declaratively-declared data in OpenLaszlo applications is contained within one or more datasets. The content of a dataset is an XML fragment with a single root node, but without the XML declaration. A given dataset usually represents a single conceptual set that may or may not be modified or reloaded during the execution of the application.
You declare a dataset in your application using the <dataset> tag. The name of the dataset is used in the datapath attribute of a view, as will be explained below.
Datasets can be embedded directly in applications, constructed at runtime, or procured from remote servers. A dataset may be declared on the canvas, in which case it is visible to the entire application, or it may be declared within a class, in which case it is visible to the members of that class.
To embed a dataset directly in an OpenLaszlo application, you use the <dataset> tag as below. In this example, you can get access to the given dataset by referring to canvas.shelf.
Example 36.1. Embedding data in an OpenLaszlo application
<canvas>
<dataset name="shelf">
<bookshelf>
<book binding="paperback">
<title>Acts of the Apostles</title>
<author>John F.X. Sundman </author>
<publisher>Rosalita Associates </publisher>
<price>15.00</price>
<year>1999</year>
<category>thriller</category>
<rating>4.5 </rating>
</book>
<book binding="casebound">
<title>Shock</title>
<author>Robin Cook </author>
<publisher>Putnam </publisher>
<price>24.95</price>
<year>2001</year>
<category>thriller</category>
<rating>3.5 </rating>
</book>
<book binding="paperback">
<title>Cheap Complex Devices</title>
<editor>John Compton Sundman </editor>
<publisher>Rosalita Associates </publisher>
<price>11.00</price>
<year>2002</year>
<category>metafiction</category>
<rating>5.0 </rating>
</book>
</bookshelf>
</dataset>
</canvas>
|
This style of dataset inclusion is called local data in that the data is included locally in the application, rather than being retrieved from a remote data source or web service. Data can be included from a remote source by specifying the src attribute as follows:
Example 36.2. Dataset from a remote source
<canvas height="400" >
<dataset name="menu" src="http://www.w3schools.com/xml/simple.xml" request="true"/>
<simplelayout axis="y"/>
<button onclick="t.setText(menu.serialize())">Show XML data </button>
<inputtext multiline="true" width="${canvas.width}" bgcolor="0xa0a0a0" id="t" height="300"/>
</canvas>
|
In this example the OpenLaszlo application, when it starts up, makes a HTTP request for the url, http://www.w3schools.com/xml/simple.xml and populates the dataset named menu with the XML returned. You can click the button to see the serialized contents of the dataset.
The src attribute should be a well-formed URL that points to the back-end data source that will produce the data. This may be an absolute or relative URL. (All requests made for relative URLs are relative to the application's URL.) The URL may point to a static XML file or a server-side processor (such as JSP, ASP, PHP, and so on) that produces XML data.
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.
The data within a dataset is accessed using a <datapointer> or a instance of one of its subclasses.
A dataset is an instantiation of the LzDataset class. An LzDataset is a Javascript object that provides a Document Object Model (DOM) API for accessing, manipulating, and creating XML elements and attributes in memory. These APIs are discussed in Chapter 36, Data Access and Binding. The dataset also has APIs that pertain to data transport.
The datapath of the <text> tag binds it to the data.
Datapaths use XPath attributes to navigate through the XML data. So the name of the dataset to use goes before the colon myData:, followed by the nodes, separated by forward slashes (/). The square brackets provide a (one-based) space to enter which sibling node we want. [1] is implied, so the above example could be rewritten without any "[1]"s.
The /text() path segment is unnecessary with the datapath attribute.
So far we've used the <text> tag in conjunction with a single datapath. If we wanted to present tabular information, this would mean each text element would need its own datapath, and would be cumbersome and difficult to write. Instead let's make a quick table, by giving a <view> a datapath:
Example 36.3. Assigning a datapath to a view
<canvas height="80" width="500">
<dataset name="myData">
<myXML>
<person show="simpsons">
<firstName>Homer</firstName>
<lastName>Simpson</lastName>
</person>
<person show="simpsons">
<firstName>Marge</firstName>
<lastName>Simpson</lastName>
</person>
<person show="simpsons">
<firstName>Montgomery</firstName>
<lastName>Burns</lastName>
</person>
</myXML>
</dataset>
<view name="rowOfData" datapath="myData:/myXML[1]/person[1]">
<simplelayout axis="x" />
<text datapath="firstName/text()" />
<text datapath="lastName/text()" />
<text datapath="@show" />
</view>
</canvas>
|
The datapath of the entire rowOfData view has now become Homer's person node. The child elements of rowOfData inherit this, so their datapaths can be referenced relatively.
In the above example we used a single rowOfData node. Next, we shall use a range of all of the nodes:
Example 36.4. Range of nodes
<canvas height="80" width="500" >
<dataset name="myData">
<myXML>
<person show="simpsons">
<firstName>Homer</firstName>
<lastName>Simpson</lastName>
</person>
<person show="simpsons">
<firstName>Marge</firstName>
<lastName>Simpson</lastName>
</person>
<person show="simpsons">
<firstName>Montgomery</firstName>
<lastName>Burns</lastName>
</person>
</myXML>
</dataset>
<view name="myTable">
<simplelayout axis="y" />
<view name="rowOfData" datapath="myData:/myXML[1]/person">
<simplelayout axis="x" />
<text datapath="firstName/text()" />
<text datapath="lastName/text()" />
<text datapath="@show" />
</view>
</view>
</canvas>
|
Whichever tag contains the datapath attribute will get repeated as often as is necessary.
Remember that datapaths bind themselves to a view, so if the data changes, so will the view.
The source for a dataset may be anything that returns XML, including sources elsewhere on the web. For instance, the source may be a URL for a .jsp or .php program that generates XML data "on the fly." This is a typical architecture for OpenLaszlo applications. The table below highlights ways of categorizing datasets according to where the data comes from and how it is integrated into the application.
| How is it included? | When is it loaded? | Syntax | |
|---|---|---|---|
| Embedded | Compile-time |
|
|
| Included | Compile-time |
|
|
| HTTP data | Runtime |
|
Embedded data is XML between the <dataset> tags. When the OpenLaszlo Compiler compiles the application, the data is bound into it. The data can still be changed after the application runs.
Included data is essentially the same as embedded data, except that the XML itself is kept in a separate file. The size of the initial download will be the same as with embedded data.
It is locally referenced via the filesystem, so it can be placed in other directories. Included data is static.
Remote data goes over HTTP, which means it can (but doesn't have to) be dynamic. If it is static, then the only difference between it and included or embedded data is that it is downloaded after the application loads. The type="http" attribute tells the OpenLaszlo Server that this is an HTTP request. The requests can be either GET or POST.
There are several points at which the client makes requests for the data:
In the table above, we referenced a file locally (myXMLDoc.xml), but we could have done it absolutely, or we could have hit a server-side script (PHP, ASP, JSP or some CGI) that returned an XML document. We could add the query string to the <dataset> tag:
<dataset name="myData"
src="http://www.myServer.com/cgi-bin/myXMLDoc.cgi?return=addresses"/>
|
The type="http" attribute gets implied when the src attribute contains "http://".
![[Note]](images/note.png) |
Note |
|---|---|
|
You do not have to worry about speed of the Flash Player's XML parser when using the OpenLaszlo Server. |
|
If specified on the canvas, datasets are visible to and accesible by the entire application. Datasets can also be local to a class.
-
Datasets will automatically name themselves localdata if a name is not specified
-
Local datapath syntax is datapath="local:reference.to.dataset.relative.to.parent:/path"
-
The name of the dataset can be omitted fromm the datapath if the dataset name is the default 'localdata', e.g. 'local:classroot:/' can be used instead of 'local:classroot.localdata:/' for a dataset named localdata in the classroot
Here is a simple program that illustrates use of local datasets (the file tests/data, a sample XML file is included in this directory also.)
Example 36.5. local datasets
<canvas width="100%" height="200" >
<debug fontsize="12"/>
<view layout="axis: y">
<dataset name="ds" src="http://..."/>
<text datapath="this.ds:/record/text()"/>
</view>
<class name="myclass" layout="axis: y">
<dataset name="ds" src="http://..."/>
<text datapath="this.ds:/record/text()"/>
</class>
<myclass/>
<myclass/>
<dataset name="gdata" src="../testdata.xml"/>
<simplelayout spacing="2"/>
<view name="nodatanoname" layout="axis: y" bgcolor="#cccccc">
<handler name="onclick">
Debug.write(this.localdata);
</handler>
<dataset/>
<text>empty local dataset with no name</text>
</view>
<view name="nodata" layout="axis: y" bgcolor="#cccccc">
<handler name="onclick">
Debug.write(this.lds);
</handler>
<dataset name="lds"/>
<text>empty local dataset</text>
</view>
<view name="somedata" layout="axis: y" bgcolor="#cccccc">
<handler name="onclick">
Debug.write(this.lds);
</handler>
<dataset name="lds">
<foo>bar</foo>
</dataset>
<text>local dataset</text>
<handler reference="lds" name="oninit">
<![CDATA[
Debug.write("somedata test data loaded", this);
if (this.lds.serialize() != '<lds><foo>bar</foo></lds>') {
Debug.error("somedata serialized data does not match expected value");
}
]]>
</handler>
</view>
<view name="filedata" layout="axis: y" bgcolor="#cccccc">
<handler name="onclick">
Debug.write(this.lds);
</handler>
<dataset name="lds" src="../testdata.xml"/>
<text>local dataset compiled in from external file</text>
<handler reference="lds" name="oninit">
<![CDATA[
Debug.write("filedata test data loaded", this);
if (this.lds.serialize() != '<lds><persons><person id="1"><firstName>Dan</firstName><lastName>McGowan</lastName><modifyDate>3/25/05</modifyDate><address code="ML" id="1"><line1>2210 North 184th Street</line1><line2/><city>Shoreline</city></address></person><person id="2"><firstName>Barry</firstName><lastName>Bonds</lastName><modifyDate>3/25/05</modifyDate></person><person id="3"><firstName>Jeff</firstName><lastName>Beck</lastName><modifyDate>3/25/05</modifyDate></person></persons></lds>') {
Debug.error("filedata serialized data does not match expected value");
}
]]>
</handler>
</view>
<view name="remotedata" layout="axis: y" bgcolor="#cccccc">
<handler name="onclick">
Debug.write(this.lds);
</handler>
<dataset name="lds" src="../testdata.xml" type="http" request="true"/>
<text>local dataset loaded at runtime</text>
<text datapath="local:parent.lds:/persons/person/firstName/text()" onclick="Debug.write(this.datapath)"/>
<handler reference="lds" name="ondata">
<![CDATA[
Debug.write("remotedata test data loaded", this);
if (this.lds.serialize() != '<lds><persons><person id="1"><firstName>Dan</firstName><lastName>McGowan</lastName><modifyDate>3/25/05</modifyDate><address id="1" code="ML"><line1>2210 North 184th Street</line1><line2/><city>Shoreline</city></address></person><person id="2"><firstName>Barry</firstName><lastName>Bonds</lastName><modifyDate>3/25/05</modifyDate></person><person id="3"><firstName>Jeff</firstName><lastName>Beck</lastName><modifyDate>3/25/05</modifyDate></person></persons></lds>') {
Debug.error("remotedata serialized data does not match expected value");
}
]]>
</handler>
</view>
<view name="remotedatarelative" layout="axis: y" bgcolor="#cccccc" datapath="local:lds:/persons/" visible="true">
<handler name="onclick">
Debug.write(this.lds);
this.datapath.setXPath(this.datapath.xpath);
</handler>
<dataset name="lds" src="../testdata.xml" type="http" request="true"/>
<text>local dataset loaded at runtime and relative datapath - datapath doesn't resolve because dataset doesn't exist yet. click to reparse xpath</text>
<text datapath="person/firstName/text()" onclick="Debug.write(this.datapath)"/>
</view>
<class name="localdatatest">
<dataset/>
<view datapath="local:classroot:/">
<simplelayout/>
<handler name="onclick">
this.datapath.addNode('child', 'Click to remove this node', {});
</handler>
<text>Click to add a node to my local dataset</text>
<text x="10" datapath="child/text()" onclick="this.datapath.deleteNode();"/>
</view>
</class>
<class name="redlocaldatatest" extends="localdatatest" bgcolor="red"/>
<localdatatest/>
<localdatatest/>
<redlocaldatatest/>
</canvas>
|
When the application's LzDataset receives the data, the ondata event is sent. In the case that an error occured in communicating with the back-end (which may be proxied by the OpenLaszlo Server in proxied applications, or direct, in SOLO applications), an onerror event is sent instead. And, if there is a timeout (currently hard-coded at 30 seconds) in communicating with the back end, an ontimeout event is sent. The OpenLaszlo Runtime guarentees that each request generates exactly one of ondata, onerror, or ontimeout.
Datasets support both HTTP GET and POST methods for communicating with the OpenLaszlo Server and back-end servers. The default is GET but this can be changed with the LzDataset.setQueryType() API. In general, requests with large query parameters should be sent via POST.
In general, the OpenLaszlo Server proxies HTTP request and response headers to and from the back-end. However, certain headers are specifically omitted or modified.
Note that response headers are not available to SOLO applications.
The OpenLaszlo Server proxies all "Cookie" request headers and all "Set-Cookie" response headers. Because of the domain name restrictions on cookies, the OpenLaszlo Server can only properly proxy these cookie headers when the back-end host is in the same domain (or a subdomain) or the OpenLaszlo host. For more on this topic, see Chapter 41, Cookies and Sessions
Underlying each dataset that communicates over HTTP is an LzDatasource object. This object abstracts all protocol specific communication. In general, you do not need to use the datasource object yourself, except for very rare situations.
For example, one situation is when you are running the OpenLaszlo Server secure port on something other than 443; the only place you can specify the secure port is on the datasource.
<XMLHTTPRequest> implements XMLHttpRequest as specified by the what-wg consortium. Basically, this class allows you to fetch XML data from a URL, and so it is essentially equivalent to the LzDataset API (or the <dataset> tag.) It is provided as a convenience to developers who are familiar with its syntax from its use in AJAX applications.
Here is an example of the XMLHTTPRequest class.
Example 36.6. XMLHTTPRequest
<canvas width="1400" height="600" debug="true">
<debug width="400" height="300" fontsize="12" x="400"/>
<include href="rpc/ajax.lzx" />
<script>
<![CDATA[
var req = null;
function processReqChange() {
Debug.write("processReqChange: req.readyState", req.readyState);
// only if req shows "loaded"
if (req.readyState == 4) {
// only if "OK"
if (req.status == 200) {
Debug.write("req.status", req.status);
Debug.write("req.responseText:", req.responseText);
Debug.write("req.responseXML:", req.responseXML);
Debug.write("req.getAllResponseHeaders:", req.getAllResponseHeaders());
} else {
Debug.write("There was a problem retrieving the XML data:\n" +
req.statusText);
}
}
}
function loadXMLDoc(url) {
// branch for native XMLHttpRequest object
req = new XMLHttpRequest();
req.onreadystatechange = processReqChange;
req.open("GET", url, true);
req.setRequestHeader('X-Test', 'one');
req.setRequestHeader('X-Test', 'two');
req.send(null);
}
]]>
</script>
<simplelayout spacing="4"/>
<edittext id="in1">echo.jsp</edittext>
<button onclick="loadXMLDoc(in1.getText())">Load Data</button>
<button onclick="loadXMLDoc('badurl')">Test Error Handling, this should fail</button>
</canvas>
|
In SOLO applications, the XMLHTTPRequest class does provide one capability that is not currently available from datasets; that is, you can get the raw text of the XML as a string, before it is parsed. You do this using the responseText() method. This capability is only available in SOLO applications.
Note that by accessing a URL in this way you can fetch data that is not XML, which may come in handy in some situations. However, since LZX is predicated on the XML data model, in general you shouldn't expect to be using this technique very much.
Also, in SOLO deployed applications, the XMLHTTPRequest class departs from the what-wg specification in these ways:
-
HTTP headers are not settable
-
response headers are not accessible
-
you cannot send raw POST data
-
you cannot send repeated query args in a POST using LoadVars
-
Username/password HTTP Auth args to send() are not supported.
Datapaths are extremely handy, but if you need more control over the data, they can become cumbersome. (Datapaths are actually extensions of datapointers, but are easier to learn, which is why we introduced them first.) A datapointer is a pointer into the dataset, which can be moved around. It can only be in one place of the dataset at a time, but you can have multiple datapointers, each pointing to a different part of a dataset.
Datapointers are not bound to views like datapaths are, but they do have a place in the view hierarchy—that is, they "know about" parents and children.
You will use a datapointer when you need to operate on the data in some way. For example, using the same format of data as in the previous examples, say you wanted to find all the people who were in the South Park show:
Example 36.7. Manipulating datapointers
<canvas height="180" width="500" debug="true">
<dataset name="myData" src="../../guide/myShowData.xml" />
<datapointer xpath="myData:/" ondata="processData()">
<method name="processData">
this.selectChild(2);
do {
if (this.xpathQuery( '@show' ) == 'south park') {
Debug.write(this.xpathQuery('firstName/text()'));
}
} while (this.selectNext());
</method>
</datapointer>
</canvas>
|
For brevity's sake, we are writing to the debugger, and we are including the data from a local file.
The first selectNext(2) method call selects first the <myXML> node, then the South Park <person> node. It selects two because of the depth argument "2" we pass it (otherwise it would default to 1.
The other selectNext method call returns true as long as an XML node was successfully selected (i.e. until there aren't any more). We exploit this by using it in a do … while loop, so that the same iteration occurs for every <person> node.
We could also have given the <datapointer> onerror and ontimeout event handlers to capture any problems.
A <dataset> provides a way to encapsulate arbitrary XML data in an OpenLaszlo application. Depending on the source of the data, datasets can be static or dynamic. When a dataset is explicitly declared with type="http", the value of its src is interpreted as an URL and the dataset is populated with data at runtime. If the src attribute is absent, the data it represents is expected to be contained within the <dataset> tags, and thus also compiled into the application.
When we say that HTTP datasets are dynamic, we mean that you can repopulate them programmatically by calling the doRequest() method of the dataset object, or if the request attribute is set to true, by changing the URL of the dataset when one of the setSrc(), setQueryString(), or setQueryParam() methods is called.
When a dataset is defined as an immediate child of <canvas> or <library>, it can be referenced anywhere in the code through the datasets property of canvas, i.e. canvas.datasets['mydset'], or simply by its name (it is globally visible):
Example 36.8. Explicitly defined datasets
<canvas debug="true" height="200">
<debug height="150"/>
<dataset name="mydset" src="http:?lzt=xml"/>
<dataset name="week">
<day>Sunday</day>
<day>Monday</day>
<day>Tuesday</day>
<day>Wednesday</day>
<day>Thursday</day>
<day>Friday</day>
</dataset>
<script>
Debug.write(mydset);
Debug.write(canvas.datasets['mydset']);
Debug.write(week)
</script>
</canvas>
|
Datasets can also be created at runtime in script by calling the constructor for the LzDataset: var dset = new LzDataset(null, {name: 'mydset'}). The first argument to the constructor is the dataset's parent node, which is the <datasource> that encloses this dataset; this parameter is allowed to be null — in this case a datasource will be created implicitly.
The LZX event system allows you to insert custom data handling into the application as needed. This is typically done by overriding the applyData() method of the databound node, by providing a handler for the ondata event on the datapointer or datapath, or by defining a $path constraint on an expression-type attribute and processing changes to the attribute's value with the onattribute_name handler.
The applyData() method is called on any node that is declared with a datapath that matches a terminal selector, such as text() or @attribute when the data it matches is changed. The argument passed to the method is the string the data represents. Use the ondata event if the node is bound to a datapath that matches a data node (see below).
Example 36.9. Overriding applyData
<canvas height="150">
<dataset name="colors">
<value>red</value>
<value>green</value>
<value>olive</value>
<value>yellow</value>
<value>blue</value>
<value>teal</value>
</dataset>
<simplelayout spacing="10"/>
<view name="swatch" width="200" height="30"
datapath="colors:/value[1]/text()">
<method name="applyData" args="v">
setBGColor(eval(v))
display.setText(v)
</method>
</view>
<text name="display" resize="true"/>
<button text="Change view color">
<attribute name="ind" value="$once{1}"/>
<handler name="onclick">
if (++ind == 7) ind = 1
swatch.setDatapath('colors:/value[' + ind + ']/text()')
</handler>
</button>
</canvas>
|
Attributes of a node can be bound to data explicitly by using the $path{} constraint syntax. The expression inside the curly brackets must evaluate to a string, which is interpreted as a relative XPath expression.
If you need to use an absolute path in the expression, you could instead constrain the attribute to the result of an xpathQuery() call: visible="dp.xpathQuery('mydset:/record/row[1]/@visible')". A limitation of the $path{} constraint is that the expression it contains is evaluated only at the initialization time, that is, an expression such as $path{'mynode[' + i + ']/@attr'} will behave like a $once{} constraint.
$path bindings are two-way, so calling updateData() on a node's datapath will store the current value for that attribute back in the dataset.
Example 36.10. $path constraint example
<canvas height="150" >
<dataset name="sizes">
<value>200</value>
<value>150</value>
<value>100</value>
</dataset>
<button text="Shrink me" datapath="sizes:/value[1]" >
<attribute name="width" value="$path{'text()'}"/>
<handler name="onclick">
if (!datapath.selectNext()) this.setAttribute('text', 'Done')
</handler>
</button>
<button y="40" text="Stretch me" datapath="sizes:/value[1]">
<attribute name="width" value="$path{'text()'}"/>
<handler name="onclick">
datapath.setNodeText(Number(datapath.getNodeText()) + 20)
</handler>
</button>
</canvas>
|
The data property is a shorthand way of accessing data referenced by a datapointer or a datapath. For convenience, a datamapped node gets its data property set to that of the datapath it is bound to. In the example below, the color view changes its properties as the data field to which they are constrained follows the "order" attribute of the nodes in the dataset. Note that the data is a string value of the attribute; this is the case when the XPath matches an operator. The datapath of the enclosing view, however, refers to entire node in the dataset, and its data property contains an instance of LzDataNode that the XPath references. This is evident from the debugger output.
Example 36.11. Using the data property
<canvas height="150" debug="true">
<debug x="150"/>
<dataset name="onion">
<layer order="1"><layer><layer>core</layer></layer></layer>
</dataset>
<view datapath="onion:/layer">
<simplelayout spacing="5"/>
<view width="${100 / this.data}" height="${100 / this.data}"
bgcolor="0x09d055" datapath="@order"
opacity="${Math.min(1, this.data / 3)}"/>
<button text="Peel next layer">
<handler name="onclick">
with (parent.datapath) {
Debug.write(data)
if (!selectChild()) this.setAttribute('enabled', false)
else setNodeAttribute('order', Number(p.parentNode.attributes['order']) + 1)
}
</handler>
</button>
</view>
</canvas>
|
For a datapointer, a datapath, or a datamapped node, the ondata event is sent whenever the data it is bound to changes. This implies that for XPaths that select a data node, ondata event is sent only when the datapointer is set to point to a different node. If the pointer selects an operator, i.e. "text()" or "@attr" it is also sent when the text or the attribute it matches has changed. The argument sent with the event is the current value of the data property of the node or the datapointer (see previous section).
The example below makes use of the ondata event sent by a temporary datapointer to calculate the average of a sequence of accumulated numbers and display it. Then event is sent when the setXPath() method is invoked on the datapointer. Typically, a problem like this would be easier to program using Javascript's built-in arrays, but this version illustrates the data-driven approach. It also introduces the concept of data replication, which is explained in more detail later in this document.
Example 36.12. Ondata event
<canvas height="200" >
<dataset name="numbers"/>
<datapointer name="top" xpath="numbers:/"/>
<datapointer name="numptr">
<handler name="ondata" args="d">
// d is LzDataElement object
result.update(d.nodeName)
</handler>
</datapointer>
<simplelayout spacing="5"/>
<text>Type in a number and press the button or the Enter key</text>
<view>
<simplelayout spacing="10" axis="x"/>
<edittext name="input">
<handler name="onkeyup" args="k">
if ( k == 13 ) {
parent.bSend.compute();
}
</handler>
</edittext>
<button name="bSend" text="Add">
<handler name="onclick" method="compute"/>
<method name="compute">
top.addNode(parent.input.getText())
var end = top.xpathQuery('*/last()')
numptr.setXPath('numbers:/*[' + end + ']')
parent.input.clearText()
</method>
</button>
</view>
<view height="100" >
<text bgcolor="0xcecece" datapath="numbers:/*/name()"/>
<wrappinglayout axis="y" spacing="3"/>
</view>
<view>
<attribute name="sum" value="$once{0}"/>
<simplelayout axis="x"/>
<text><b>AVG: </b></text>
<text id="result" fgcolor="blue" fontstyle="bold">
<method name="update" args="v">
parent.sum += Number(v)
this.setText(parent.sum / top.p.childNodes.length)
</method>
</text>
</view>
</canvas>
|
Recall that datapointer is an object that represents a pointer to a node in a LzDataset. The datapointer can be repositioned using either cursor movements calls such as selectNext(), or by running an XPath request via setXPath().
Datapointers support a subset of the XPath specification, which uses a notation similar to the UNIX file-system to refer to nodes within a dataset. Once a datapointer is bound to a node in a dataset it will keep pointing to that node until it is moved. If the dataset is edited, the behavior of the datapointer will be controlled by its rerunxpath attribute. If this attribute is true (the default value), it will continue pointing to its current node as long as it is valid.
The rerunxpath property of datapointer determines whether the XPath expression is re-evaluated every time the contents of the dataset change. The default is false; if set to true, every time the dataset is edited, the XPath binding is refreshed. In other words, the datapointer is assumed to be "constant" unless the rerunxpath attribute is true.
Example 36.13. Using rerunxpath attribute
<canvas height="200">
<dataset name="stack">
<root/>
</dataset>
<datapointer name="top" xpath="stack:/root"/>
<datapointer xpath="stack:/root/*[1]/name()" rerunxpath="true">
<handler name="ondata" args="d">
good_result.setText(d)
</handler>
</datapointer>
<datapointer xpath="stack:/root/*[1]/name()">
<handler name="ondata" args="d">
bad_result.setText(d)
</handler>
</datapointer>
<simplelayout spacing="5"/>
<text>Type in a string and press the button or the Enter key</text>
<view>
<simplelayout spacing="10" axis="x"/>
<edittext name="input">
<handler name="onkeyup" args="k">
if ( k == 13 ) {
parent.bAdd.handler();
}
</handler>
</edittext>
<button name="bAdd" text="Push">
<handler name="onclick" >
var n = parent.input.getText()
if (!top.p['childNodes'])
top.addNode(n)
else
{
var ne = new LzDataElement(n)
top.p.insertBefore(ne, top.p.getFirstChild())
}
parent.input.clearText()
</handler>
</button>
<button name="bPop" text="Pop">
<handler name="onclick">
var last = top.xpathQuery('*[1]')
top.p.removeChild(last)
</handler>
</button>
</view>
<view height="100">
<text bgcolor="0xcecece" text="$path{'name()'}">
<datapath xpath="stack:/root/*/name()"/>
</text>
<wrappinglayout axis="y" spacing="3"/>
</view>
<view>
<simplelayout axis="x" spacing="5"/>
<text><b>TOP: </b></text>
<text id="good_result" resize="true" fgcolor="green" fontstyle="bold"/>
<text id="bad_result" resize="true" fgcolor="red" fontstyle="bold"/>
</view>
</canvas>
|
This example illustrates the effect of the rerunxpath property. The text fields at the bottom are updated when the ondata event is sent by the datapointers intended to be bound to the first node in the dataset. However, the first one is declared with rerunxpath="true", and therefore it points to the actual first data node, while the second one remembers the node it was referencing initially, and never gets updated.
By default, any view whose datapath does not match any data will not be visible. However, sometimes it is desirable to override this behavior, specifying that a datamapped view should be visible regardless of whether or not it has data. A typical example of this is a panel containing placeholder views mapped to dynamically retrieved data records, that need to be visible at all times. This is accomplished by defining the view's datapath with the dataControlsVisibility attribute and setting its value to false.
The following example illustrates the usage of this attribute. The green square view's datapath initially has no data, but its datapath is declared with dataControlsVisibility set to false, and thus it is always visible. The red square's datapath initially matches nothing, and dataControlsVisibility is left at its default value of true, and as expected, the view is not shown. But after we add another node to the dataset, the datapath has a match, and the view becomes visible. The blue square is declared with a matching datapath, so it is made visible.
Example 36.14. Visibility of datamapped views
<canvas height="150">
<dataset name="mydata">
<element>data</element>
</dataset>
<simplelayout spacing="5"/>
<view layout="axis: x">
<view name="cs" width="20" height="20" bgcolor="green">
<datapath xpath="mydata:/element[2]">
<attribute name="dataControlsVisibility" value="false"/>
</datapath>
</view>
<text text="${parent.cs.datapath.xpath}"/>
</view>
<view layout="axis: x">
<view name="cs" width="20" height="20" bgcolor="red"
datapath="mydata:/element[2]/text()"/>
<text text="${parent.cs.datapath.xpath}"/>
</view>
<view layout="axis: x">
<view name="cs" width="20" height="20" bgcolor="blue"
datapath="mydata:/element[1]/text()"/>
<text text="${parent.cs.datapath.xpath}"/>
</view>
<button text="Add data node"
onclick="mydata.getPointer().addNode('element', 'data')"/>
</canvas>
|
Lastly, dataControlsVisibility is read-only, which means that changing it at runtime has no effect, and is expected to be declared as a separate attribute.
Because data contained by static datasets is compiled into the application, it is available immediately. Therefore any datapointers that have a static dataset as part of their paths will send the ondata event before any children of the canvas are instantiated by the runtime. This is important to remember if all changes in the data need to be reflected in the application's interface. In other words, when writing handlers for ondata, one should be careful not to reference views that may not have been fully initialized.
In the example below, we attempt to expand a datamapped tree in response to the ondata event, but the tree is backed by the same data and is not yet fully initialized, since there was not enough time for databinding to occur. Thus, the openChildren() call on the first tree fails and the tree is not expanded. The solution is to move the call to the handler for oninit, which will be sent when the tree and all of its children (also trees) have finished initializing. This result of this approach is that the call succeeds and the second tree is expanded.
Example 36.15. Proper handling of data updates
<canvas height="200">
<include href="lz/tree.lzx" />
<dataset name="filesys" src="resources/dirtree.xml"/>
<class name="fs_tree" extends="tree">
<datapath xpath="filesys:/entry/@name"/>
<attribute name="autoscroll" value="true"/>
<tree datapath="*" text="$path{'@name'}"
isleaf="${this.datapath.xpathQuery('@type') == 'file'}"/>
</class>
<simplelayout axis="x" spacing="20"/>
<view width="200" height="200" clip="true">
<fs_tree id="myfs"/>
<scrollbar visible="${scrollable}"/>
</view>
<view width="200" height="200" clip="true">
<fs_tree oninit="openChildren(true)"/>
<scrollbar visible="${scrollable}"/>
</view>
<datapointer xpath="filesys:/" ondata="myfs.openChildren()"/>
</canvas>
|
On the other hand, dynamic datasets have to fetch data externally, so they may not deliver it before the visual elements that depend on it are in a stable state. This is why the logic in the code should only attempt to use these datamapped elements in response to the ondata event or by overriding the applyData method (see above). Note that the LzDataset object itself sends an ondata event whenever it receives new data; this is a convenient way of synchronizing UI operations with arrival of data it is tied to. As stated above, static datasets cause ondata to be sent as soon as they are instantiated.
Often, the LzDatapointer API provides the most convenient way to traverse the hierarchy of nodes in a dataset. Below is an example that recursively walks a dataset mapped to a tree by calling iterator methods on a datapointer initially set to the top of the dataset, and adds a new node at each level.
Example 36.16. Using datapointer's iterator methods
<canvas height="200" >
<include href="lz/tree.lzx"/>
<dataset name="filesys" src="resources/dirtree.xml"/>
<simplelayout axis="x" spacing="20"/>
<view width="200" height="200" clip="true">
<tree name="fs_tree" open="true" datapath="filesys:/entry/@name"
autoscroll="true">
<tree datapath="*" text="$path{'@name'}" open="true"
isleaf="${this.datapath.xpathQuery('@type') == 'file'}"/>
</tree>
<scrollbar visible="${scrollable}"/>
</view>
<datapointer name="dptr" xpath="filesys:/entry" />
<button text="Add a dot dir">
<handler name="onclick">
// Allow to do this only once
if (!dptr.xpathQuery('*[@name = "."]'))
traverse(dptr);
</handler>
<method name="traverse" args="top">
var ne = new LzDataElement('entry', {name: '.', type: 'dir'})
do {
if (top.xpathQuery('@type') == 'dir') {
var root = top.dupePointer();
// If this node has children, insert the dot before the first one
// and descend one level, otherwise, just add below self.
if (root.selectChild()) {
top.p.insertBefore(ne, top.p.getFirstChild())
traverse(root)
}
else top.p.appendChild(ne)
}
} while (top.selectNext())
</method>
</button>
</canvas>
|
As an essential part of their functionality, datapointers (and datapaths) can be set directly to data nodes. The example below uses the setPointer() method to set the target view's datapath to the node referenced by the datapath of the selected view. In effect, this maps the details view to the contact currently selected in the dataset.
Example 36.17. Using setPointer
<canvas height="150">
<dataset name="phonebook" src="resources/phonebook.xml"/>
<simplelayout axis="x" spacing="20"/>
<view name="contacts" height="150" width="100">
<view bgcolor="0xe0e0e0" datapath="phonebook:/contacts/contact"
onmouseover="setBGColor(0xc0c0c0)" onmouseout="setBGColor(0xe0e0e0)"
onclick="details.datapath.setPointer(this.datapath.p)">
<simplelayout axis="x" spacing="5"/>
<text datapath="@firstName" resize="true"/>
<text datapath="@lastName" resize="true"/>
</view>
<simplelayout spacing="5"/>
</view>
<view id="details" width="150" height="150" bgcolor="0xe0e0e0" fgcolor="blue">
<datapath/>
<text datapath="@firstName"/>
<text datapath="@lastName"/>
<text datapath="@phone"/>
<text datapath="@email"/>
<simplelayout spacing="5"/>
</view>
</canvas>
|
LzDatapath is a subclass of LzDatapointer, and therefore can be used in much the same way to iterate over data. The example below treats the datapath of each of the replicated view as a pointer to the dataset that backs it. The datapath of the enclosing view in this context is simply a pointer to the root of the dataset, and thus it could be used to manipulate and add children nodes.
Example 36.18. Dereferencing datapaths
<canvas height="150">
<dataset name="busy">
<Monday order="1"/>
<Tuesday order="2"/>
<Wednesday order="3"/>
<Thursday order="4"/>
<Friday order="5"/>
</dataset>
<dataset name="free"/>
<simplelayout axis="x" spacing="20"/>
<class name="schedule" height="150" width="100">
<attribute name="title" type="string"/>
<attribute name="target"/>
<simplelayout spacing="5"/>
<text bgcolor="white" fgcolor="blue" text="$once{parent.title}"/>
<text bgcolor="0xe0e0e0"
onmouseover="setBGColor(0xc0c0c0)" onmouseout="setBGColor(0xe0e0e0)">
<datapath xpath="*/name()" sortpath="@order" sortorder="ascending"/>
<handler name="onclick">
parent.target.datapath.addNodeFromPointer(this.datapath)
this.datapath.deleteNode()
</handler>
</text>
</class>
<schedule name="b" target="${f}" title="Busy" bgcolor="0xd0000a" datapath="busy:/"/>
<schedule name="f" target="${b}" title="Free" bgcolor="0x00a000" datapath="free:/"/>
</canvas>
|
There is an important restriction on usage of iterator methods with a datapath. If you move it by calling any of select...() or setXXXPointer() methods, its XPath is then removed, which means that any updates to underlying data will not notify the datamapped UI element. Consider the following example.
Example 36.19. Datapath iteration
<canvas height="150" width="250">
<dataset name="phonebook" src="resources/phonebook.xml" />
<button text="Previous" y="125"
onclick="details.datapath.selectPrev()"/>
<view name="details" options="releasetolayout" height="150">
<datapath xpath="phonebook:/contacts/contact[1]"/>
<text datapath="@firstName"/>
<text datapath="@lastName"/>
<text datapath="@phone"/>
<text datapath="@email"/>
<button text="Delete record"
onclick="parent.datapath.deleteNode()"/>
<simplelayout spacing="5"/>
</view>
<button text="Next" y="125"
onclick="details.datapath.selectNext()"/>
<resizelayout axis="x" spacing="10"/>
</canvas>
|
You can move the datapath of the contact detail view in either direction, and the text fields will update correctly. This is because their respective datapaths are unaffected by the scrolling (it only moves the datapath of the containing view). However, deleting a contact will only result in an automatic update to the text fields if no navigation has yet occurred. The solution is to reset the datapath's XPath to the proper value by calling the setXPath() method:
Example 36.20. Datapath iteration workaround
<canvas height="150" width="250">
<dataset name="phonebook" src="resources/phonebook.xml"/>
<button text="Previous" y="125">
<handler name="onclick">
with (details.datapath) {
selectPrev()
setXPath('phonebook:/contacts/contact[' + getNodeOffset() + ']' )
}
</handler>
</button>
<view name="details" options="releasetolayout" height="150">
<datapath xpath="phonebook:/contacts/contact[1]"/>
<text datapath="@firstName"/>
<text datapath="@lastName"/>
<text datapath="@phone"/>
<text datapath="@email"/>
<button text="Delete record"
onclick="parent.datapath.deleteNode()"/>
<simplelayout spacing="5"/>
</view>
<button text="Next" y="125">
<handler name="onclick">
with (details.datapath) {
selectNext()
setXPath('phonebook:/contacts/contact[' + getNodeOffset() + ']')
}
</handler>
</button>
<resizelayout axis="x" spacing="10"/>
</canvas>
|
As shown in some of the examples above, datapaths that match multiple nodes cause their nodes to be replicated. By "replicated", we mean that for each match of the XPath expression one instance of the mapped view is created. This is one of the most important features of the databinding facilities in LZX.
A replication manager is a runtime object that is created automatically whenever data replication occurs as a result of a datapath matching more than once. When that happens, the name or id attribute of the replicated view (if the view is named) is taken over by the replication manager, and from then on referring to that name will access the replication manager object, and not the view. In order to reference the replicated views, known as clones, you should use the LzReplicationManager API.
If a datapath matches multiple nodes, it will create a replication manager. If replication is normal (the default), then the replication manager will be a direct instance of LzReplicationManager. If it is lazy, it will instead create a LzLazyReplicationManager.
As mentioned above, when a view is replicated, its copies are managed by the replication manager object. Once clones are created, the instance of the replication manager contains references to them in the clones property, which is an array of views. Note that LzReplicationManager extends LzDatapath, and a cloned view along with its datapath is replaced with the replication manager object. Armed with this knowledge, we have a technique for determining when a view is cloned. The example below demonstrates the use of the clones property by declaring a handler for the onclones event on the view's datapath.
Example 36.21. Using clones and the onclones event
<canvas width="550" height="200">
<dataset name="tabnames">
<title name="Account Info"/>
<title name="Order History"/>
<title name="Preferences"/>
<title name="Shopping Cart"/>
</dataset>
<simplelayout axis="x" spacing="25"/>
<button text="Create tabs">
<handler name="onclick">
gs.pane.setDatapath('tabnames:/title')
bs.pane.setDatapath('tabnames:/title')
</handler>
</button>
<class name="repltabelt" extends="tabelement" text="$path{'@name'}" visible="true"/>
<tabslider width="150" name="gs" height="150" spacing="2">
<repltabelt name="pane">
<datapath>
<handler name="onclones">
if (!this['doneDel']) {
this.doneDel = new LzDelegate(this, 'openOH')
this.doneDel.register(clones[clones.length - 1], 'oninit')
}
</handler>
<method name="openOH">
parent.select(this.getCloneNumber(0))
</method>
</datapath>
</repltabelt>
</tabslider>
<tabslider width="150" name="bs" height="150" spacing="2">
<repltabelt name="pane">
<datapath>
<handler name="onclones">
parent.select(this.getCloneNumber(0))
</handler>
</datapath>
</repltabelt>
</tabslider>
</canvas>
|
Because the onclones event is sent when the clones attribute is set, it only signals the start of view replication, but in this example it is used to determine the exact moment when replication is finished. Since replicated views are initialized in the same order they are in inserted in the clones array, we only need to wait for the oninit event for the last clone in the list. This is necessary because initialization of the tab elements takes a non-zero amount of time, and an attempt to perform an operation on their container — tab slider — before it is completed will leave the component in an inconsistent state. For illustration purposes, the second tabslider has this problem, whereby selecting the first tab element too soon renders its parent unusable (the other tabelements are gone).
This example also takes advantage of the fact that, by default, views become visible when they consume data (see section on visibility of datamapped views above). Before the button is clicked, there is a single tabelement object within the tabslider. However, it is kept invisible until it receives data, at which point its replication occurs, and its clones are displayed.
Similarly to the clones property, LzReplicationManager maintains a list of matched data nodes in the nodes property. It is an array of LzDataElement objects that are mapped to the replicated views, and is available before any clones are created. And as with the onclones event, a handler for onnodes may be declared to respond to data replication in a custom way. The code below qualifies the value of name attribute of each replicated data node with the value of the text field, if any.
Example 36.22. Using the nodes property
<canvas height="200">
<dataset name="tabnames">
<title name="Account Info"/>
<title name="Order History"/>
<title name="Preferences"/>
<title name="Shopping Cart"/>
</dataset>
<simplelayout axis="x" spacing="25"/>
<button text="Create tabs for user:">
<handler name="onclick">
nav.pane.setDatapath('tabnames:/title')
</handler>
</button>
<edittext name="user" width="120" options="ignorelayout" y="25"/>
<tabslider width="150" name="nav" height="150" spacing="2">
<tabelement name="pane" text="$path{'@name'}" visible="true">
< |