This tutorial assumes that you've read XOAD Page Skeleton.
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:
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).
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:
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).
Let's create a simple class Person
that will have only one
variable - name
.
<?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.
<?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.
<?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.
<?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:
<?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.
<?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
.
Take a look at the Advanced Chat. It demonstrates how to fire events from the server side.
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