Introducing XOAD Events

This tutorial assumes that you've read XOAD Page Skeleton.

What's XOAD Events?

XOAD Events was introduced in version 0.3.0.0. It allows you to fire events from one computer and catch and process them on another. To understand XOAD Events imagine a chat application with two users - John and Marry. Take a look at this simple diagram:

John -> Server -> Marry Diagram
Figure 1

When John writes a new message the chat application fires a new event and sends it to the server (1). Marry is using the same application that is listening for this event and she'll receive the message that John sent (2).

Behind the Scenes

The browser and the web server are in disconnected mode after processing the page. When John fires a new event XOAD Events opens a new connection to the server and posts the event. What about Marry? In order to receive the event Marry is querying the server each second. To illustrate what's happening at the server take a look at this simple log:

  1. Marry @ 13:00:00 - get new events
    Server - no new events
  2. Marry @ 13:00:01 - get new events
    Server - no new events
  3. Marry @ 13:00:02 - get new events
    Server - no new events
  4. John @ 13:00:03 - post new event
    Server - OK
  5. Marry @ 13:00:03 - get new events
    Server - one new event
  6. Marry @ 13:00:04 - get new events
    Server - no new events
  7. Marry @ 13:00:05 - get new events
    Server - no new events
    ...

Configuration

To use XOAD Events you must choose one of the available storage providers. These providers are used to save the information that is associated with each event. At the time of this writing the following providers were available:

To use the MySQL provider you must run the following SQL code in your database:

CREATE TABLE `xoad_events`
(

	`id`		BIGINT			UNSIGNED	NOT NULL	AUTO_INCREMENT,
	`event`		VARCHAR(100)				NOT NULL,
	`className`	VARCHAR(100)				NOT NULL,
	`filter`	VARCHAR(100)				NULL,
	`sender`	TEXT					NULL,
	`data`		TEXT					NULL,
	`time`		DOUBLE			UNSIGNED	NOT NULL,
	`endTime`	DOUBLE			UNSIGNED	NOT NULL,

	PRIMARY KEY(`id`),

	INDEX(`event`, `className`, `filter`, `time`, `endTime`)

);

Next, open config/xoad.config.php and search for define('XOAD_EVENTS_STORAGE_DSN'. Modify this line with your real values (server, user, password and database).

Basic Example

Let's create a simple class Person that will have only one variable - name.

Person.class.php
<?php

class Person
{
	var $name;
}

?>

Our goal is to create two separate pages - John.php and Marry.php that will communicate using XOAD Events. Let's start with John.php. We'll include the Person.class.php and xoad.php and we'll instruct XOAD to handle the requests.

John.php
<?php

require_once('Person.class.php');

define('XOAD_AUTOHANDLE', true);

require_once('xoad.php');

?>

Next, we need to register XOAD client files. We also need to call one extra method XOAD_Utilities::eventsHeader to include additional information that XOAD Events will use later.

John.php
<?php

require_once('Person.class.php');

define('XOAD_AUTOHANDLE', true);

require_once('xoad.php');

?>
<?= XOAD_Utilities::header() ?>
<?= XOAD_Utilities::eventsHeader() ?>

Next, we add a button that will call a JavaScript function when it's clicked.

John.php
<?php

require_once('Person.class.php');

define('XOAD_AUTOHANDLE', true);

require_once('xoad.php');

?>
<?= XOAD_Utilities::header() ?>
<?= XOAD_Utilities::eventsHeader() ?>

<button onclick="greetMarry(); return false;">Send Greetings</button>

Now, let's create the JavaScript function to greet Marry:

John.php
<?php

require_once('Person.class.php');

define('XOAD_AUTOHANDLE', true);

require_once('xoad.php');

?>
<?= XOAD_Utilities::header() ?>
<?= XOAD_Utilities::eventsHeader() ?>

<button onclick="greetMarry(); return false;">Send Greetings</button>

<script type="text/javascript">

function greetMarry()
{
	var john = <?= XOAD_Client::register(new Person()) ?>;

	john.name = 'John';

	john.postEvent('onHello');
}

</script>

First, we export a copy of the Person class to the client. Next, we assign the name variable and finally we fire a new onHello event.

Let's continue with Marry.php. We'll include the Person.class.php and xoad.php and we'll instruct XOAD to handle the requests. We'll register XOAD and XOAD Events client files too.

Marry.php
<?php

require_once('Person.class.php');

define('XOAD_AUTOHANDLE', true);

require_once('xoad.php');

?>
<?= XOAD_Utilities::header() ?>
<?= XOAD_Utilities::eventsHeader() ?>

Next, we need to export a copy of the Person class. Note that events are associated with classes. If we add another class ExtendedPerson that fires the onHello event, our class Person will not catch the event, because it's from a different class.

Marry.php
<?php

require_once('Person.class.php');

define('XOAD_AUTOHANDLE', true);

require_once('xoad.php');

?>
<?= XOAD_Utilities::header() ?>
<?= XOAD_Utilities::eventsHeader() ?>

<script type="text/javascript">

var marry = <?= XOAD_Client::register(new Person()) ?>;

</script>

By default XOAD Events is not listening for events (performance reasons). To instruct XOAD Events to listen for our onHello event we'll add this line:

Marry.php
<?php

require_once('Person.class.php');

define('XOAD_AUTOHANDLE', true);

require_once('xoad.php');

?>
<?= XOAD_Utilities::header() ?>
<?= XOAD_Utilities::eventsHeader() ?>

<script type="text/javascript">

var marry = <?= XOAD_Client::register(new Person()) ?>;

marry.catchEvent('onHello');

</script>

Next, we need to add a handler for our event. We'll create a new method that has the same name as the name of our event - onHello. It takes one argument - the sender of the event.

Marry.php
<?php

require_once('Person.class.php');

define('XOAD_AUTOHANDLE', true);

require_once('xoad.php');

?>
<?= XOAD_Utilities::header() ?>
<?= XOAD_Utilities::eventsHeader() ?>

<script type="text/javascript">

var marry = <?= XOAD_Client::register(new Person()) ?>;

marry.onHello = function(sender) {

	alert('Hello from ' + sender.name + '!');
}

marry.catchEvent('onHello');

</script>

Save both John.php and Marry.php. Open them in different browsers or at different computers. Click the Send Greetings button. An alert window should open in Marry.php.

Advanced Example

Take a look at the Advanced Chat. It demonstrates how to fire events from the server side.

Final Words

This tutorial does not cover some of the advanced features available in XOAD Events, such as filtering and sending data with the event. I hope I'll have time to write another tutorial on how to use them.

Happy coding.

» XOAD HTML Questions & Answers

XOAD Logo