Next: 5. Writing new Clarens Up: manual Previous: 3. Client Usage Contents

Subsections

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 http://machine.name/clarens/. 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	`http://machine.name/clarens/`

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:

JSON

{"id":0,
"error": null,
"result":[{
"desc":"A test service",
"name":"Test Service"
"file":"test/test_interface.html",
"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.

HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>

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

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

<form name="requestform">
Type a word: <input type="text" name="word">
<input type="button"
onclick="do_echo()"
value="Send!">
</form>

</body>

This page does a few things:

Loads the ../javascript/json.js and test.js files in the head section of the page.
Loads the javascript/json_html.js file in the body of the page.
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:

Javascript

// Send echo request
function do_echo(){
  word=document.requestform.word.value;
  jsonrpc("echo.echo", word, echo_callback, null);
}

// echo callback
function echo_callback(result){
  alert(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: 5. Writing new Clarens Up: manual Previous: 3. Client Usage Contents

Conrad Steenberg 2005-07-11