TemplatesWhitebeam 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 FieldsMany 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. IteratorsMany 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). |