This tutorial will teach you step-by-step how to use XOAD.
It's a good idea to create a separate file for each class that you would like
to use in XOAD. Let's create our first class - FirstClass
. It has
only one function - toUpper
that converts a given string to upper
case.
<?php class FirstClass { function toUpper($str) { return strtoupper($str); } } ?>
Next, we need to apply meta data to the class. The data tells XOAD the real name of the methods in the class, which methods to export and which to skip. Note that the meta data is not necessary.
FirstClass.class.php<?php class FirstClass { function toUpper($str) { return strtoupper($str); } function xoadGetMeta() { XOAD_Client::mapMethods($this, array('toUpper')); XOAD_Client::publicMethods($this, array('toUpper')); } } ?>
You should use XOAD_Client::publicMethods rather than XOAD_Client::privateMethods.
Let's create our main file. We'll include FirstClass.class.php
and
the main XOAD file - xoad.php
.
<?php require_once('FirstClass.class.php'); require_once('xoad.php'); ?>
Next, we need to tell XOAD which classes it's allowed to access. This is not necessary, but it's recommended. Then we run the server and halt the script execution if the request is a XOAD callback.
index.php<?php require_once('FirstClass.class.php'); require_once('xoad.php'); XOAD_Server::allowClasses('FirstClass'); if (XOAD_Server::runServer()) { exit; } ?>
One of the most important steps it to register XOAD client files.
index.php<?php require_once('FirstClass.class.php'); require_once('xoad.php'); XOAD_Server::allowClasses('FirstClass'); if (XOAD_Server::runServer()) { exit; } ?> <?= XOAD_Utilities::header('.') ?>
Next, we'll export an instance of FirstClass
to the client.
<?php require_once('FirstClass.class.php'); require_once('xoad.php'); XOAD_Server::allowClasses('FirstClass'); if (XOAD_Server::runServer()) { exit; } ?> <?= XOAD_Utilities::header('.') ?> <script type="text/javascript"> var obj = <?= XOAD_Client::register(new FirstClass()) ?>; </script>
There are various situations in which XOAD will throw an exception - the server did not respond, script error, invalid response... It's a good idea to 'trap' these exceptions and to process them - otherwise an error box is displayed to the user.
When we make a call to toUpper
in case of error XOAD will try to
execute a method called onToUpperError
. If this method exists and
it returns true
the exception is processed and XOAD won't display
an error box.
<?php require_once('FirstClass.class.php'); require_once('xoad.php'); XOAD_Server::allowClasses('FirstClass'); if (XOAD_Server::runServer()) { exit; } ?> <?= XOAD_Utilities::header('.') ?> <script type="text/javascript"> var obj = <?= XOAD_Client::register(new FirstClass()) ?>; obj.onToUpperError = function(error) { alert(error.message); return true; } </script>
The final step is to make some use of FirstClass
class.
<?php require_once('FirstClass.class.php'); require_once('xoad.php'); XOAD_Server::allowClasses('FirstClass'); if (XOAD_Server::runServer()) { exit; } ?> <?= XOAD_Utilities::header('.') ?> <script type="text/javascript"> var obj = <?= XOAD_Client::register(new FirstClass()) ?>; obj.onToUpperError = function(error) { alert(error.message); return true; } alert(obj.toUpper('Hello World!')); </script>
The above peace of code has one drawback - your browser will freeze during the
request to the server. Add sleep(3)
to toUpper
. You'll see what I mean. To avoid this you should make
your calls asynchronous.
<?php require_once('FirstClass.class.php'); require_once('xoad.php'); XOAD_Server::allowClasses('FirstClass'); if (XOAD_Server::runServer()) { exit; } ?> <?= XOAD_Utilities::header('.') ?> <script type="text/javascript"> var obj = <?= XOAD_Client::register(new FirstClass()) ?>; obj.onToUpperError = function(error) { alert(error.message); return true; } obj.toUpper('Hello World!', function(result) { alert(result); }); </script>
This tutorial does not cover most of the advanced features available in XOAD, such as extensions (XOAD_HTML), class maps, server and client events... I hope I'll have time to write another tutorial on how to use them.
Happy coding.