A dataset (LzDataset) is two things:

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:

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

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 37, Data Access and Binding. The dataset also has APIs that pertain to data transport.

2.1.1. Interpreting a datapath

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 37.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.

2.1.2. Multiple rows of data

In the above example we used a single rowOfData node. Next, we shall use a range of all of the nodes:

Example 37.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.

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

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 37.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 42, 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.

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:

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.

6.1.1. Globally Visible Datasets

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 37.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>

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 37.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.

7.2.1. Absolute paths

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 37.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>

7.2.2. Attribute values by $path constraint

The dataset is basically an array. Assigning a node's attribute value by $path constraint, and then using the XPath expression myData:/myXML/person -- which gathers all the "person" nodes -- results in replication of the node as many times as necessary to correspond with each item in the dataset.

In this example, there are three items in the dataset, so the box node replicates three times.

Example 37.11. Assigning an attribute value by $path constraint

<canvas debug="true">

    <dataset name="boxes">
        <boxes>
         <box color="0xFF0000"/>
         <box color="0x00FF00"/>
         <box color="0x0000FF"/>
         </boxes>
    </dataset>

<simplelayout axis="x" spacing="10" />

<class name="coloredbox"  height="50" width="50" bgcolor="$path{'@color'}"/>

<coloredbox datapath="boxes:/boxes/box"/>

</canvas> 

  <attribute name='intermediate' value="$path{'degf'}" \>
  <attribute name='text' value="${Number(intermediate) * 5 / 9}" />

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 37.13. 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 37.14. 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>

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 37.15. 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 37.16. 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 37.17. 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 37.18. 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 37.19. 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 37.20. 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 37.21. 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 37.22. 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>

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.

10.1.2. Clones and the onclones event

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 37.23. 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.

10.1.3. Nodes and the onnodes event

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 37.24. 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">
      <datapath>
        <handler name="onnodes">
          if (user.text.length)
            for (var i = 0; i &lt; nodes.length ; i++) {
              var title = nodes[i].getAttr('name')
              pos = title.indexOf(':')
              if (pos != -1)
                title = user.text + title.substr(pos)
              else 
                title = user.text + ': ' + title
              nodes[i].setAttr('name', title)
            }
        </handler>
      </datapath>
    </tabelement>
  </tabslider>
</canvas>

If your application uses data replication and the data backing replicated views changes at runtime, by default the replication manager destroys and re-creates the replicated views whose data has changed. The typical scenarios when this will occur are a change in the datapath of the replicated view, or deletion/addition of rows to the dataset. Because the dataset may contain many data elements, this adjustment is often an expensive operation that results in a noticeable flicker of the user interface while view removal/creation takes place.

In order to make updates to datamapped elements more efficient, you can declare the datapath that will match multiple nodes with the pooling attribute set to true. The effect of this is that the views that have already been created as a result of replication will be reused internally, instead of re-created. Since the replication manager only needs to remap the changed data to the existing clones, data updates are reflected in UI much faster than they would be if the runtime had to create new views. Consider the following example.

Example 37.25. Using pooling to optimize data updates

<canvas height="300">
  <dataset name="phonebook" src="resources/phonebook.xml"/>
  
  <simplelayout axis="y" spacing="3"/>
  <view>
    <view name="newContact" datapath="new:/contact">
      <text>First Name:</text>
      <edittext name="firstName" datapath="@firstName" x="80"/>
      <text y="25">Last Name:</text>
      <edittext name="lastname" datapath="@lastName" x="80" y="25"/>
      <text y="50">Phone:</text>
      <edittext name="phone" datapath="@phone" x="80" y="50"/>
      <text y="75">Email:</text>
      <edittext name="email" datapath="@email" x="80" y="75"/>
      <button width="80" x="200">Add
        <handler name="onclick">
          parent.datapath.updateData();
          var dp= phonebook.getPointer();   
          dp.selectChild();
          dp.addNodeFromPointer(parent.datapath);     
          parent.setDatapath("new:/contact");         
        </handler>
      </button>
    </view>
  </view>
  <button text="Delete selected">
    <handler name="onclick"><![CDATA[
      for (var c = 0; c < all.nodes.length; ++c)
        with (all.clones[c]) {
          if (datapath.xpathQuery('@checked') == true)  {
            datapath.deleteNode()
            c--
          }
        }]]>
    </handler>
  </button>
  
  <view name="all">
    <datapath xpath="phonebook:/contacts/contact" pooling="true"/>
    <view>
      <simplelayout axis="x"/>
      <checkbox width="30" datapath="@checked">
        <handler name="onvalue">
          datapath.updateData()
        </handler>
        <method name="updateData">
          return this.value
        </method>
        <method name="applyData" args="d">
          setValue(d)
        </method>
      </checkbox>
      <text datapath="@firstName"/>
      <text datapath="@lastName"/>
      <text datapath="@phone"/>
      <text datapath="@email"/>
    </view>
  </view>
</canvas>

In the code above, we handle data removal by going through the list of data nodes, and deleting the nodes whose checked attribute is set to "true". Note how this attribute is controlled by and mapped to the value of the corresponding checkbox. Any change in the state of the checkbox results in an update to the data node attribute, and vice versa — when views are created or reused (due to deletion), the appearance of their checkboxes is unchecked because initially the attribute is not set.

This kind of syncing to the underlying data is generally required when pooling is in effect and the state of the visual elements can be changed as a result of a user interaction. In a simpler case, the UI would not be modifiable by the user, so the data flow is one way only and the views are completely data-driven, and therefore consistency of data with its presentation would be maintained automatically.

If a datapath's replication attribute is set to lazy, then a match to multiple nodes will create an LzLazyReplicationManager instead of an LzReplicationManager. This kind of replication manager is called "lazy" because it doesn't do the work of creating a view until it has to, and it does the bare minimum of work. The lazy replication manager creates only enough replicated views necessary to display the data, so there is not a view for each data node. This enables the display of very large datasets.

Because the LzLazyReplicationManager is relatively specialized, there are several restrictions on its use:

This example shows use of the lazy replication manager to display a large dataset. The replication does not create a view for each node in the dataset; rather it only creates enough views to fill the clipping view that contains it. As you click the "Make it bigger" button, you will see that more items from the list are shown. Notice also that these views are actually being created when you press the button, as you can see by then "number of subviews" value at the top of the canvas.

Example 37.26. Using a lazy replication manager to display a large dataset

<canvas height="350">
  <dataset name="vegetables">
    <celery/> <celeriac/> <carrot/> <florence_fennel/> <parsnip/> 
    <parsley/> <winter_endive/> <witloof_chicory/> <cardoon/> 
    <artichoke/> <head_lettuce/> <cos_lettuce/> <black_salsify/> 
    <swedish_turnip/> <cauliflower/> <cabbage/> <brussels_sprouts/> 
    <kohlrabi/> <broccoli/> <savoy_cabbage/> <turnip/> <radish/> 
    <water_cress/> <garden_cress/> <foliage_beet/> <spinach/> 
    <sweet_potato/> <watermelon/> <melon/> <cucumber/> <winter_squash/> 
    <marrow/> <chickpea/> <lentil/> <runner_bean/> <common_bean/> 
    <pea/> <faba_bean/> <leek/> <shallot/> <onion/> <salsify/> 
    <welsh_onion/> <garlic/> <chives/> <asparagus/> <ladyfinger/> 
    <sweet_corn/> <rhubarb/> <capsicum_pepper/> <tomato/> <eggplant/>
  </dataset>

  <simplelayout spacing="10"/>
  <text width="200" oninit="checkSubviews()">
    <handler
            name="onaddsubview" reference="replicationParent">
      this.setText('number of subviews: ' + 
                   replicationParent.subviews.length);
    </handler>
  </text>

  <view clip="true" width="100" height="100" id="clipper" bgcolor="silver">
    <view id="replicationParent">
      <text>
        <datapath xpath="vegetables:/*/name()" replication="lazy"/>
      </text>
    </view>
    <scrollbar/>
  </view>
  <button>Make it bigger
    <handler name="onclick">
      clipper.setAttribute('height', clipper.height + 50);
    </handler>
  </button>
</canvas>

See the paging.lzx example for another example of lazy replication.

Only a datapath can cause replication. Although it might seem that $path might be used to implicitly force replication, it will not. A $path expression will only yield a single value. If it matches multiple values, it is an error and it will act as if it matched none. In the example below, note that The $path constraint does not update when the enclosing datapath is set.

Example 37.27. $path does not replicate

 <canvas height="300" width="400" debug="true">
   <debug y="100" />
   <dataset name="ds">
     <data>
       <person name="a assdfasfva asdf sad" surname="a surname"/>
       <person name="b" surname="b surname"/>
       <person name="c" surname="c surname"/>
     </data>
   </dataset>
   <simplelayout axis="y"/>
   <button onclick="thedata.setAttribute('datapath', 'ds:/')">Set datapath</button>
   <view id="thedata" ondata="Debug.warn('data %#w', arguments[0])">
     <simplelayout axis="y"/>
     <view>
       <simplelayout axis="x"/>
       <text>Datapath:</text>
       <view>
         <simplelayout axis="y"/>
         <text datapath='data/person/@name' resize="true"
               ondata="Debug.warn('datapath.ondata')"
               />
       </view>
     </view>
     <view>
       <simplelayout axis="x"/>
       <text>$path:</text>
       <view>
         <simplelayout axis="y"/>
         <text text="$path{'data/person/@name'}" resize="true"
               ondata="Debug.warn('$path.ondata')"
               />
       </view>
     </view>
   </view>
 </canvas>

Sometimes you want to know the position of a view; for example, say you wanted to alternate background colors. You might think of checking for the position of the view in its oninit() method.

However, if you're using datapath pooling (you'll probably want to for long lists), the oninit events for views created by data replication don't necessarily fire because the views may be reused. In that case, the ondata event will fire, so you might consider using the ondata() handler. However, incrementing a counter isn't the most reliable way to determine order because views may not instantiate in linear order.

That's why it's better to use a datapath expression. Add attribute like this inside your replicated node:

<attribute name="pos" value="$path{'position()'}"/>

This will tie the pos attribute to the physical position in the data. You can then then tie the background color like so:

<attribute name="bgcolor" value="${this.pos % 2 == 0 ? 0x00EEEE : 0x00DDDD}"/> 

Views that you create procedurally are not the same as "clones" created by data replication. In fact, data replication overrides procedurally created views. For example:

Changes made in step 2 will be ignored after replication.