This tutorial describes the concept of an 'Iterator' object in the Whitebeam
System. Most templates use a database to store data representing the objects
supported by the templates. Potentially large (even as large as everything stored
in the database) amounts of data could be returned in response to certain template
calls. Iterators overcome the issues associated with potentially large amounts
of data by providing a simple mechanism for returning information about individual
objects while being able to represent the entire set of objects.
Most operations performed on Whitebeam Templates result in a reasonably small amount
of data being returned to the Presentation Page. There are some requests though that
may generate an indeterminate amount of data. Often a lot of this data is then
ignored by the Presentation Page in its generation of the users page. A good example is
a template method that performs a search
of a large set of data - for example a product catalogue. The results may be nothing
or could return every item in the catalogue. In the latter case it is highly likely that
all bar the first few items will be discarded by the Presentation Page.
It is very costly to generate a huge set of data only to then discard
the bulk of those results. The result would be slow page generation.
The Whitebeam System provides an alternative means of accessing these datasets
efficiently. Instead of generating the entire dataset and loading it into the
Presentation Engine from the template the dataset instead remains in the template
as a 'virtual' dataset. In database language the Presentation Page can access specific
rows (individual object data) within a conceptual table (the complete set of
returned data). As each row is requested the template generates the data for
that row. The Presentation Page can modify the current position within the table
at any time. In this way the template does not actually have to generate the
entire dataset. It has the freedom, for example, to just generate the first
25 rows and not do any more work until the Presentation Page requests the 26th
This process of stepping through the contents of a potentially large table
is known as 'iterating' and the mechanism by which this is achieved in the Whitebeam
that it returns an 'iterator' (see rb.page.iterateHeader
for an example) then the resulting object will allow the Presentation Page to step
through the conceptual table.
The diagram above shows the basic model for an iterator object. The object always
has exactly the
same set of methods along with a set of data
properties. Each property represents a value from one column of the conceptual row.
The properties that exist are determined by reference to a specific
data structure definition. The example of rb.page.iterateHeader specified that
the iterator properties are defined by
Think of the method as being analogous to another method that returns the entire table.
In this case the method would return an array of 'rb.page.headerinfo'. In the
case of an iterator we're returning
an iterator over an array of 'rb.page.headerinfo'
In the illustration above the method that returned this iterator would have referenced a
type having properties 'A' through to 'F'.
Reading the table rows
Once created iterators are very easy to use. Bear in mind that immediately
after it has been created the properties do not yet exist. The most common first
operation will be to call the iterators '
getNextRow' method. This causes the Presentation Engine to retrieve the
first row from the conceptual table and to store the values for that row
in the iterators properties. Occasionally you may not want to start with
the first row in the table - for example where you want to show the second 25
results of a search. In this case the call to
getNextRow' will be preceded by a call to
The call to 'setNextRow' does not load any
data into the iterator object. It tells the Presentation Engine which row should
be fetched at the next call to 'getNextRow'.
For an example of iterators in use see the documentation for rb.page.iterateHeader