Chapter 37. Data Access and Binding

Chapter 37. Data Access and Binding
Prev	Part V. Data and Databinding	Next

1. Preview of databinding

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 specific details, we'll start with a conceptual overview of how data is represented in LZX applications, and the APIs for manipulating it.

1.1. Types of data objects

A dataset (lz.dataset) 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 lz.DataElement is the LZX class that represents a single XML data tag in OpenLaszlo applications. lz.DataElements 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, lz.DataElements are linked in a tree-like structure, but that doesn't mean to say that an lz.DataElement must go inside of a dataset.

lz.DataElement is a subclass of lz.DataNode, as is lz.DataText..

Finally, note that a dataset is a subclass of lz.DataElement, which means that all of the methods which work on lz.DataElements also work on lz.datasets, although the usual method of manipulating datasets is with datapaths and datapointers, as explained below.

1.2. Two ways to interact with data

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.

1.2.1. lz.DataNodes and the DOM APIs

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

lz.DataNode is the base class for the classes that represent LZX's hierarchical data format. An lz.DataNode comprises lz.DataElements. An lz.DataElement represents a node in a hierarchical dataset. An lz.DataElement can contain other lz.DataElements, or lz.DataText, which represents a text node. More advanced data manipulation in OpenLaszlo applications employ the various methods on the lz.DataElement 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.

1.2.2. Datapointers and Datapaths

In addition to lz.DataNodes, 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.

2. OpenLaszlo datasets and data nodes

Data in OpenLaszlo applications can be declared with a tag, or built up using procedural (script) APIs. The script APIs operate on lz.DataNodes.

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 37.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 37.2. Dataset from a remote source

<canvas width="100%" height="400">
  <dataset name="menu" src="http://www.w3schools.com/xml/simple.xml" request="true"/>
  <simplelayout axis="y"/>
  <button onclick="t.setAttribute('text', canvas.menu.serialize())">Show XML data </button>
  <inputtext multiline="true" width="${canvas.width}" bgcolor="0xa0a0a0" id="t" height="300"/>
</canvas>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2007, 2008 Laszlo Systems, Inc.  All Rights Reserved.                   *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->

How is it included?	When is it loaded?	Syntax
Embedded	Compile-time	<dataset name="myData"> <myXML> <!-- ... other XML tags ... --> </myXML> </dataset>
Included	Compile-time	<dataset name="myData" src="myXMLDoc.xml"/>
HTTP data	Runtime	<dataset name="myData" request="true" type="http" src="myXMLDoc.xml" />

Prev	Up	Next
Chapter 36. Data, XML, and XPath	Home	Chapter 38. Data Replication