Rich Ajax Application Framework
Table of Contents

Connecting The Dots

Client/Server Event Binding

Client/Server Event Binding is what makes the Raxan for PHP framework truly special. Imagine never having to write a single line of JavaScript code in order to receive an Ajax notification when a user clicked on a button. Imagine being able to bind your server-side event handler to just about any HTML tag inside your web page. The possibilities are endless when you realize that you have total control over every DOM element inside your client's web browser.

Binding to an Event

Every JavaScript developer knows that he or she will often times have to write JavaScript code to send data to the server. However, with Raxan for PHP, that's a rare occurrence. In fact, getting data or receiving an event notification from the client is very straightforward.

The simplest way to do this is to use the xt-bind extended attribute to listen to events being triggered from the client.

Usage:

xt-bind="type, callback, serialize, autoDisable, autoToggle"

Note: Comma separate CSS selectors (e.g .class1, .class2, .classN) are currently not supported when using the xt-bind attribute. They can however be used with the bind() method.

Usage Examples:

xt-bind="click, showDetails" - makes a synchronous call to the server

xt-bind="#click, showDetails"  - makes an asynchronous call to the server 

- The following will disables the current element, toggles the "#loader" element and serialize
- the all "form" elements before making an asynchronous callback to the server 

xt-bind="#click,editUser,form,true,#loader"

Working example:

<?php require_once('raxan/pdi/autostart.php'); ?>

<form name="form1" action="" method="post">
    <input id="mybutton" type="button" value="Click Me" xt-bind="click,buttonClick" />
    <div id="msg" />
</form>

<?php
    class MyPage extends RaxanWebPage {

        // callback function
        protected function buttonClick($e) {
            // select the #msg element and set html to hello world
            $this->msg->html('Hello World');
        }
    }

?>

Event Delegates

Event delegates (or live events) provides a way for you to bind a dynamic set of element to an event without having to reselect the elements whenever the set changes.

To do this you can use either the xt-delagate extended attribute or the

Usage:

xt-delegate="selector type, callback, serialize, autoDisable, autoToggle"

Note: See xt-bind for a descrition of the other parameters

Usage Example:

xt-delegate="a.edit click, editRecord" - delegates all a.edit click events for the current element

Working Example:

<?php require_once('raxan/pdi/autostart.php'); ?>

<ul xt-delegate="li a click,doSomething">
    <li><a href="#1">Item 1</a></li>
    <li><a href="#2">Item 2</a></li>
    <li><a href="#3">Item 3</a></li>
    <li><a href="#4">Item 4</a></li>
</ul>
<div id="panel"></div>

<?php
    class NewPage extends RaxanWebPage {

        protected function doSomething($e) {            
            $i = $e->intval(); // get the integer value for the event                
            $this->panel->text('You have clicked item #'.$i);
        }
    }

?>

Timeout Events

There are times when you will need to periodically update an element on a web page with content from the server without any user intervention. This task would normally require a developer write JavaScript code to periodically poll the server for updates.

Raxan eliminates the need to have to manage your own client-side updates with the xt-autoupdate extended attribute:

Usage:

xt-autoupdate = "true"  - Default mode. Enable automatic updates during ajax calls
xt-autoupdate = "seconds, callback, repeat, serialize, autotoggle" - enable timeouts

Note: Setting xt-autoupdate="true" will automatically cause the element to be updated during ajax calls. This is similar to calling the updateClient() method.

Usage Examples:

xt-autoupdate = "true"  - enable automatic updates during ajax calls
xt-autoupdate = "5000,update,true" - updates every 5 seconds (repeatedly)

- The following will asynchronously updates the element every 
- 15 seconds (repeatedly) and toggles #loader during updates

xt-autoupdate = "#15000,update,true,,#loader"

Working Example:

<?php require_once('raxan/pdi/autostart.php'); ?>

<a href="#" xt-bind="#click,doSomething">Click Here</a>
<div id="msgbox" xt-autoupdate="true"></div>

<?php
    class NewPage extends RaxanWebPage {

        protected function doSomething($e) {
            $this->msgbox->text('A message from your server');
        }
    }

?>
Using the bind() and delegate() methods

The bind() method provides you with a lot more features than the xt-bind extended attribute. With the bind method you can specify three different types of event callback functions:

In addition, the bind() method can also accept optional values that can be used to determine the data returned by the client or actions that should be carried out just before or after and event call:

<?php

    $this['#button']->bind('#click',array(
        'callback' => '.auto_search',
        'autoDisable' => true,   // disable the button during event call to server
        'autoToggle' => 'img#pre', // show pre loader
        'serialize' => 'form :input' // serialize ad post all form inputs back to the server
    ));

?>

As stated above, the delegate() method is similar to the bind() method with the exception that you can specify an additional selector as part of the event name.

<?php

    $this['#button']->delegate('a.edit #click','.editRecord');

?>

Bind options for events

When the event handler is called, an instance of the RaxanWebPageEvent object is passed as the first parameter with the following properties:

Triggering a Server-side Event

Server-side events can be triggered by using the framework's API, client-side scripts, form submits or hyperlinks. By sending special name/value pairs to the server via either POST or GET methods you can make a request to invoke an event within the application. Here's a list of some of the event name/value pairs used when making a request:

_e[target] - Target element id _e[type] - Event Name - Defaults to click _e[value] - (Optional) Value to be passed to the event _e[tok] - Special token to be sent to server. This entry is optional if the event was registered using @global. By default the framework automatically assigns this value.

An example of how to use a hyperlink to manually invoke a server-side event:

<a href="order.php?_e[target]=page&_e[type]=saveorder">Submit Order</a>

It's important to note that the framework has a built-in security feature that helps to prevent Cross-Site Request Forgery (CSRF). Each event request must be accompanied with a valid token id. This token is unique to the user's active browser session and will be destroyed once the browser is closed. Handling a Server-side Event

Handling a server-side event is very simple and straight forward. All that's required is your event handler (or callback) function or object and a call to one of the three available event binding functions.

The bind() method can be used to automatically bind a server-side event handler to the client-side click event of the selected element:

<?php
    $page['#button']->bind('click','myEventHandler');
?>

The delegate() method will delegate and redirect a client-side event to a server-side event handler:

<?php
    $page['#list td a']->delegate('click','myEventHandler');
?>

This will register an event for the current page and bind the event to a callback handler:

<?php
    $page->registerEvent('specialevent','myEventHandler');
?>

Degradable Pages >>

Table of Contents