AribaWeb MetaUI Explained - Part 1

Introduction
AribaWeb is a full stack Java Ajax framework for developing applications, mostly on the web. It comes with so many features and tools so the issues you would have to deal with in your day to day web development is already sorted out.
Among its many features it the ability to generate your UI from metadata defined in stylesheet like OSS files and also from annotations defined on your classes.
This is very beautiful because you can generate different UI based on the device or the context in use. One very practical application is for web applications that will have to run on mobile devices - and this is the area I want to explore most once I have full grasp on AribaWeb. You can read more about AribaWeb (AW) from here.

For now we want to explore one of the stacks of AribaWeb that is very confusing but very very useful once you get a hang of it. I am also new to AW and this is part of my exploration into AW to understand and use it properly. This is therefore not a perfect explanation but my understanding of the technology from reading this document - MetaUI-InDepth
 

Assertion and Concepts

Most of the UI code written in traditional frameworks is a mechanical application of (unstated) rules rooted in the domain object data model.
With AW, the Objects , Business rules and Contexts can directly influence presentation without redesigning of the application.


What is a Rule
Rule defines a map of properties that should apply in the event that a set of conditions  evaluate to true. These Conditions are reffered to as Selectors. For example, Suppose we want to use MetaUI to affect the presentation of our firstname field in our com.farouk.alhassan.User object, we will write some conditions(Selectors) like this:
class=com.farouk.alhassan.User{
      feild=firstname{
         visible:true;
         //Add More
      }
}
The above is what in AW terms we call a rule. AW evaluates the conditions('Equal to' sections of the code), from now on called Selectors, and nicely selects the firstname feild. From that, AW creates a Map which is just a key-value stack for this particular feild and applies those properties when generating the html. More on these when we get to rules syntax!

Sources of Rules
- Rules can come from various source including Introspection, Annotation, .OSS files and from plugged in External sources.

Rules form Introspection
In AW, if you are using the MetaUI stack, then AW uses the datatypes of the feilds and other properties to generate  Rules for your feilds. Say you have this class:

   class DemoObject{
       BigDecimal price
       String description
  }

AW MetaUI uses introspection to know that price is a BigDecimal an so defines rules that apply the money formatter to it. By defining the datatype of your description feild as String, AW by default uses the AWTextFeild Component. So just by introspection, without you making any specific rules, you get a presentation UI generated on the fly for you. Now how cool is that!!!

Rules from Annotations
AW also generate rules based on annotations defined on the members of a class. Some accetable annotations that AW uses include
@Traits
@Trait
@Properties
@NavModuleClass

and some more.
check out tthis package for more annotations and how they affect your UI.

    ariba.ui.meta.annotations

Rules from .OSS files

AW uses rules defined in files called OSS files to derive the view for the browser. Literally, it means AW uses these rules to generate the HTML presented to the browser. AW comes with Rules defined in WidgetsRules.oss file in the folder

src/metaui/ariba/ui/meta/layouts

and in PersistenceRules.oss

src/metaui/ariba/ui/meta/persistence

 Normally, to avoid conflicts with AW merges, you would normally not modify these unless its critical to your application.
Application specific rules can only be defined in two files:

1. Application.oss: This file must live in the app folder . The filename is case sensitive. The rules in this file by practice defines global rules that affect the whole application.

2. rules.oss: This is per class/package based rules and is located in the package for which it affects. So if I have

com.farouk.alhassan

then the rules.oss go into

com/farouk/alhassan

Some Data Type Rules
These are the default rules that apply to some datatypes:
Type                                      Component Used
Money(BigDecimal)               AWTextField with Money formatter
Date                                      DateField
Entity                                     AWChooser (Combo Box)
List                                        Chooser that allows Multiple selection.

Some Definitions
1. Context:  Context represents a stack of assignments (e.g. class=User, field=birthDay, operation=edit) that together form a PropertyMap for the presentation. An example is illustrated bellow. Think of the context as the current environment within which a class, field or component find itself. Within this environment, there can be values assigned to various properties of the environment. These together form a PropertyMap which is then applied to generated User Interface. Eg

2. Context Keys and Property Maps: Context keys are the keys used for the matching condition or selector to select the rules to apply. Property Map is the key value pair that is assigned after a match has been made base on the selector. Generally, Context keys are used to select and PropertyMap is then used to assign values to the Property keys. The PropertyMap come into play once the context keys have been used to make a selection or literally, a match has been made from the 'equal to' section. Just for emphasis, think of context keys as decision makers and PropertyMaps as the values to be assigned now that a decision has been made.
Some Context keys
Here are some of the common context keys :
* module ------Global Nav Tab. When you define this, you get a Navigation tab
*layout---------Defines a named layout.
*operation-----Can be either “view”, “edit”, “create”, “search” NB: Maybe you can add more??
*class----------Full class name (org.package.Class), Can be derived from object
*object---------Object instance (e.g. a User object)
*action---------Maps a named action on the page to an action defined on class
*field-----------current field of class
*type-----------(Java) type of current field
*elementType--If type is collection(eg List), the type of its elements
*editing--------Currently editing? Derived from operation
*trait-----------Current traits in effect (like CSS classes)

As you would expect or should know, every map is made of key and the keys should be known and defined before it's values can be retreived.
With regards to our PropertyMap, here are some of the common Property Keys

These can be used on any entity ie the feild or member that was selected by the selector conditions
*trait------------------List of traits to apply. Datatype: List of String
*after-----------------Name of item (or zone) that this item should follow (for layout order). Datatype: String
*visible---------------Should current item be shown. Datatype: boolean or reslove to boolean
*component----------AW Component name to display. Datatype: AWComponent
*bindings-------------Map of bindings to pass to component. Datatype: Map
*wrapperComponent--Name of component to wrap around this component (also, wrapperBindings). Datatype: AWComponent

This can only be used with Layout, Module, Field, Action entities
*label---------------the Display Key ie what gets displayed. Datatype: String

These can be used only if what was selected is a Field
*editable------------Should the feild be editable. Datatype: boolean or reslove to boolean
*valid---------------is the curent value valid. Datatype: boolean or reslove to boolean

These can be used only if what was selected is a Layout
*layoutsByZone-----List of sub-layout names grouped by zone(zTop, zLeft, …)

These can be used only if what was selected is an Action
actionResults--------AWResponseGenerating result: fires action

Rules Chaining
As you would expect, after an entity has been selected by the selectors defined, some-not all-context keys can be used to define selectors that will select sub entities of the current entity.
Example

operation=edit{
        class=model.User{
          feild=password {
           type=String{
              trait=secret{
                editing{
                 component:AWPasswordFeild;}
                }
             } 
          } 
   }
 }

In the above example, even though component, is a context key, it is nested inside another another property making it behave as a property key. This results in a chaining effect called Rules Chaining or Nesting.
The following are context keys that can work as property keys
* class
* type
* elementType
* trait
* editable
* editing
* layout
* component.

3.MetaContext
MetaContext allows an AW component to overide the current values defined for some context keys. this is done by defining the tag within the .awl file.
Example:

      <m:context layout="Inspect" object="$user" operation="edit">
        <m:includecomponent>
     </m:includecomponent></m:context>

Here the object, layout and operation  context key for the current context are overridden for the current component.
The Context API defines the following Bindings for that can be used with
valueMap:   This is a map of actual context key/values.  It's an alternative way to pass in context key/values. Useful when the list of context key/value are generated dynamically.
scopeKey: This is a context key, but it is usually not specified in any OSS files, and users don't need to worry it.  It is used to narrow down on rule matches.
pushNewContext:This is a boolean flag pass to MetaContext to determine if a new context object needs to be created.

UPDATE 1: Corrections have been made to reflect feedback from Mailing list on  12th June, 2009


Coming Up!

Rule Syntax. Time to Understand them.--Watch out for Part 2.


NB: This document is not complete. It is based purely on how I understood the above referenced document from Craig Federighi. You are welcomed to challenge and/or correct any part of this via comments, the AW mailing list or by email to me. You will find me on the AW Google Groups forums.