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:

Binding Type	Description
ONE_TIME	Retrieves the value from the data source and initializes the target property.
ONE_WAY	Retrieves the value from the data source and initializes the target property. When the source value changes, re-initializes the target property.

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.

Attribute	Description	Required/Optional
id	Uniquely identifies the binding using a system wide unique value.	Required
dataSource	Uniquely identifies the dataSource. Also, identifies an iterator bound to an interface.	Required
select	Specifies a query string specific to the data source.	Required
type	Enumeration: ONE_TIME, ONE_WAY Default: ONE_TIME	Optional
formatter	The ID of a formatter used to format raw data before display. You can chain formatters if you require more than one.	Optional
defaultValue	The value to return when resolving text nodes or attribute values, this value will exist until the data source completes its data retrieval.	Optional

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.

Attribute	Description	Required/Optional
dataSource	Uniquely identifies the dataSource when supplied, this can be the id of a predefined dataSource or the name of any ancestor iterator. If this is left out the iterator will be relative to the immediate parent iterator.	Optional
select	Query string; data source specific.	Required
type	Enumeration: ONE_TIME, ONE_WAY Default is ONE_TIME	Optional
name	Identifies the iterator in context, can be used as the dataSource reference in sub-iterators and bind declarations. Developers should take care not to name iterators using the same name as a dataSource identifier, since this will provide undesirable results in most situations.	Optional

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:

Parameter	Description	Required
type	Binding type: ONE_TIME or ONE_WAY If not supplied, defaults to ONE_TIME	Optional
dataSource	The ID of a data source, or in the context of an iteration loop, this may be the name of an ancestor iterator. If not supplied the select will be executed relative to the parent iterator.	Required
defaultValue	The value to be returned when the data is unavailable or null.	Optional
formatter	the formatter to use to alter the data for presentation in the ui

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