'Site' Template Overview

The site template provides a store for site-wide, or global site data. Before going into the detail it's worth describing a few typical web-application requirements that can make use of this template.

Configurable site paramters

Modular, reusable applications are often built from configurable components. Configuration often takes place through data stored in a file. This works well for configuration options that are only changed when the site is initially build and for which there is no requirement for the users to make changes to those parameters.

Where these parameters need to be changed dynamically a common solution is to write application code that updates the core configuration file. Unfortunately this solution doesn't scale to multiple server, load balanced installations which is one of the main target requirements for Whitebeam. To scale these paramters need to be stored in one place accessible by all servers in the installation. The obvious place of course being a central site database.

Application data cache

Another common application scenario is the need to build dynamic pages from the contents of the database. Although all of the data is stored in the database via the various templates, it may take unacceptably long to retrieve that data for each page generation.

This is particularly true of pages that summarise information from various different application areas, and that are frequently accessed. The home, or landing page for a site is a very common example of this.

Consider an on-line magazine as an example. The front page is likely to hold editorial commentary, a summary of articles in the magazine and potentially a summary of recent contributions from site members/contributors.

All of this data could be retrieved for each page impression by making the relevant requests to each of the templates, but the home page must respond very quickly, and is likely to be the most heavily loaded page on the site. Couple this with the fact that the contents of that page changes relatively infrequently. For example if the content changes once an hour, and 500 people visit in that time, then exactly the same page has been built from the database 500 times!

Caching of frequently used data is the general solution to this problem. Build a summary of the data once, or perhaps once an hour and store that data somewhere fast and convenient. Commonly this cache information is stored in a local file, but again this does not play well to Whitebeams target of a scaleable multi-server solution.

Although each server *could* indepently create a cache file, there will be times when the caches contain slightly different information. Given that two requests from the same client can hit different servers, the page can vary from time-to-time. Not ideal!

A better solution is a central cache, again the most useful place to store this would be in the database.

Central data-store

The template stores a number of data-sets on behalf of an application instance. A simple template interface allows one or more of these data-sets to be retrieved in a single template call.(Although be aware of the template data-trasfer limit, which is currently 250K. If you're transfering more data than this though for a single page then for efficiency you probably want to revisit your design!)

The template serialises the JavaScript object and stores it in the database (see the page on meta-data for more information).

Some examples

The most common (intended) way of using the template for caching data is to have each component that is responsible for data storage to create a 'site' template summary. A page that then needs to combine data from various components will read all the summaries in a single template call.

A code snippet that reads a list of articles from a branch of the catalogue, builds a summary of that information and then stores this in 'articles' section in the site template:


function buildSummary(rootID) {

   var it=rb.catalogue.item.get({ID:rootID, idMkr:'N',allData:2});

   var summary = {docs:[]};

   while (it.getNextRow())

      summary.docs.push({ID:it.itemID, name:it.name, summary:it.description});

 

   // Store in the site template.

   rb.site.write("articles",summary);

}

You can imagine several other components caching in a similar way (in sections 'messages' and 'topics') and then some 'homepage' code that draws in all this cache data to build the site summary:


<rb:script>

   var cacheData = rb.site.readSet(['articles','messages','topics']);

   // cacheData has three properties, with the name of the sections 

   // requested. So for example to output the article summary from this.

</rb:script>

   <rb:repeatfor expr="var i=0;i<cacheData.articles.docs.length;i++">

   <div class="title">

      <a rb:eval=&qout;href#'readArticle.rhtm?ID='+cacheData.articles.docs[i].ID">

         <?= cacheData.articles.docs[i].title ?>

      </a>

   </div>

   <div class="description">

      <?= cacheData.articles.docs[i].description ?>

   </div>

   </rb:repeatfor>

'Site' Template Overview

Introduction

Configurable site paramters

Application data cache

Central data-store

Some examples