Plugins
From PsychoStats
Contents |
Introduction
Starting with PsychoStats 3.1 a plugin architecture is available for developers to extend the front-end using PHP classes. This feature is still new and may undergo several changes or tweaks as the 3.1 branch of code matures but the API should remain relatively unchanged.
A PsychoStats plugin is a PHP object that conforms to a certain API standard used within PsychoStats. You can do virtually anything you want in a plugin object. In it's most simplest form you can "hook" into various events or actions that occur anywhere within the stats website. A hook allows you to extend the functionality of a certain action within PsychoStats without having to recode anything in the core.
Hooks
A "hook" is a mechanism that allows your plugin to hook into a particular action or filter by having part of your plugin code execute at specific times in the page rendering process of the website. Multiple plugins can hook into the same action or filter and will be processed in the order of which they were instantiated.
For a full listing of available hooks see: Hooks
Filter Hooks
A Filter hook is the most common type of hook. A filter allows a plugin to modify something before it is output to the browser or used internally. This can either be a string of text (usually from some block of theme HTML), or a reference to another variable (eq: another object).
A plugin can modify the input given to it in any way it sees fit (And that is appropriate).
Action Hooks
An Action hook is less common and are similar to filter hooks except that usually no arguments are passed into the hook. It's up to the hook to 'globalize' the proper variables and do something useful. One example of this is on the 'map' stats page. The "top 10" player lists on that page are built dynamically and are different for each game. A plugin could register an action hook add_map_player_list and add new stats to the map page w/o having to modify anything in the PsychoStats code directly.
Full Plugin Example
Below is a working shell of a PsychoStats Plugin (PSP).
<?php
/**
* "Hello World" plugin.
* This is not a useful plugin. It's simply for educational purposes only.
* Use this as a baseline when creating your own plugins for PsychoStats.
**/
// The class name must be the same as the plugin directory or filename.
// all plugins must inherhit PsychoPlugin
class helloworld extends PsychoPlugin {
var $version = '1.0';
var $errstr = '';
// called when the plugin is loaded. This is called on every page request.
// You'll want to register all your hooks here.
function load(&$cms) {
// an example of registering a hook. In this case we register a filter
// on the 'overall_header' hook. Our class needs a 'filter_overall_header'
// method that will be called automatically when the hook triggers.
$cms->register_filter($this, 'overall_header');
// If loading fails, a plugin should set the error string $errstr
// and return false
if ('something broke' and false) {
$this->errstr = "Error loading plugin";
return false;
}
// return true if everything is loaded ok
return true;
}
// The install method is called when a plugin is installed by an admin in the ACP.
// This is only called once. This is a good place to initialize
// things like database tables, etc.
// This should return an array of metadata that describes your plugin or
// FALSE if the install failed.
function install(&$cms) {
$info = array();
$info['version'] = $this->version;
$info['description'] = "This is an example plugin that does nothing useful. " .
"View the plugin code to see how to make your own plugins!";
return $info;
}
// The uninstall method is called when a plugin in UNinstalled by an admin in the ACP.
// this is only called once. This is a good place to remove anything you initialized
// from the install method originally.
function uninstall(&$cms) {
return true;
}
// our filter hook. This is called automatically when the 'overall_header' hook is
// triggered. This is a filter which means we're given a reference to a string (or
// other object). Any changes to the $output will be permanent.
function filter_overall_header(&$output, &$cms, $args = array()) {
// $output = strtoupper($output);
$output .= "<b>$this</b> updated the overall header!<br>";
}
} // END of class
?>
