This tutorial will teach you step-by-step how to use NAJAX.
It's a good idea to create a separate file for each class that
you would like to use in NAJAX. 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 NAJAX 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 najaxGetMeta() { NAJAX_Client::mapMethods($this, array('toUpper')); NAJAX_Client::publicMethods($this, array('toUpper')); } } ?>
You should use NAJAX_Client::publicMethods rather than NAJAX_Client::privateMethods.
Let's create our main file. We'll include FirstClass.class.php
and the main NAJAX file - najax.php
.
<?php require_once('FirstClass.class.php'); require_once('najax.php'); ?>
Next, we need to tell NAJAX 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 NAJAX callback.
index.php<?php require_once('FirstClass.class.php'); require_once('najax.php'); NAJAX_Server::allowClasses('FirstClass'); if (NAJAX_Server::runServer()) { exit; } ?>
One of the most important steps it to register NAJAX client files.
index.php<?php require_once('FirstClass.class.php'); require_once('najax.php'); NAJAX_Server::allowClasses('FirstClass'); if (NAJAX_Server::runServer()) { exit; } ?> <?= NAJAX_Utilities::header('.') ?>
Next, we'll export an instance of FirstClass
to the client.
<?php require_once('FirstClass.class.php'); require_once('najax.php'); NAJAX_Server::allowClasses('FirstClass'); if (NAJAX_Server::runServer()) { exit; } ?> <?= NAJAX_Utilities::header('.') ?> <script type="text/javascript"> var obj = <?= NAJAX_Client::register(new FirstClass()) ?>; </script>
There are various situations in which NAJAX 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 NAJAX
will try to execute a method called onToUpperError
.
If this method exists and it returns true
the exception
is processed and NAJAX won't display an error box.
<?php require_once('FirstClass.class.php'); require_once('najax.php'); NAJAX_Server::allowClasses('FirstClass'); if (NAJAX_Server::runServer()) { exit; } ?> <?= NAJAX_Utilities::header('.') ?> <script type="text/javascript"> var obj = <?= NAJAX_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('najax.php'); NAJAX_Server::allowClasses('FirstClass'); if (NAJAX_Server::runServer()) { exit; } ?> <?= NAJAX_Utilities::header('.') ?> <script type="text/javascript"> var obj = <?= NAJAX_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('najax.php'); NAJAX_Server::allowClasses('FirstClass'); if (NAJAX_Server::runServer()) { exit; } ?> <?= NAJAX_Utilities::header('.') ?> <script type="text/javascript"> var obj = <?= NAJAX_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 NAJAX, such as extensions (NAJAX_HTML), class maps, server and client events... I hope I'll have time to write another tutorial on how to use them.
Happy coding.