Plugins & System Events

Plugins are special classes that are used to extend the framework by listening to or interacting with system-events or making system wide changes. For example, you can create a plugin to add a footnote to every page within your web site without having to directly modify the individual pages.

Creating a Plugin

To create a plugin you need to extend the RaxanPlugin class as shown below:

<?php
    class NewPlugin extends RaxanPlugin {
        public static $name = 'New Plugin';
        public static $description = "Plugin descrtion goes here";
        public static $author = "Author's Name";
        protected function methods() { return get_class_methods($this); }
        public static function register() { return self::instance(__CLASS__); }

        protected function myMethodName() {
            // your method code here
        }

        public function doSomething() {
            // your method code here
        }
    }
    NewPlugin::register(); // register the plugin
?>

Next, you will need to add system event handler methods to your plugin so that you can perform an action when the event is invoked:

<?php
    class NewPlugin extends RaxanPlugin {
        public static $name = 'New Plugin';
        public static $description = "Plugin descrtion goes here";
        public static $author = "Author's Name";
        protected function methods() { return get_class_methods($this); }
        public static function register() { return self::instance(__CLASS__); }

        protected function page_load($e, $page) {
            $page->append('Hello from Plugin!'); // append the text to the web page
        }

        protected function myMethodName() {
            // your method code here
        }

        public function doSomething() {
            // your method code here
        }
    }
    NewPlugin::register(); // register the plugin

?>

When you're finished you can save your plugin to the raxan plugins folder. For example you could save the file (dosomething.php) to a folder called myplugins (raxan/plugins/myplugins).

Loading a plugin

There are two ways to load a plugin with Raxan. You can use either the "preload.plugins" configuration option or the call the loadPlugin() method as shown:

Using the loadPlugin() method

To load a plugin you simple make a call to the Raxan::loadPlugin() method:

<?php
    // load plugin from plugins.path. The .php extension is not needed
    Raxan::loadPlugin('myplugins/newplugin');

    // get a reference to the loaded plugin instance
    $instance = Raxan::loadPlugin('myplugins/newplugin');
    $instance->doSeomthing(); // call public methods from the plugin

?>

Or call the loadPlugin wrapper directly from the web page:

<?php
    protected function _init() {
        // load plugin
        $this->loadPlugin('myplugins/newplugin');

        // load and get a reference to the registered plugin instance
        $instance = $this->loadPlugin('myplugins/newplugin');
        $instance->doSeomthing(); // call public methods from the plugin

        // load plugin and assign an alias to the loaded instance
        $this->loadPlugin('myplugins/newplugin','myPlugin');   // load as myPlugin property
        $this->myPlugin->doSomething(); // call public methods from myPlugin
    }
?>

The above will load the plugin relative to the plugins.path configuration option, which defaults to the raxan/plugins folder. Notice that we did not have to specify the .php extension for the plugin file.

To load a plugin that's located inside an alternate folder (not relative to plugins.path):

<?php
    // load external plugin using Raxan::loadPlugin()
    Raxan::loadPlugin('/path/to/plugin/newplugin.php', true);

    // load external plugin using RaxanWebPage->loadPlugin() and assign it to 'myPlugin' alias
    protected function _config() {
        $this->loadPlugin('/path/to/plugin/newplugin.php', true, 'myPlugin');
    }
?>

The second parameter will cause the framework to load the plugin based on the specified folder path and filename. Please note that you will have to include the .php extension when loading plugins that are external to the assigned 'plugins.path'.

Using the preload.plugins configuration option

To load your plugins at startup your can use the preload.plugins from within your config file:

<?php
    // comma delimited list of plugins
    $config['preload.plugins'] = 'plugin1, plugin2, myplugins/dosomething, /path/to/plugin/name.php';
?>

Adding methods to a page or element

In addition to listening to system events, you can also use a plugin to add new functionality to a web page to element. For example, you might want to create a plugin that adds a userLogin() method to the page.

To add new methods to a page or element you can use addMethod() as follow:

<?php

    // ... network-connector plugin ...

    protected function page_config($e, $page){
        // add new method to the page object
        $page->addMethod('networkUserLogin',array($this,'login'));

        // or add it to the RaxanWebPage class
        RaxanWebPage::addMethod('isUserLogin',array($this,'loginCheck')); // add a custom method to the page
        RaxanWebPage::addProperty('userAccessPermission','rwd');    // add a custom property to the page

        // add method to RaxanElement
        RaxanElement::addMethod('showUserInfo',array($this,'bindUserInfo'));
    }

    public function login($name, $password){
        // do something here
    }

    public function loginCheck($name){
        // do something here
    }

    public function bindUserInfo() {
        // do something here
    }
?>

To use the new methods, you must first load the plugin before calling the methods:

<?php

    // ... web page ...

    protected function _config() {
        $this->loadPlugin('network-connector'); // load plugin
    }

    // login view
    protected function _loginView() {
        $this->appendView('loggin.html');
    }

    protected function _authorize() {
        $this->loginStatus = $this->isUserLogin($this->userName);
        if ($this->loginStatus==false) {
            $this->redirectToView('login'); //redirect to login view
        }
    }

    // login event handler
    protected function processLogin($e) {
        $uid = $this->post->textVal('user');
        $pwd = $this->post->textVal('password');
        $loginOk = $this->networkUserLogin($uid, $pwd); // process user login
        if ($loginOk) $this->redirectToView('index');
        else $this->flashmsg('Login failed','fade','rax-box error');
    }

?>

System Events

The following is a list of available system-events that can be used when a plugin:

  • system_init - Triggered after the system configuration files has being loaded
  • system_error - Triggered when an error is not handled by the developer
  • session_init - Triggered after the session storage class has being initialized. See the session.data.storage config option
  • data_connection - Triggered before a data connection is created. This event can be used to create custom data connectors by returning the an object to the event caller:

    <?php
        // custom data connection plugin
        protected function data_connection($e,$args){
            $dsn = $args(0);
            $user = $args(1);
            $password = $args(2);
            $attribs = $args(3);
            if (substr($dsn,0,11)=='custom-dsn:') {
                // do something - code to connect $conn to data source goes here
                return $conn;
            }
        }
    ?>
    

    To connect to the custom data source you can use the Raxan::connect() method:

    <?php
        protected function _load() {
            $db = $this->Raxan->connect('custom-dsn: server=localhost','user','password',true);
        }
    ?>
    
  • page_config - Triggered after web page _config event handler

  • page_init - Triggered after web page _init event handler
  • page_authorize - Triggered after web page _authorized event handler.

    <?php
        protected function page_authorize($e,$page){
            // code to validate user goes here
            if (!$isLogin) $page->redirectTo('login.php'); // redirect user to login page
            else if(!$isAuthorized) return false; // deny access to page
        }
    ?>
    
  • page_load - Triggered after web page _load event handler

  • page_prerender - Triggered after web page _prerender event handler
  • page_postrender - Triggered after web page _postrender event handler
  • page_reply - Triggered after web page _reply event handler

Up Next: Data Sanitization