Category: Tutorials for xajax 0.5

Xajax 0.5: Tutorials: Writing Custom Plugins

Writing Custom Plugins for xajax 0.5

First, you need to declare your plugin class as an extension of the xajaxResponsePlugin class; Add some functions; and then register the plugin.

Getting Started

Ensure that you have prototype and scriptaculous installed and working before using this example code verbatim.

Let's start with a simple plugin, then we'll expand it's capabilities. Add the following plugin code at the top of your index.php file (if you are using a single file implementation) or at the top of the index.server.php (if using an index, common and server setup).

class scriptaculous extends xajaxResponsePlugin
{
    var $sCallName = "scriptaculous";
    
    function fade($id) {
        $this->_objResponse->script("new Effect.Fade(\"{$id}\");");
    }
    function appear($id) {
        $this->_objResponse->script("new Effect.Appear(\"{$id}\")");
    }
}

$pluginManager = &xajaxPluginManager::getInstance();
$pluginManager->registerResponsePlugin(new scriptaculous());

Now, you can use the plugin in your php code like this:

function myPHPFunction() {
    $objResponse = new xajaxResponse();

    //PHP4 or PHP5 Plugin Syntax
    $objResponse->plugin("scriptaculous", "fade", "myDivID");

    return $objResponse;
}

While the syntax above will work in PHP5, there is an alternate syntax available in PHP5 ONLY that is more intuitive and readable:

function myPHPFunction() {
    $objResponse = new xajaxResponse();

    //PHP5 ONLY Plugin Syntax
    $objResponse->scriptaculous->fade("myDivID");

    return $objResponse;
}

Adding On

At this point, you will start to think of all the nifty options that you are missing out on by settling for the simplistic version... so, here is an example of how to extend the plugin to support more of the scriptaculous options.

Let's extend the plugin a bit:

class scriptaculous extends xajaxResponsePlugin
{
    var $sCallName = "scriptaculous";

    function processParameters(&$aParams) {
        $comma = false;
        $params = ", {";
        if (isset($aParams["duration"])) {
            if ($comma)
                $params .= ", ";
            $params .= "duration: ";
            $params .= $aParams["duration"];
            $comma = true;
        }
        if (isset($aParams["queue"])) {
            if ($comma)
                $params .= ", ";
            $params .= "queue: '";
            $params .= $aParams["queue"];
            $params .= "'";
            $comma = true;
        }
        $params .= "}";
        if (", {}" == $params)
            $params = "";
        return $params;
    }        
    function fade($id, $aParams = array()) {
        $params = $this->processParameters($aParams);
        $this->_objResponse->script("new Effect.Fade(\"{$id}\"{$params});");
    }
    function appear($id, $aParams = array()) {
        $params = $this->processParameters($aParams);
        $this->_objResponse->script("new Effect.Appear(\"{$id}\"{$params})");
    }
}    

$pluginManager = &xajaxPluginManager::getInstance();
$pluginManager->registerResponsePlugin(new scriptaculous());

Now, you can use the plugin with the additional parameters like this:

function myPHPFunction() {
    $objResponse = new xajaxResponse();

    //PHP4 or PHP5 Plugin Syntax
    $objResponse->plugin("scriptaculous", "fade", "myDivID", array("duration"=>".3"));
    $objResponse->plugin("scriptaculous", "appear", "myDivID", array("queue"=>"end"));

    return $objResponse;
}

Or using the PHP5 Only syntax:

function myPHPFunction() {
    $objResponse = new xajaxResponse();

    //PHP5 ONLY Plugin Syntax
    $objResponse->scriptaculous->fade("myDivID", array("duration"=>".3", "queue"=>"end"));
    $objResponse->scriptaculous->appear("myDivID", array("duration"=>".8", "queue"=>"end"));

    return $objResponse;
}

Adding additional functions, using the above functions as templates, should be straightforward.

See also the basticPluginTest.php file that comes packaged with xajax 0.5.

TODO

At some point, the plugin should be moved to a separate file; It appears that xajax 0.5 is able to read plugin files from a specified folder. I'll have to check into that and report back. (Jared says: I haven't implemented this yet in Beta 1, but 0.5 will be able to read plugin files automatically at some point.)

BETA 4b

I was trying to get this to work with the beta 4b version. After a long struggle I wrote the following plugin for de jquery lib.

<?php

class jquery extends xajaxResponsePlugin {
    var $validBaseMethods = array('addclass','append','prepend','background','after','removeClass','hide','show','slideToggle','toggle');

    function generateClientScript() {
      echo '<script type="text/javascript" src="./jquery-1.2.1.min.js"></script>'.PHP_EOL;
    }

    function buildArgs($iArgs) {
      $args = false;
      // Skip the first arg it is always the jquery expression
      $count = sizeof($iArgs);
      for($i = 1; $i < $count; $i++) {
        if($args) {
          $args .= ',';
        }
        $args .= '"'.$value[$i].'"';
      }
      return $args;
    }

    function __call($method, $args) {
      if(!in_array($method, $this->validBaseMethods)) {
        error_log($method.' method has not been tested with jquery to work!');
      }
        $exp = $args[0];
        $args = $this->buildArgs($args);
        $this->objResponse->script('$("'.$exp.'").'.$method.'('.$args.')');
    }
    
}    

$pluginManager =& xajaxPluginManager::getInstance();
$pluginManager->registerResponsePlugin(new jquery());