NAJAX Page Skeleton

This tutorial will teach you step-by-step how to use NAJAX.

Step 1 - Basic Class

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.

FirstClass.class.php
<?php

class FirstClass
{
	function toUpper($str)
	{
		return strtoupper($str);
	}
}

?>

Step 2 - Applying Meta Data

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.

Step 3 - NAJAX Initialization

Let's create our main file. We'll include FirstClass.class.php and the main NAJAX file - najax.php.

index.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('.') ?>

Step 4 - Exporting Objects

Next, we'll export an instance of FirstClass to the client.

index.php
<?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>

Step 5 - Error Handling

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.

index.php
<?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>

Step 6 - Using the Class

The final step is to make some use of FirstClass class.

index.php
<?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.

index.php
<?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>

Final Words

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.