next up previous contents
Next: 5. Writing new Clarens Up: manual Previous: 3. Client Usage   Contents


4. Writing Browser Interfaces

One of the most common applications on any modern desktop computer is the ubiquitous web browser. For this reason the Clarens framwework provides extensive support for writing browser-based interfaces that can be used from virtually anywhere using a standard browser.

This chapter will explain the basics of how this can be done using the facilities provided by the server-side Javascript and dunamic HTML framework in the clarens-server-web< package.

This chapter describes how to write services that use the Javascript Object Notation (JSON), which is conveniently handled natively by most modern browsers.

4.1 Files and paths

4.1.1 Accessing files on the server in different contexts

In order to have the files describing the client interface accessible by a browser they must be placed under the virtual file service root directory. On a default installation this will be under $opkg_root/share/apache2/clarens/.clarens_file_root or as set up by the clarens-server-config utility. Files placed under this top-level directory will be available using the file.method calls with a virtual / directory prefix.

These files are also available using standard HTTP GET requests under the server URL, typically of the form This is summarized in table 4.1.

Table 4.1: Mapping of paths in different contexts
Context Path
Filesystem $opkg_root/share/apache2/clarens/.clarens_file_root
File service /
Browser URL

4.1.2 Browser interface path conventions

In order to organize interfaces to different services, certain conventions are used for the placement of files. The paths given are relative to the file service virtual root:
Path Description
/ Index file to display 'shell' of different services
/web Files that make up the navigation panel and system-provided content
/web/registry Registry files used to generate navigation panel
/web/javascript System-provided Javascript files
/web/images System-provided image files
/web/images System-provided stylesheet files
/web/service_name Service directories

4.1.3 Registry files

The web browser interface automatically creates a navigation panel on the left of the shell using files placed in the /web/registry directory as mentioned above.

These files are in the form of JSONRPC response methods as if generated by web service calls. They are text files that can be created with any text editor, or automatically using a scripting language like Python.

Each registry file may describe one or more service interfaces, with an associated category, name, description and a link to the interface HTML page. In the registry file these properties are as follows:

Element Description
name Short name to be displayed in the menu
desc Longer description to be displyed as a 'tooltip'
cat A category to place the item in
file A relative link to the interface HTML file

The file containing these definitions must have the .json extension to be used in the navigation menu.

As an example, let's create a registry file for a test service, with a user interface in /web/test:

"error": null,
"desc":"A test service",
"name":"Test Service"
"cat": "Test Category"}],

For anyone familiar with Javascript or Python, the above should be immediately obvious: the file consists of a mapping with elements id, error, and result. The id tag is ignored, while the error must always be null.

The result element contains a list of mappings, in this case only one, each with the information needed to describe one menu item.

4.2 Creating the interface

In this section an interface to the echo service will be created that allows a user to type in a string, press a button and have the server send back the string in question, to be displayed in a message window.

4.2.1 HTML file

The HTML file acts as a visual interface layout description from which the browser creates a page and loads the Javascript code that performs the needed actions.


<script type="text/javascript" src="../javascript/json.js"></script>
<script type="text/javascript" src="test.js"></script>

<script type="text/javascript" src="../javascript/json_html.js"></script>

<form name="requestform">
Type a word: <input type="text" name="word">
<input type="button"


This page does a few things:

  1. Loads the ../javascript/json.js and test.js files in the head section of the page.
  2. Loads the javascript/json_html.js file in the body of the page.
  3. Defines a form with a text input box and a submit button, which when pressed, will call the do_echo() method.

4.2.2 Javascript file

Once the interface is defined, we need to respond to the submit button being pressed in the form, and call the server's echo.echo method using the word the user typed in as an argument. This is accomplished with the do_echo() callback defined in the test.js file quoted below:

// Send echo request
function do_echo(){
  jsonrpc("echo.echo", word, echo_callback, null);

// echo callback
function echo_callback(result){

First the value of the word form element is obtained, followed by a call to the jsonrpc method provided by the Clarens framework.

The jsonrpc method takes the following arguments:

Type Name Description
string method The name of the remote method
list arguments A list of arguments
function success callback Function to be called upon success
function fault callback Function to be called when a fault is returned

The arguments to the remote method is usually passed as a list, although in our example we passed a single string as an argument. The success callback, named echo_callback in the example, takes a result object as its only argument. The type of the result object is determined by the remote method.

The fault callback is called with the full JSONRPC result object as was demonstrated in section 4.1.3 for the registry files. In the case of a fault, or exception, returned by the server, the error element of the JSONRPC return object will contain information about the fault, while the result element will be set to null.

next up previous contents
Next: 5. Writing new Clarens Up: manual Previous: 3. Client Usage   Contents
Conrad Steenberg 2005-07-11