Running JavsScript only files

The traditional model for Whitebeam applications has been to run "Presentation Pages" - these are XML pages containing WhitebeamML (Whitebeam Markup Language). Within this XML tree there can be embedded Javascript, must as you can have in client-side web-pages with <script tags.

With the migration of much of the user interface (UI) coding from the server to ever more capable client environments this traditional Whitebeam structure can seem cumbersome when what you're trying to achieve is an end-point for RPC methods. It would be nice if you could write a sever side AJAX end point, for example, in pure JavaScript.

From Whitebeam 1.3.23 it's now possible to run 'raw' JavaScript files.

Configure Apache/Shell to run raw JavaScript files

Whitebeam's default behaviour is to run standard WhitebeamML XML files. You need to add an RBJS directive to your Apache or Whitebeam Shell configuration file(s) on your server:

AddHandler whitebeam-handler .wjs
RBJS wjs

You can put this in you /etc/httpd/conf.d/whitebeam.conf file if you installed using the RPM on a RedHat/CentOS install. The first directive is to tell Apache that Whitebeam wants to handle all files with an extension '.wjs'. The second tells Whitebeam that when it's asked to run such a URL it should treat it as raw JavaScript.

With this change in place, and Apache restarted, you could use the following URL: "http://mysite.com/runapp.wjs" where runapp.wjs contains:

rb.page.write('Hello World;);

You have free access to all the built in Whitebeam API methods and to the same templates that a WhtiebeamML page has.

Going beyond the standard Whitebeam API

While this is 'useful' there are some functions that are directly available in markup for which there are not direct JavaScript equivalents:

<rb:script src="/framework/layout_engine.sjs"/>
<rb:script>
   Layout.renderPage()
</rb:script>

JavaScript has caught the worlds imagination and there are many 'standard' (or at least ver usefule) libraries around that can be applied both client side and server side. A good example of this is underscore.js. There are also a bunch of 'standard' module loaders out there. The most applicable to Whitebeam is the 'CommonJS Module Loader, which is designed for synchronous load server environments but some libraries that applications want to use may have been developed with the asynchronous 'require.js model.

Rather than impose a specific loader, or reinvent the wheel, Whitebeam JS allows applications to create their own environment. By default Whitebeam simply 'runs' a JavaScript file. Applications can however configure the JavaScript environment before the script is started. Do this by specifying a separate XML configuration file somewhere under your DocumentRoot directory. This file can contain any valid WhitebeamML mark-up which a special '<rb:js/> tag to identify when to run the JavaScript application:

<rb:script src="commonjs_loader.sjs"/>
<rb:js/>

The CommonJS module loader is then available directly withing your script which can be written as:

var application = require('main');
var layoutEngine = require('layout');
layoutEngine.renderPage()

Common JS Loader Module

As an example Whtiebeam release 1.3.23 onwards includes a sample CommonJS module loader. This is currently located in the source tree under 'whitebeam/scripts'. This implementation is conformant to the CommonJS Module Loader 1.1.1 spec. You can either copy this code to you virtual server file space or install the script as a 'system' utility making a single copy available to all your applications.

System scripts should be installed under the standard Whitebeam install path in a subdirectory 'user' under 'scripts'. The default install path is /var/whitebeam so copy the script to /var/whitebeam/scripts/user.

You can then reference this script in a JavaScript loader profile as follows:

<rb:script src=&qout;/commonjsmod.sjs&qout; system="yes"/>
<rb:js/>