Evaluated Attributes and Helpers

Evaluated attributes provide a powerful way of extending the scope and range of what Aria can do. Take for example a simple data binding where a single source node is mapped to say an edit field. On its own this binding is limited, but if we use an evaluated attribute then we can control what is displayed each time the binding is updated, and earlier (Callbacks.) we saw an example of this dynamic data binding.

Evaluated attributes offer a great deal of power and reinforce the idea of the Model-View-Controller architecture by providing a means to insert links between the various components without hard wiring of these links.

Evaluated attributes

First of all, to recap what an evaluated attribute is and how it works lets look at a very simple example.

Basic attribute evaluation

 <Button name="DecBtn" x="178" y="43" w="42" h="20" content="${getContent()}"/>

The code ${getContent()} is an expression that is evaluated at runtime each time the expression is encountered. For a page component declaration the expression is evaluated when the page is loaded.

Expressions can be used in other locations such as within the data model, the data bindings, the validations or the event bindings.

Arguments allowed in XML attribute method calls

The XML description of pages has been able to support method calls for the evaluation of attributes since version 1.0.3. These method calls now support method arguments. Arguments of int and String types can be included. For example:

An Evaluated Attribute

 <Bind target="connSizeSt" source="${getNodeValue(3)}" unique="true"/>

This example dynamically binds a value to the connSizeSt component. The implementing page should then contain the method

A Handler for an Evaluated Attribute

 public String getNodeValue( int NodeID ) 
{ 
... 
}

The implementation of this method should return a String that can be used as the source attribute of the original XML Bind element.

The advantage of this method call is that the same page definition can now be reused and bound to different parts of the data model. A simple example of this might be where a popup dialog is used to show details of say a person in some business model. Such a person entity could be a manager, an employee or a visitor/guest and as such the data for each of these entities would exist in different parts of an organizational hierarchy.

Library expressions

In Aria 2.0 The attributes can also be defined in classes other than the current page or classes derived from Page . The syntax for such expressions is as follows:

where mypackage is the name of the Java package containing the class MyClass . The value of referenceName is a user defined value that identifies the instance of the class. The application instantiates an instance of the class when the expression is first encountered and thereafter maintains the instance with each subsequent call retrieving the same instance of the class. As in early versions, the method call can also contain zero or more arguments. For an example of this please see Evaluated attributes.. Library expressions can be used in the specification of component attributes, events and for data bindings.

Expression evaluators

The expressions are evaluated by an ExpressionEvaluator and each page has by default its own instance of the default expression evaluator. (The default evaluator delegates storage of the referenced classes to the project). However, the page allows this evaluator to be replaced and a different evaluator can be inserted with a call to the AriaBuilder.setAttributeEvaluator method. This replaceable evaluator allows a route to include other expression evaluators such as interpreters. Therefore if the capability of the built in evaluate is insufficient you can replace or extend the default evaluator. As an example a prototype evaluator for the Groovy language has been created.

Using evaluated attributes

OK, so we have seen how the attributes of an XML file can in fact be callbacks to methods in your page class or in some other class. What does this mean for the application?

Essentially this means that the model is dynamic, it can be adapted to meet the changing needs of your application as a session progresses. You are not restricted to the setup encoded in the XML at start-up.

The dynamic model also means the data structure specified in the XML (or in your code for that matter) can be mapped from one instance to another via the evaluated attributes and callbacks. We have already seen how this could be use with something as simple as an address form.

Evaluated attributes also make it possible to apply more advanced techniques like filtering data and providing access control. Once you get to grips with the basic functionality you should find the use of evaluated attributes a very powerful mechanism.

From an achitectural point of view the use of evaluated expressions means that you can create a user interface with XML with very little dependancy upon the Java code. The page does not need to be derived from a custom class as you logic can be embedded in some other hierarchy.

The use of library functions also promotes reuse as the code can be freed of some of the page specific constraints. Late binding also opens up further possibilities for dynamically matching code to the user interface and providing different levels of functionality or strategies for different situations or even for different users.

The on-line mortgage tutorial uses library methods to implement its page navigation. In the pre 2.0 versions the navigation required a special page to implement this behavior and therefore the navigation page became tied to the navigation class which was undesirable if you wanted to use features of another page class (assuming that the navigation is only a small part of the page's functionality). With the new library functions the navigation features can be added as mix-ins with very few special requrements.

The added flexibility of this arrangement should make it possible to build reusable functionality that can be dropped in to various points of your application.

Escape sequence for path attribute values

When searching for a model node it is possible to specify an attribute value to distinguish between nodes with the same parents. For example:

A Model Path and Attribute

 model.get( "products/software/vendor@name=Formaria" );

This searches for a node where the vendor has a name attribute of Formaria . Sometimes, for instance when handling code numbers or article numbers, the attribute may include forward slashes. These slashes can cause problems when trying to identify various parts of the path and therefore an escape sequence has been added to allow attributes with slashes to be used in searches. Such a search would appear as:

A Model Path and a Specified Attribute

 model.get( "products/tyres/vendor@name=michelin/size@value=[R14/500]" );

In the above example the search is for a tyre from the michelin vendor and with a size of R14/500 .

Handling evaluation exceptions

An exception handler has been added to the attribute evaluator. The handler gets called in case of an exception and can override the result returned by the attribute evaluator. The evaluator may be of use in case, for example, an evaluation depends on a list selection and where that list may not have a selected values - the list would otherwise return a value such as null or -1 to indicate the error and this is probably not a valid value for the evaluated attribute. Say a path of a/b/${c}/d/e is enetered and ${c} depends on say a list selection and that list is not fully initialized.

TODO add example code

An example

To illustrate the use of evaluated attributes a dialog with dynamically loaded text will be displayed. The text to be loaded comes from an extrenal HTML file as it is too large to be embedded in the page XML or the language resource bundles.

First of all lets look at the XML:

Setting the text via a callback function

 <Page class="org.formaria.demo.About" padding="10">
   <Components>
     <Image x="526" y="0" w="74" h="30" imageName="danfoss.gif" />
     <ScrollPane x="10" y="50" w="600" h="250" style="base/info" border="0"
            vertical_scrollbar="as needed" horizontal_scrollbar="never">
       <Label x="10" y="50" w="600" h="400" content="${getExtraText(terms)}" 
		style="base/info"/>
     </ScrollPane>
     <ImageButton name="closeBtn" x="510" y="310" w="100" h="28" 
		style="GraphicButton" text="OK" 
        imageName="button.png" rollover="button_over.png" 
		pressed="button_pressed.png"/>
   </Components>
   <Events>
     <Event method="closeDlg" target="closeBtn" type="ActionHandler"/>
   </Events>
 </Page>

Then in the about class the referenced method is implemented:

Implementingthe evaluated method

 public class About extends Dialog
 {
   public About()
   {
   }
 
   /**
    * Get the text for a popup from an extra file
    * @param fileName the argument from the XML file
    */
   public String getExtraText( String fileName )
   {
     // Get the default language from the preferences
     Preferences rsPrefs = Preferences.userNodeForPackage( Welcome.class );
     String defLangCode = rsPrefs.get( "defaultLanguage", "en" );
 
     // Build the path to the file - use a separate sub folder for each language
     String filePath = defLangCode + File.separator + fileName + ".html";
     try {
       // Open and read the file
       Reader r = project.getBufferedReader( filePath );
 
       StringBuffer text = new StringBuffer();
       int BUF_LEN = 1024;
       int len = -1;
       char buffer[] = new char[ BUF_LEN ];
       while (( len = r.read( buffer, 0, BUF_LEN )) >= 0 ) 
         text.append( buffer, 0, BUF_LEN );
 
       // Now return the text
       return text.toString();
     }
     catch ( Exception e ) 
     {
       e.printStackTrace();
     }
 
     // The resource was not loaded for some reason
     return translate( "Missing resource" );
   }
 }

With just a few lines of reusable code it is now possible to load content from a variety of sources much in the manner of templates. In fact, the above method has little need to reside in a page class and could just as easily reside in a library class further extending the resuability of the evaluated attribute.

The results of this coding can be seen below: