Templates

Whitebeam templates provide specific "pre-built" functionality that enable developers to build bespoke applications quickly. The templates are designed as interlocking components which are made available to developers in the form of the Resource Object Model (ROM). The ROM is exposed through the Presentation Engine to the server side XML and JavaScript. An on-line reference provides details of all method calls and data structures.

Some fairly complex data structures are used to interface with the templates but typically very few properties are mandatory, many are optional or default to a value. A default value means that the property will be set to the stated value if a user does not supply a value. An optional value means that the current value will be used if the user does not supply a value. In both cases "not supplying a value" means not defining a property in the corresponding object data structure.

The templates generally have a "back-end" connection to a database system which they use to securely store application data. The templates provide an object-oriented view of this database and generally use/provide two important mechanisms described below.

Metadata Fields

Many Whitebeam templates include "metadata" fields that allow the data objects provided by the templates to be extended by the application designer. A metadata field is a JavaScript object container (similar to the session data container) that can contain any arbitrary JavaScript object. For example individual and OU objects in the Contacts Template support the customData metadata field that could be used to store network information alongside their name and telephone number:

user = new Object();
user.customData = new Object();
user.name = "Tom Jones";
user.phone = "0870 1664400";
user.customData.IPadd = "121.34.55.67";
user.customData.floorSocket = "A47";
user.customData.patch = "3-23";

Most template search methods support searching the metafield contents as a whole, individual developer-defined sub-objects or properties cannot be isolated and searched for on their own.

Note that, unlike session data, the system does not use hidden properties of metadata fields and so an empty metadata field (i.e. no developer defined properties set) will test equal to null.

Iterators

Many Whitebeam templates use "iterator" objects. These are used to return collections of objects when the size of the collection returned is indeterminate but could be very large e.g. the results of an item search from the Catalogue template. An iterator object is like any JavaScript object except it has one very important method defined - getNextRow(). Making this call changes the object's contents to represent the next sequential object in the collection. An example of the use of an iterator is shown below. This code fragment gets an iterator object representing all users within a particular community (Contacts template):

var user = rb.contact.whosIn(community);
while (user.getNextRow()) {
    do something;
}

Note that the method call to return an iterator only initialises the iterator object, getNextRow() has to be called to get the first item of the collection. If the iterator object is null then the end of the collection has been reached (or if the first call to getNextRow() returns null the collection is empty).