Custom Data Bindings

Advanced Tutorial - Custom Data Bindings - Creating the custom binding

SUMMARY At the end of the introduction tutorial we saw how a custom data binding was required to display localized information in the comboboxes. With the release of version 3.0 of XUI the mechanism for including these has changed. This step will take you through how to incorporate this new functionality.

FURTHER READING The chapter Data bindings in the XUI manual elaborates on this process. See also the knowledge base article at http://www.xoetrope.com/xui/kb/data/registration.

In the final localization step of the introduction tutorial we saw how the databindng for the combobox needed to be changed to use a custom XListBinding class. We will now show how to manage these custom bindings in the bindings.xml file for your project.

We'll begin by creating the custom list binding. The example we are providing here is actually a copy of the XLocalisedListBinding which can be found in the net.xoetrope.optional.data package. If you need this functionality in a project you can simply reference this class instead of creating a custom one as we are doing here. In the next steps of this tutorial we will reference the data binding in the XUI library.

Listing 1 - CustomDataBinding.java

package net.xoetrope.mortgage;

import java.util.Hashtable;
import java.util.ResourceBundle;
import java.util.Vector;
import net.xoetrope.xui.data.XListBinding;
import net.xoetrope.xui.XProject;

/**
 * A list binding that supports localization of the list content
 * 

Copyright Xoetrope (c) 2001-2007

 * $Revision: 2.8 $
 * License: see license.txt
 */
public class CustomDataBinding extends XListBinding 
{
  protected ResourceBundle languageResourceBundle;
  protected Vector keys;

  public CustomDataBinding() 
  {
      keys = new Vector();
  }
  
  /**
   * Setup and configure the binding instance. The binding is configured via the
   * XML setup registered for the particular binding type and then, subsequently
   * by attibitional attributes of the binding instance specified in the page
   * declaration, for the individual binding instance. The binding may also
   * obtain configuration or reference information from the component and the 
   * project.
   * @param project the owning project
   * @param c the component being bound
   * @param bindingConfig the XML element which contains the binding configuration
   * @param instanceConfig the XML element which contains the setup attributes of
the binding instance
   */
  public void setup( XProject project, 
                      Object c, 
                      Hashtable bindingConfig, 
                      Hashtable instanceConfig )
  {
    super.setup( project, c, bindingConfig, instanceConfig );
    languageResourceBundle = currentProject.getResourceBundle( 
		currentProject.getStartupParam( "Language" ) );
  }


  /**
   * Translate the text being added to the list.
   * @param key the key to be look up in the resourcebundle
   * @return the translated key or the key itself if no translation found
   */
  protected String translate( String key )
  {
    String ret = key;
    while ( key.indexOf( ' ' ) >= 0  )
      key = key.replace( ' ', '_' );

    try {
      ret = languageResourceBundle.getString( key );
    }
    catch ( Exception ex ) {
    }

    return ret;
  }

  /**
   * translate the text at this point
   * @param s the text to be translated
   * @return The passed String
   */
  protected String addItem( String s )
  {
    keys.add( s );
    String item = translate( s );
    listHolder.addItem( item );
    return item;
  }

  /**
   * Get the untranslated key for a list item
   * @param idx the list index
   * @return the key at the specified index
   */
  public String getKey( int idx )
  {
    return (String)keys.elementAt( idx );
  }
}

The new class extends the net.xoetrope.xui.data.XListBinding class. The setup method is of particular instance as this is called when the binding is first created. The two Hashtables which are passed as parameters provide information about the attributes which are specified in binding node in the page XML. In this case we simply call the super method and retrieve the language resource bundle for the currently selected language.

The addItem is also overloaded so that the string can be translated before it's added to the list. This takes care of the new data binding.

Now that the custom binding has been created we can now reference it in our bindings.xml file as shown below.

Listing 2 - bindings.xml

<Bindings>
  <InspectorBindings>
  </InspectorBindings>
  
  <ClassBindings>
  </ClassBindings>
  
  <InterfaceBindings>
	<Binding target="net.xoetrope.xui.XListHolder" 
class="net.xoetrope.mortgage.CustomDataBinding" type="locallist"/>
  </InterfaceBindings>
  
  <InstanceBindings>
  </InstanceBindings>
</Bindings>

The class is referenced in the InterfaceBindings node as it implements the XListHolder node. More information on the meaning of these nodes can be found in the data bindings chapter of the XUI manual.

The class attribute is set to the fully qualified name of the custom class we have created and the type attribute is set to the unique name we wish to give this type of binding. In this case the name is locallist.

We have now done enough configuration to be able to include a reference to the new custom binding in the Personal page. The adjustment is made to the personal.xml file as shown below.

Listing 3 - startup.properties

...
<Data>
	<Bind target="firstnameText" source="/mortapp/${getCustomerID()}/firstname" /> 
	<Bind target="surnameText" source="/mortapp/${getCustomerID()}/surname" /> 
	<Bind target="dobText" source="/mortapp/${getCustomerID()}/dob" /> 
	<Bind type="locallist" target="titleList" source="defaults/titleList" 
		output="/mortapp/${getCustomerID()}/title"/> 
</Data>
...