Inhalt

• Über das Buch
• Shop
• Lokris
• Code-Beispiele
• Ajax- Programmierung, -Beratung und -Schulung
• Impressum

Der Intensiv-Einstieg in Ajax mit unseren Inhouse-Workshops.

Lokris Manual

Lokris is a Javascript library for Ajax communication between browser and server. It's functionality is focused on the communication. Thus it can be called a XMLHttpRequest wrapper. This manual describes how to use Lokris in one's own web pages and how to communicate with the server.

Loading the library

It's recommended to load Lokris like any other Javascript library in the head of a HTML page with the following directive:

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

This line implies that lokris.js is stored in the same directory as the HTML file. Otherwise the value of the src attribute has to be set accordingly.

Doing Ajax requests

Requesting an XML resource

If doing an Ajax call that retrieves XML data, a callback function for processing the XML data is required. Lokris assumes that the server sends an XML MIME-Type, and then, Lokris calls the callback function with the XML document object as it's argument. The process looks like this:

// Define the callback function for processing XML documents (DOM objects):

function yourXmlCallback(xmlDocument) {
  ...
}

// Doing the call:

Lokris.AjaxCall(uri, yourXmlCallback [, options]);

Example:

Lokris.AjaxCall("/an/xml/source.xml", alert);

This example sends an HTTP request to http://current_host/an/xml/source.xml. Since Ajax is asynchronous by default, the function call terminates immediately and the browser continues the execution of the Javascript program. As soon as the requested data arrive from the server, Lokris calls the alert() function with the received data as the only argument. If it's XML, alert() is called with a DOM object of type document.

Example:
Try the example by clicking the button:

// Lokris call:
Lokris.AjaxCall("message.xml", alert);

Because alert() provides no special handling for XML objects, the output might look like this (depending on the browser and OS):

Requesting a text resource

Requesting text data works exactly as described before. The difference is, that Lokris calls the callback function with a string argument in case of a text/plain MIME type. The callback function should be defined accordingly. Summarised:

// Define the callback function for processing text data (strings):

function yourTextCallback(string) {
  ...
}

// Doing the call:

Lokris.AjaxCall(uri, yourTextCallback [, options]);

Example:
Since the process is the same as before, we can directly try an example. Please note that the data sent are the same as before. Only the file name extension, and consequently the MIME type is different.

// Lokris call:
Lokris.AjaxCall("message.txt", alert);

Now alert() prints the text, because the function got a string instead of a DOM object as it's argument.

Options

Beyond the basic functionality Lokris has more option, some of them advanced. When using Lokris.AjaxCall, options are defined as an anonymous object, and are given as the third parameter to the function.

Synchronous Ajax communication

Usually Lokris runs asynchronous (that's the default behaviour of the XMLHttpRequest object). To make a synchronous Ajax call, the option async with a value of false is used as follows:

var request = Lokris.AjaxCall(uri, null, {async: false});

// After requesting XML data
yourXmlCallback(request.responseXML);

// After requesting text data:
yourTextCallback(request.responseText);

The third paramter shows the anonymous options object. In this example it has just one property, async. In the case of asynchronous Ajax requests not all browser call the callback function; some do it, some not. To handle this varying behaviour, Lokris suggests the convention shown above: The callback function is set to null. Browser which call the callback function just call null. Lokris returns the request object as the result of the communication. It can be used to call the callback function to processed the returned data.

Defining timeouts for asynchronous communication

In contrast to many other Ajax libraries, Ajax has an integrated timeout handling. With asynchronous communication it can happen, that the server does not responds to the request for a long time. You might wish to abort the request if the server does not responds within a reasonable period.

Lokris supports this by aborting the communication after a given amount of time and calling a given function. The so called timeout handler may inform the user that an error has occurred.

Example:

function myTimeOut() {
  alert("Server does not respond. Aborting the communication.");
}
Lokris.AjaxCall(uri, yourXmlCallback, {timeout: 5000, timeoutHandler: myTimeOut})

Options reference