Data Binding

Binding and Iterator tags

Binding

A binding defines a map for connecting data sources and query strings to bound targets (UI DOM attributes/nodes) and identifies the formatters and validators to apply to the data flowing from the data source.

Binding Types

The following binding types are supported for binding and iteration in the data service plugin: 

Data sources may specify what binding types they support, all data sources must support at least ONE_TIME binding.

Binding Tag

The binding tag allows a pre-defined binding to a data source which can be used to bind common values to multiple targets in the UI without writing the definition multiple times in binding declarations.

Usage

Binding Data using the binding tag

To bind data, you declare a binding and then associate it with one or more user interface components.  You can bind data to any text child or attribute value within the UI DOM.

The following example declares a binding that counts the number of customer elements under the customers root node.  Additionally, it references a formatter that modifies the data before display:

<binding id="customer-count" dataSource="customers" 
  select="count(/customers/customer)" formatter="customers" 
  type="ONE_WAY" />

To use this binding:

You place a reference to the data binding in the UI document where normally you place the actual data.  The following example displays a label that contains the customer count:

<label text="{ bind( binding://customer-count ) }"

You can bind multiple controls to the same data source.  When the data source gets updated, any one way type binding also gets updated.

Iterators

Iterators give you the flexibility to create complex UI structures based on data sets.  This functionality allows complex aggregate UI components such as listboxes, comboboxes, tables, and charts to be configured.

To perform iteration, you use the iterator tag.

With it, you can loop over a DataSet retrieved from a dataSource, replicate the contents of the iterator tag definition in place for each item in the set, and append the items in the dataset to the parent of the iterator tag at the iterator's position. 

In addition, you can do nested iterations.

Usage

Binding Wtih Iterators

This example creates a table and iterates over a DataSet, creating a row for each entry.

 <table>
 <column><header name="First Name" /></column>
 <column><header name="Last Name" /></column>
 <column><header name="Phone Number" /></column>
 <iterator dataSource="customers"  
  select="/customers/customer"  type="ONE_WAY" />
  <row>
   <!--refers to parent iterator -->
   <cell text="{ *('firstName') }" />
   <!--refers to parent iterator -->
   <cell text="{ *('lastName') }" />   
   <!--refers to parent iterator -->
   <cell text="{ *('phoneNumber') }" />  
  </row>
 </iterator>
</table> 

Data Service Binding

Requires Platform 4.2+ and Data Service Plugin

This document describes the declarative syntax for using the com.nexaweb.data.DataService interface for binding data to the UI. The com.nexaweb.data.DataService interface is a system service provided through a plug-in. See the Data Service Plugin API javadoc for more information.

The following methods are exposed for binding data to the UI using the "DataService" system service.

Important: The following methods return generic Objects that can be used with the text resolution syntax or as method call arguments.

DataService.bind( 'bind-string' )

Bind using the specified bind-string.

where bind-string: a semi-colon delimited list of parameters.

where Parameter format: name/value pairs separated by equals (name=value).

The following table lists the supported parameters for the bind-string:

Example

<label text="{ bind('dataSource=myDataSource; select=/customers/customer[0]@name; type=ONE_WAY') }"/>

Registered Shortcut

bind
bind=DataService.bind

DataService.bind( binding://binding-id )

Bind using the binding definition with ID binding-id.

Example

<label text="{ bind(binding:myBinding) }"/>

Registered Shortcut

bind
bind=DataService.bind

DataService.relativeBind( 'select' )

Bind using the specified select string. The binding executes against the data source for the closest iterator ancestor, supplying the current iteration data as the context for the select.

Example

<data:iterator dataSource="myDataSource" select="/customers" 
     xmlns:data="http://openxal.org/core/data">
  <label text="{ *('customer[0]@name') }"/>
</data:iterator>

Registered Shortcut

*
* for DataService.relativeBind

DataService.relativeBind( 'iteratorNameOrDataSourceId', 'select' )

Bind using the specified select string. The binding executes relative to the current iteration of the iterator ancestor named iteratorNameOrDataSourceId, or directly against the specified data source with id iteratorNameOrDataSourceId without context.

Example:

<data:iterator name="topIterator" dataSource="myDataSource" 
     select="/customers" xmlns:data="http://openxal.org/core/data">
	<label text="{ *('topIterator', 'customer[0]@name') }"/>
</data:iterator>

Registered Shortcut 

*
* for DataService.relativeBind