Introducing XOAD

So far in this part of the book we have looked at the prototype.js and Rico libraries and how they can help you to develop Ajax applications. Unlike these client-side libraries, which are written in JavaScript, XOAD is a server-side Ajax toolkit written in PHP.

This lesson discusses some of the concepts behind XOAD and the basics of its use.

Tip

XOAD is an acronym for XMLHTTP Object-oriented Application Development.

All our work so far has concentrated on the use of JavaScript to handle both the server request and the returned data in Ajax applications. XOAD is a server-based solution written in PHP that takes a slightly different approach.

XOAD applications make server-based PHP functions available to the client-side JavaScript interpreter by passing serialized versions of them as JavaScript objects.

Note

Under the hood, XOAD employs JSON (JavaScript Object Notation) for communications. JSON was described in Lesson 19, "The prototype.js Toolkit."

Downloading and Installing XOAD

XOAD is made up of many PHP and supporting scripts and can be downloaded as an archive file from http://sourceforge.net/projects/xoad. To install XOAD successfully, you need FTP access to a web server that supports PHP and (to use the more advanced features of XOAD) the MySQL database. Detailed instructions for installing XOAD can be found in the downloaded material, and there is a public forum at http://forums.xoad.org/.

A Simple XOAD Page

Let's take a look at an example of the simplest XOAD page. Suppose that you have a PHP class that you want to use in your XOAD application. This class is stored in the PHP file myClass.class.php:

<?php
class myClass {
  function stLength($mystring) {
      return strlen($mystring);
    }
  function xoadGetMeta() {
      XOAD_Client::mapMethods($this, array('stLength'));
      XOAD_Client::publicMethods($this, array('stLength'));
    }
}
?>

This simple class has only one function, stLength(), which merely returns the length of a string variable. We also added some metadata to the class in the form of the function xoadGetMeta(). This information tells XOAD which methods from the class are available to be exported to the main application. In this case there is just one, stLength().

Caution

It is not absolutely necessary to include metadata in the class, but it is recommended. Without metadata, all methods will be public, and method names will be converted to lowercase.

Now you need to start constructing the main application script xoad.php.

Tip

The Ajax applications developed in previous lessons were HTML files with file extensions .htm or .html. Because our XOAD application contains PHP code, it must have a suitable file extension. Most web server and PHP implementations will accept a file extension of .php, and some will allow other extensions such as .php4 or .phtml.

Listing 21.1 shows the XOAD application. This is a fairly pointless program that simply returns the length of a string, "My XOAD Application". Nevertheless, it demonstrates the concept of methods from server-side PHP classes being made available on the client side as JavaScript objects.

Listing 21.1. A Simple XOAD Application

On loading the preceding document into a browser, the page simply says:

String: My XOAD Application
Length: 19

I won't go into much detail about how the PHP code works; this is after all a book about Ajax, not advanced PHP. It's important, though, to understand the concepts that underpin the code, so let's step through Listing 21.1 and try to understand what's happening:

<?php
require_once('myClass.class.php');
require_once('xoad.php');
XOAD_Server::allowClasses('myClass');
if (XOAD_Server::runServer()) {
  exit;
  }
?>
<?= XOAD_Utilities::header('.') ?>

The first part of the script includes both xoad.php and the required class file myClass.class.php, and informs XOAD which classes it may access (in this case only one).

The XOAD function runServer() checks whether the XOAD request is a client callback, and if so handles it appropriately. The header() function is used to register the client header files.

Now let's look at the remainder of the script:

<script type="text/javascript">
var myobj = <?= XOAD_Client::register(new myClass()) ?>;
var mystring = 'My XOAD Application';
myobj.onStLengthError = function(error) {
  alert(error.message);
  return true;
  }
myobj.stLength(mystring, function(result) {
  document.write('String: ' + mystring + '<br />Length: ' + result);
  });
</script>

See how the remainder of the script is a <script>...</script> element?

The line

var myobj = <?= XOAD_Client::register(new myClass()) ?>;

exports the public methods declared in myClass.class.php to a JavaScript object. We now have a JavaScript object with a method stLength() that allows us to use the method of the same name from the PHP class myClass.