System Template

Overview

The System Template provides the fundamental facilities for controlling the generation of Web pages, for interacting with end-users at Web browsers and maintaining the "environment".

• The page object provides a number of facilities for building pages using included files, repeated blocks and by redirection. The redirection facility allows the developer to structure their application better by enabling a different page to be conditionally sent back to the requestor based on an appropriate test. Include files allow the developer to generate re-usable librairies. Convenient access to form parameters, is also made available by the page object. There are also a number of sub-objects:

  • The cookie page object enables very easy manipulation of user browser cookies.

  • The env page object gives access to web server/protocol variables.

  • Tracking features allow the developer to track a user's session on a browser as they traverse a web application. The session object automatically saves session information and makes it available to presentation pages. Session tracking is achieved transparently using a combination of browser cookies and embedded session markers in HTML elements (such as URLs or Form tags) and automatically retrieved by the template. A practical example would be to record those search results that have already been displayed to a user where the results exceed one page.

• A security object controls page access, or items within pages such as links to files, enabling them to be restricted to a specified list of users (this is performed in conjunction with the Contacts Template which allows names and passwords to be added, modified and deleted).

• The debug object provides facilities that allow for test mode operation of sites and the controllable generation of developer defined, as well as system defined, error messages.

• The file object maintains a repository of file or binary information such as documents and images

• The email object allows, for example, the contents of web forms to be emailed to defined recipients.

Page

The page object supports a redirect mechanism (<rb:redirect src="something" /> tag and rb.page.redirect("something") method) that causes the presentation engine to discard all page output from the currently executing presentation page and start again with the redirected presentation page. Note that a redirect is not a goto. It is structured in that execution of the original page will continue after the redirected page is processed. Although no page output will be produced, any side effects of program execution will still take place (e.g. you could have a piece of code on the original page that "tidied up" after any redirect).

Another, associated mechanism supported by the page object is the included page (<rb:include src="something" /> tag and rb.page.include("something") method).

All applications will use forms to input data from a user's browser and the page object provides a very easy mechanism with which to read the data into an application. The form data can be submitted with a GET or a POST (or indeed the input could be made by means of URL parameters such as http://www.whitebeam.com/input.rhtm?count=342); in either case a call to the rb.page.formdata() method gets the parameters. These parameters become properties of the object returned, the name being the name of the parameter, with a value set to the parameter value. Automatic "unescaping" of encoded parameters is performed by the method to make manipulation as straightforward as possible.

Cookie

The cookie object lets the developer read and write user browser based cookies.

Env

The env(ironment) object gives access to a similar set of environment variables to those available to a CGI programmer.

Session

A very important and useful feature of the Whitebeam system is the mechanism it provides for session tracking. Session tracking is the ability to identify a series of requests as coming form the same user browser session (no inherent mechanism is designed into web browser protocols). If you are a programmer, session data is like having a static global variable (in the form of a container for JavaScript objects) for your set of presentation pages. The data can be read, modified and then saved again from any presentation pages using rb.page.session.read()andrb.page.session.write(sData).

Security

The security object makes it very easy to restrict access to certain pages (or subsections of pages) of an application and specify whether they should be served in a secure manner. A page is access controlled for example by using <rb:authenticate> tags in conjunction with the Contacts template. The security object provides access to various parameters such as authorisation status rb.security.auth.status().

Debug

The debug object provides a mechanism to record and output a separate debug content.

By default all test instances of applications work in debug mode. In this mode all errors are reported to the requesting browser - these could be JavaScript errors, run time errors or template interfacing errors (e.g. a value out of range). Debug text can be inserted into the output document by using the <rb:insertdebug/> tag, typically you would place this at the end of the HTML before the closing body tag. The debug text stream is generated by rb.debug.write() method calls embedded in Presentation Page JavaScript.

File

The file object is a Whitebeam component that maintains a repository for file or binary information such as documents and images.

Concepts

A file has a standard set of properties such as file name, owner, and description. It also has a file definition that combines file mime (describing the type of file), size and binary data or location. Each file in the database is automatically allocated a unique identifier (fileID) when it is created.

The file template allows an extensive set of search criteria to be specified for retrieving files. To narrow down the search results, keywords can additionally be specified along with the elements of data in which find matches. It is also possible to specify how much data is returned for all categories or items matching the search criteria. Reducing the amount of data returned may increase the overall turnaround time for the search. It is also possible to specify the index of the first item to be retrieved from the set of results matching the set criteria.

The binary data type supports three key methods:

Example Uses

All images used in generating web pages can be easily stored and retrieved via the File template as can files to be made available for download to a user.

To load a known and single file onto the Whitebeam system...

1.   Set up a Javascript object with the details of the file to be created:

file_create = new Object;
file_create.fileDef = new Binary;
file_create.name = “file name”;
file_create.owner = “Marketing”;
file_create.description = “picture of the team”;


2.   Load the file from the file system:

file_create.fileDef.load( “team.gif” );


3.   Create the file:

var fileID = rb.file.create(file_create);


To load any file or multiple files onto the Whitebeam system …

1.   Present a HTML form to capture the file details:

… <input type = “text” name = “name”>
…
… <input type = “file” name = fileDef”>


It is VERY important to make the form action 'post' and to add an extra attribute of enctype=multipart/form-data:

<form method="post" action="output.rhtm" enctype="multipart/form-data">

2.   Get the file details using Whitebeam script:

var input = rb.page.formdata();


3.   Set up a JavaScript object with the details of the file to be created:

file_create = new Object;
file_create.name = input.name;
file_create.owner = input.owner;
file_create.description = input.description;
file_create.fileDef = input.fileDef;


4.   Call the method to create the file:

var fileID = rb.file.create(file_create);