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.
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).
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:
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'.
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';
?>
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');
}
?>
The following is a list of available system-events that can be used when a plugin:
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_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
Up Next: Data Sanitization