A dataset represents an XML document containing data for the application. A dataset tag can embed the data (like in this example), or point to an external resource as we will discuss later in this tutorial. You can define multiple datasets inside a single application. The dataset is also the cornerstone for OpenLaszlo's data binding API.

The data binding API allows user interface components to be automatically populated with data. For each user interface component, you use the datapath attribute to specify which data the component should display. The value of the datapath attribute is an XPath expression. XPath expressions use a simple URL-like notation to navigate through the hierarchical structure of an XML document. The expression is made of the name of the dataset, followed by a colon and the path to the desired tag. You use /text() to display the data value of a tag (comments 1 to 2), or @attribute_name to display the value of a tag attribute (comment 2).

To make your code easier to read and maintain, you can bind a container view to a particular node and then bind the user interface components inside the view using a relative address.

<view name="list" datapath="dset:/phonebook/contact">
  <simplelayout axis="x"/>
  <text datapath="firstName/text()"/>
  <text datapath="lastName/text()"/>
  <text datapath="phone/text()"/>
  <text datapath="email/text()"/>
  <text datapath="@category"/>
</view>

Laszlo makes it easy to manipulate and display multiple rows of data. If the XPath expression points to more than one node in the XML document, bound user interface components are repeated for each node.

Example 38.2. binding data to views

<canvas height="50" width="700" bgcolor="#D4D0C8">
  <dataset name="dset">
    <phonebook>
      <contact category="friends">
        <firstName>John</firstName>
        <lastName>Smith</lastName>
        <phone>617-536-7855</phone>
        <email>[email protected]</email>
      </contact>
      <contact category="business">
        <firstName>Mary</firstName>
        <lastName>Jones</lastName>
        <phone>415-534-1186</phone>
        <email>[email protected]</email>
      </contact>
      <contact category="friends">
        <firstName>Lisa</firstName>
        <lastName>Brown</lastName>
        <phone>212-423-1132</phone>
        <email>[email protected]</email>
      </contact>
    </phonebook>
  </dataset>
  <simplelayout axis="y"/>
  <view name="list" datapath="dset:/phonebook/contact">
    <simplelayout axis="x"/>
    <!-- 1 -->
    <text datapath="firstName/text()"/>
    <text datapath="lastName/text()"/>
    <text datapath="phone/text()"/>
    <text datapath="email/text()"/>
    <text datapath="@category"/>
  </view>
</canvas>

XPath also supports a one-based index notation to limit the number of nodes retrieved by an expression. You can experiment with the following XPath expressions for the datapath attribute of the list view (comment 1).

At this point, the data for the phonebook application is embedded in the application source code. This is appropriate for static information that is not reused across applications. However, in most cases, externalizing the data from the application source code is a better approach.

First, we create an XML document called phonebook.xml containing the data for the phonebook application:

phonebook.xml:
<phonebook>
  <contact firstName="John" lastName="Smith" phone="617-536-7855" 
           email="[email protected]"/>
  <contact firstName="Lisa" lastName="Jones" phone="415-225-8743" 
           email="[email protected]"/>
  <contact firstName="Mary" lastName="Brown" phone="212-665-5211" 
           email="[email protected]"/>
</phonebook>

We can now remove the data from the source code of the phonebook application, and make the dataset point to the phonebook.xml file:

Example 38.3. using an external dataset

<canvas height="50" width="700" bgcolor="#D4D0C8">
  <dataset name="dset" src="../phonebook.xml"/>
  <simplelayout axis="y"/>
  <view name="list" datapath="dset:/phonebook/contact">
    <simplelayout axis="x"/>
    <text datapath="@firstName"/>
    <text datapath="@lastName"/>
    <text datapath="@phone"/>
    <text datapath="@email"/>
  </view>
</canvas>

Note

Due to a limitation of the OpenLaszlo documentation system, relative paths to referenced files (for example, ../phonebook.xml) are problematic in example programs. Examples that work inline don't work when you edit them. This is because when you press "edit" on an example in the documentation, a new instance of the example program is created. This new instance is in a different spot than the original, so relative paths are incorrect, and the example breaks. A work around for editing examples like the above is to copy and paste the example and any supporting files to your working environment.

To update a dataset based on information entered in bound user interface components, you invoke the updateData() method on the datapath object (comment 2a). updateData() simply copies the data from the bound user interface components back to the dataset.

To delete a node in a dataset, you invoke the deleteNode() method on the datapath object (comment 2b).

Before looking at how a datapointer can be used to add a node to a dataset, we set up the user interface to allow the user to enter a new contact.

Example 38.5. UI for adding new contact

<canvas height="400" width="700" bgcolor="#D4D0C8">
  <dataset name="dset" src="../phonebook.xml"/>
  <simplelayout axis="y"/>
  <view>
    <simplelayout axis="y"/>
    <!-- 1 -->
    <text onclick="parent.newContact.setVisible(!parent.newContact.visible);">New Entry...</text>
    <!-- 2 -->
    <view name="newContact" datapath="new:/contact" 
          visible="false" x="20" height="120">
      <text y="10">First Name:</text>
      <edittext name="firstName" datapath="@firstName" x="80" y="10"/>
      <text y="35">Last Name:</text>
      <edittext name="lastname" datapath="@lastName" x="80" y="35"/>
      <text y="60">Phone:</text>
      <edittext name="phone" datapath="@phone" x="80" y="60"/>
      <text y="85">Email:</text>
      <edittext name="email" datapath="@email" x="80" y="85"/>
      <button width="80" x="200" y="10">Add
        <handler name="onclick">
          parent.parent.datapath.updateData();
        </handler>
      </button>
    </view>
    <!-- 3 -->
  </view>
  <view datapath="dset:/phonebook/contact">
    <simplelayout axis="y"/>
    <view name="list" 
          onclick="parent.updateContact.setVisible(!parent.updateContact.visible);">
      <simplelayout axis="x"/>
      <text datapath="@firstName"/>
      <text datapath="@lastName"/>
      <text datapath="@phone"/>
      <text datapath="@email"/>
    </view>
    <view name="updateContact" visible="false" x="20" height="120">
      <text y="10">First Name:</text>
      <edittext name="firstName" datapath="@firstName" x="80" y="10"/>
      <text y="35">Last Name:</text>
      <edittext name="lastname" datapath="@lastName" x="80" y="35"/>
      <text y="60">Phone:</text>
      <edittext name="phone" datapath="@phone" x="80" y="60"/>
      <text y="85">Email:</text>
      <edittext name="email" datapath="@email" x="80" y="85"/>
      <button width="80" x="200" y="10">Update
        <handler name="onclick">
          parent.parent.datapath.updateData();
        </handler>
      </button>
      <button width="80" x="200" y="40">Delete
        <handler name="onclick">
          parent.parent.datapath.deleteNode();
        </handler>
      </button>
    </view>
  </view>
</canvas>

When the user clicks the "New Entry" text at the top of the contact list (comment 1), the newContact view (comments 2 to 3) is displayed. The newContact view is similar to the updateContact view except that its datapath attribute is set to "new:/contact". This creates a new temporary dataset with an empty contact node.

If you run the application, you will notice that when you click the Add button, the new contact is not added to the list of contacts: we still have to add the new contact node defined in the temporary dataset to the main dataset (dset). We use a datapointer to perform this operation.

A datapointer is a pointer to a specific node in a dataset. You typically use a datapointer when you need to manipulate data programmatically. A datapointer can only point to one node in the dataset at a time, but you can define multiple datapointers, each pointing to a different node in the dataset.

Let's modify the event handler of the Add button with the code required to add the new contact node to the dset dataset:

<handler name="onclick">
  parent.datapath.updateData();
  var dp=canvas.datasets.dset.getPointer();   // 1
  dp.selectChild();                           // 2
  dp.addNodeFromPointer(parent.datapath);     // 3
  parent.setDatapath("new:/contact");         // 4
</handler>

Example 38.7. Using <onclick> method to add new contact

<canvas height="400" width="700" bgcolor="#D4D0C8">
  <dataset name="dset" src="../phonebook.xml"/>
  <simplelayout axis="y"/>
  <view>
    <simplelayout axis="y"/>
    <!-- 1 -->
    <text onclick="parent.newContact.setVisible(!parent.newContact.visible);">New Entry...</text>
    <!-- 2 -->
    <view name="newContact" datapath="new:/contact" 
          visible="false" x="20" height="120">
      <text y="10">First Name:</text>
      <edittext name="firstName" datapath="@firstName" x="80" y="10"/>
      <text y="35">Last Name:</text>
      <edittext name="lastname" datapath="@lastName" x="80" y="35"/>
      <text y="60">Phone:</text>
      <edittext name="phone" datapath="@phone" x="80" y="60"/>
      <text y="85">Email:</text>
      <edittext name="email" datapath="@email" x="80" y="85"/>
      <button width="80" x="200" y="10">Add
        <handler name="onclick">
           parent.datapath.updateData();
           var dp=canvas.datasets.dset.getPointer();   
           dp.selectChild();                           
           dp.addNodeFromPointer(parent.datapath);     
           parent.setDatapath("new:/contact");         
         </handler>
      </button>
    </view>
    <!-- 3 -->
  </view>
  <view datapath="dset:/phonebook/contact">
    <simplelayout axis="y"/>
    <view name="list" 
          onclick="parent.updateContact.setVisible(!parent.updateContact.visible);">
        <simplelayout axis="x"/>
        <text datapath="@firstName"/>
        <text datapath="@lastName"/>
        <text datapath="@phone"/>
        <text datapath="@email"/>
    </view>
    <view name="updateContact" visible="false" x="20" height="120">
      <text y="10">First Name:</text>
      <edittext name="firstName" datapath="@firstName" x="80" y="10"/>
      <text y="35">Last Name:</text>
      <edittext name="lastname" datapath="@lastName" x="80" y="35"/>
      <text y="60">Phone:</text>
      <edittext name="phone" datapath="@phone" x="80" y="60"/>
      <text y="85">Email:</text>
      <edittext name="email" datapath="@email" x="80" y="85"/>
      <button width="80" x="200" y="10">Update
        <handler name="onclick">
          parent.parent.datapath.updateData();
        </handler>
      </button>
      <button width="80" x="200" y="40">Delete
        <handler name="onclick">
          parent.parent.datapath.deleteNode();
        </handler>
      </button>
    </view>
  </view>
</canvas>

You need a relational database and a JDBC driver to perform this section of the tutorial.

For this example, we create a single JSP that handles inserts, deletes, and updates.

contactmgr.jsp:

<%@ page import="java.sql.*"%>
<%
    Connection connection = null;
    try {
        String action=request.getParameter("action");       // 3
        String firstName=request.getParameter("firstName");
        String lastName=request.getParameter("lastName");
        String phone=request.getParameter("phone");
        String email=request.getParameter("email");
        String pk=request.getParameter("pk");               // 4

        Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");
        connection = DriverManager.getConnection("jdbc:odbc:laszlosamples"); // 1
        String sql="";      // 2

        if (action.equals("insert")) {
            sql="INSERT INTO contact (first_name, last_name, phone, email) VALUES ('"+
                                     firstName+"','"+lastName+"','"+phone+"','"+email+"')";
        } else if (action.equals("update")) {
            sql="UPDATE contact SET first_name='"+firstName+"', last_name='"+lastName+
                                     "', phone='"+phone+"', email='"+email+"' WHERE email='"+pk+"'";
        } else if (action.equals("delete")) {
            sql="DELETE FROM contact WHERE email='"+pk+"'";
        }

        Statement stmt = connection.createStatement();
        System.out.println("*** Executing SQL: "+sql);
        stmt.executeUpdate(sql);
%>
        <result>success</result>
<%
    } catch (Exception e) {
        e.printStackTrace();
%>
        <result>failure</result>
<%
    } finally {
        try {
            connection.close();
        } catch (SQLException e) {
        }
    }
%>

In this example, we use Sun's JDBC-ODBC bridge to access the database:

This JSP expects 6 parameters from the OpenLaszlo client application (comments 3 to 4).

contactmgr.jsp returns a simple success xml document if the requested operation succeeded and failure if the operation failed. To check for the success or failure of the operation in the client application, you can define an event handler for the ondata event of the dsSendData dataset. In this event handler you use a datapointer to check for the value of the tag.

<datapointer xpath="dsSendData:/">
  <handler name="ondata">
    if (this.xpathQuery("result/text()") == "success") {
      Debug.write("Operation succeeded");
    } else {
      Debug.write("Operation failed");
    }
  </handler>
</datapointer>