Contents 

• Overview
• Status/Error Conditions from Templates

Overview 

In the Whitebeam architecture the user interface is generated by a set of 'Presentation Pages'. The Whitebeam System uses these presentation pages to dynamically generate the HTML pages that an end-user sees at a Web Browser. There are many potential ways in which this dynamic server-side behaviour can be achieved, common examples include various scripting languages such as Perl and Tcl/Tk or binary executables using the Common Gateway Interface (CGI). The Whitebeam system uses a mixture of additional XML tags and Server-Side JavaScript. The JavaScript language is identical to that supported on the Client Side in common browsers such as NetScape and Internet Explorer reducing the learning curve for Integration Partners. 

JavaScript provides a basic syntactical and sematic structure for controlling flow of execution and for generically accessing user defined application programming interfaces (API). By itself the language definition doesn't really do anything. To be useful an application has to have a way of using the language to interract with an underlying system. In client side JavaScript this is achieved through a Document Object Model (DOM). The Whitebeam system defines a similar object model, called the 'Whitebeam Object Model'. The object model defines a set of 'standard' methods and sub-objects that are always available along with a set of definitions that are specific to the business templates being used by the client. This document describes the core (always present) elements of the Whitebeam Object Model. 

The following core definitions always exist. 

Status and Error Conditions 

The interface to each template is described individually. Each template is characterised by an API held within a portion of the Rebourne Object Model. The API description describes for each method what parameters are expected and what error conditions can occur. The Whitebeam architecture provides a fairly generic status reporting mechanism that can be used by the templates, this mechanism is the subject of this section. 

The 'Whitebeam' object (rb) has a property called status. By default this contains the value 'rb.rb$ok' - a non-error condition. Each method may write a status value to this property that can then be inspected by the javascript presentation page. Note though that one page cannot overwrite an error condition with rb.rb$ok. This allows several Rebourne calls to be made and then one check of the status to make sure that there were no exceptional conditions. 

In conjunction with the status value, which is numric, there are two textual properties: rb.statusString - a short textual name for the status condition; rb.statusDesc - a slightly longer description of status condition. The latter is useful for displaying in a debug error message. 

Summary: 

Note that not all status conditions are necessarily fatal. If, having dealt with a status condition, a page wishes to continue processind the page then the status can be cleared by writing rb.rb$ok to it. 

Each template describes those error conditions it is capable of generating in terms of 'status' values. Status values are properties of one of the objects in the Rebourne Object Model - usually the top level object provided by a particular template. Each has a symbolic name.

The value of 'rb.status' can be simply compared with rb.rb$ok - NOT being this value imlies some exceptional condition in one of the template calls.

Alternatively 'rb'status' can be compared against specific status values. Each defined status value exists as a property of a Whitebeam object, and the property name always starts with rb$.

Example. Consider a template that implements 'rb.shop' as its top level branch of the Whitebeam object model. This template exports the following status values that can be used by it's methods to convery status information to the presentation pages:

A typical way for these status values to work is for a modify method to return a simple success status to the caller and if the operation fails to provide additional information n the status property - rb.status.

The template exports a method called 'rb.shop.addInventory'. The method looks like:

bool rb.shop.addInventory(productName, quantity, image)

The method returns 'true' if it works OK, otherwise it returns 'false' and sets the reason in the status value. Whitebeam script could then access this method in the following way:

if (!rb.shop.addInventory("Widget", 500, imagegif)) {
   rb.page.write('<p>Failed to update inventory');
}

Alternatively a presentation page may choose to provide more specific error messages by lookng at the rb.status property as follows:

if (!rb.shop.addInventory("Widget", 500, imagegif)) {
   switch (rb.satus) {
   case rb.shop.rb$notAvailable:
      rb.page.write('<p>Template not available');
      break;
   case rb.shop.rb$tooBig:
      rb.page.write('<p>Inventory size is too big');
      break;
   case rb.shop.rb$tableFull:
      rb.page.write('<p>Template table is full');
      break;
   case rb.shop.rb$accessDenied:
      rb.page.write('<p>You may <b>not</b> do that!');
      break;
   }
}

The presentation page may also output the generic - template generated name and description of the status condition. This is useful during development and testing of presentation pages. A fairly generic