Skip to content
Snippets Groups Projects
Commit f65bfee1 authored by chris's avatar chris
Browse files

action plugins 

This patch adds events and a third plugin type, "action" plugins, to DokuWiki.

The patch doesn't include any event signalling, that will be added in later patches.

Action plugins are loaded before most Dokuwiki processing takes place and at the
same time are given the opportunity to register handlers (or hooks) to receive
specific dokuwiki events.

Other parts of Dokuwiki (e.g. templates and syntax plugins) can also register
handlers to receive events.

Any part of Dokuwiki can create and signal events, including templates and plugins.

This patch also revises the admin plugin class by making it an extension of a
new class, DokuWiki_Plugin. The DokuWiki_Plugin_Action class also extends this
new class.

Further details of events, their signalling and handling, and of action plugins will
be added to wiki.splitbrain.org in due course :-)

darcs-hash:20060414193737-9b6ab-f23d3d9b93e4c50a3ad97ced03eabc6c0363650b.gz
parent c4e0e4a1
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doku.php
+ 1
− 0
View file @ f65bfee1
......@@ -11,6 +11,7 @@
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__)).'/');
require_once(DOKU_INC.'inc/init.php');
require_once(DOKU_INC.'inc/common.php');
require_once(DOKU_INC.'inc/events.php');
require_once(DOKU_INC.'inc/pageutils.php');
require_once(DOKU_INC.'inc/html.php');
require_once(DOKU_INC.'inc/auth.php');
......
inc/events.php 0 → 100644
+ 162
− 0
View file @ f65bfee1
<?php
/**
* DokuWiki Events
*
* @license GPL 2 (http://www.gnu.org/licenses/gpl.html)
* @author Christopher Smith <chris@jalakai.co.uk>
*/
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../').'/');
require_once(DOKU_INC.'inc/pluginutils.php');
class event {
// public properties
var $name = ''; // event name, objects must register against this name to see the event
var $data = NULL; // data relevant to the event, no standardised format (YET!)
var $result = NULL; // the results of the event action, only relevant in "*_after" advise
// private properties
var $_default = true; // whether or not to carry out the default action associated with the event
var $_continue = true; // whether or not to continue propagating the event to other handlers
var $_action = NULL; // the function executed to carry out the event
/**
* event constructor
*/
function event($name, &$data, $fn=NULL) {
$this->name = $name;
$this->data =& $data;
$this->_action = $fn;
}
/**
* advise
*
* advise all registered handlers of this event
* any processing based on the event's _default property to be determined by the caller
*
* @return results of processing the event, usually $this->_default
*/
function advise() {
global $EVENT_HANDLER;
return $EVENT_HANDLER->process_event($this,'');
}
/**
* trigger
*
* advise all registered (<event>_before) handlers that this event is about to take place
* carry out the default action using $this->data based on $this->_default, all of which
* may have been modified by the event handlers
* if the action was carried out, advise all registered (<event>_after) handlers that the
* event has taken place
*
* @return $event->results
* the value set by any <event>_before or <event> handlers if the default action is prevented
* or the results of the default action (as modified by <event>_after handlers)
* or NULL no action took place and no handler modified the value
*/
function trigger() {
global $EVENT_HANDLER;
$EVENT_HANDLER->process_event($this,'before');
if ($this->_continue) $EVENT_HANDLER->process_event($this,'');
if ($this->_default && is_callable($this->_action)) {
if (is_array($this->_action)) {
list($obj,$method) = $this->_action;
$this->result = $obj->$method($this->data);
} else {
$fn = $this->_action;
$this->result = $fn($this->data);
}
$EVENT_HANDLER->process_event($this,'after');
}
return $this->result;
}
/**
* stopPropagation
*
* stop any further processing of the event by event handlers
* this function does not prevent the default action taking place
*/
function stopPropagation() { $this->_continue = false; }
/**
* preventDefault
*
* prevent the default action taking place
*/
function preventDefault() { $this->_default = false; }
}
class event_handler {
// public properties: none
// private properties
var $_hooks = array(); // array of events and their registered handlers
/*
* event_handler
*
* constructor, loads all action plugins and calls their register() method giving them
* an opportunity to register any hooks they require
*/
function event_handler() {
// load action plugins
$plugin = NULL;
$pluginlist = plugin_list('action');
foreach ($pluginlist as $plugin_name) {
$plugin =& plugin_load('action',$plugin_name);
if ($plugin !== NULL) $plugin->register($this);
}
}
/*
* register_hook
*
* register a hook for an event
*
* @PARAM $event (string) name used by the event, (incl '_before' or '_after' for triggers)
* @PARAM $obj (obj) object in whose scope method is to be executed,
* if NULL, method is assumed to be a globally available function
* @PARAM $method (function) event handler function
* @PARAM $param (mixed) data passed to the event handler
*/
function register_hook($event, &$obj, $method, $param) {
$this->_hooks[$event][] = array($obj, $method, $param);
}
function process_event(&$event,$advise='') {
$evt_name = $event->name . ($advise ? '_'.$advise : '');
if (!empty($this->_hooks[$evt_name])) {
$hook = reset($this->_hooks[$evt_name]);
do {
list($obj, $method, $param) = $hook;
if (is_null($obj)) {
$method($param, $event);
} else {
$obj->$method($param, $event);
}
} while ($event->_continue && $hook = next($this->_hooks[$evt_name]));
}
return $event->_default;
}
}
// create the event handler
$EVENT_HANDLER = new event_handler();
inc/pluginutils.php
+ 1
− 1
View file @ f65bfee1
......@@ -7,7 +7,7 @@
*/
// plugin related constants
$plugin_types = array('admin','syntax');
$plugin_types = array('admin','syntax','action');
/**
* Returns a list of available plugins of given type
......
lib/plugins/action.php 0 → 100644
+ 24
− 0
View file @ f65bfee1
<?php
/**
* Admin Plugin Prototype
*
* @license GPL 2 (http://www.gnu.org/licenses/gpl.html)
* @author Christopher Smith <chris@jalakai.co.uk>
*/
// must be run within Dokuwiki
if(!defined('DOKU_INC')) die();
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'base.php');
/**
* All DokuWiki plugins to extend the admin function
* need to inherit from this class
*/
class DokuWiki_Action_Plugin extends DokuWiki_Plugin {
function register($controller) {
trigger_error('register() not implemented in '.get_class($this), E_USER_WARNING);
}
}
\ No newline at end of file
lib/plugins/admin.php
+ 2
− 174
View file @ f65bfee1
......@@ -9,32 +9,13 @@
if(!defined('DOKU_INC')) die();
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'base.php');
/**
* All DokuWiki plugins to extend the admin function
* need to inherit from this class
*/
class DokuWiki_Admin_Plugin {
var $localised = false; // set to true by setupLocale() after loading language dependent strings
var $lang = array(); // array to hold language dependent strings, best accessed via ->getLang()
var $configloaded = false; // set to true by loadConfig() after loading plugin configuration variables
/**
* General Info
*
* Needs to return a associative array with the following values:
*
* author - Author of the plugin
* email - Email address to contact the author
* date - Last modified date of the plugin in YYYY-MM-DD format
* name - Name of the plugin
* desc - Short description of the plugin (Text only)
* url - Website with more information on the plugin (eg. syntax description)
*/
function getInfo(){
trigger_error('getInfo() not implemented in '.get_class($this), E_USER_WARNING);
}
class DokuWiki_Admin_Plugin extends DokuWiki_Plugin {
function getMenuText($language) {
$menutext = $this->getLang('menu');
......@@ -56,160 +37,7 @@ class DokuWiki_Admin_Plugin {
function html() {
trigger_error('html() not implemented in '.get_class($this), E_USER_WARNING);
}
// private methods (maybe a dokuwiki plugin base class is required for these)
// plugin introspection methods
// extract from class name, format = <plugin type>_plugin_<name>[_<component name>]
function getPluginType() { list($t) = explode('_', get_class($this), 2); return $t; }
function getPluginName() { list($t, $p, $n) = explode('_', get_class($this), 4); return $n; }
function getPluginComponent() { list($t, $p, $n, $c) = explode('_', get_class($this), 4); return (isset($c)?$c:''); }
// localisation methods
/**
* getLang($id)
* use this function to access plugin language strings
* to try to minimise unnecessary loading of the strings when the plugin doesn't require them
* e.g. when info plugin is querying plugins for information about themselves.
*
* @param $id id of the string to be retrieved
* @return string string in appropriate language or english if not available
*/
function getLang($id) {
if (!$this->localised) $this->setupLocale();
return (isset($this->lang[$id]) ? $this->lang[$id] : '');
}
/**
* locale_xhtml($id)
*
* retrieve a language dependent file and pass to xhtml renderer for display
* plugin equivalent of p_locale_xhtml()
*
* @param $id id of language dependent wiki page
* @return string parsed contents of the wiki page in xhtml format
*/
function locale_xhtml($id) {
return p_cached_xhtml($this->localFN($id));
}
/**
* localFN($id)
* prepends appropriate path for a language dependent filename
* plugin equivalent of localFN()
*/
function localFN($id) {
global $conf;
$plugin = $this->getPluginName();
$file = DOKU_PLUGIN.$plugin.'/lang/'.$conf['lang'].'/'.$id.'.txt';
if(!@file_exists($file)){
//fall back to english
$file = DOKU_PLUGIN.$plugin.'/lang/en/'.$id.'.txt';
}
return $file;
}
/**
* setupLocale()
* reads all the plugins language dependent strings into $this->lang
* this function is automatically called by getLang()
*/
function setupLocale() {
if ($this->localised) return;
global $conf; // definitely don't invoke "global $lang"
$path = DOKU_PLUGIN.$this->getPluginName().'/lang/';
$lang = array();
// don't include once, in case several plugin components require the same language file
@include($path.'en/lang.php');
if ($conf['lang'] != 'en') @include($path.$conf['lang'].'/lang.php');
$this->lang = $lang;
$this->localised = true;
}
// configuration methods
/**
* getConf($id)
*
* use this function to access plugin configuration variables
*/
function getConf($id){
global $conf;
$plugin = $this->getPluginName();
if (!$this->configloaded){
if ($pconf = $this->loadConfig() !== false){
foreach ($pconf as $key => $value){
if (isset($conf['plugin'][$plugin][$key])) continue;
$conf['plugin'][$plugin][$key] = $value;
}
$this->configloaded = true;
}
}
return $conf['plugin'][$plugin][$id];
}
/**
* loadConfig()
* reads all plugin configuration variables into $this->conf
* this function is automatically called by getConf()
*/
function loadConfig(){
$path = DOKU_PLUGIN.$this->getPluginName().'/conf/';
$conf = array();
if (!@file_exists($path.'default.php')) return false;
// load default config file
include($path.'default.php');
return $conf;
}
// standard functions for outputing email addresses and links
// use these to avoid having to duplicate code to produce links in line with the installation configuration
function email($email, $name='', $class='', $more='') {
if (!$email) return $name;
$email = obfuscate($email);
if (!$name) $name = $email;
$class = "class='".($class ? $class : 'mail')."'";
return "<a href='mailto:$email' $class title='$email' $more>$name</a>";
}
function external_link($link, $title='', $class='', $target='', $more='') {
global $conf;
$link = htmlentities($link);
if (!$title) $title = $link;
if (!$target) $target = $conf['target']['extern'];
if ($conf['relnofollow']) $more .= ' rel="nofollow"';
if ($class) $class = " class='$class'";
if ($target) $target = " target='$target'";
if ($more) $more = " ".trim($more);
return "<a href='$link'$class$target$more>$title</a>";
}
// output text string through the parser, allows dokuwiki markup to be used
// very ineffecient for small pieces of data - try not to use
function render($text, $format='xhtml') {
return p_render($format, p_get_instructions($text),$info);
}
// deprecated functions
function plugin_localFN($id) { return $this->localFN($id); }
function plugin_locale_xhtml($id) { return $this->locale_xhtml($id); }
function plugin_email($e, $n='', $c='', $m='') { return $this->email($e, $n, $c, $m); }
function plugin_link($l, $t='', $c='', $to='', $m='') { return $this->external_link($l, $t, $c, $to, $m); }
function plugin_render($t, $f='xhtml') { return $this->render($t, $f); }
}
//Setup VIM: ex: et ts=4 enc=utf-8 :
\ No newline at end of file
lib/plugins/base.php 0 → 100644
+ 190
− 0
View file @ f65bfee1
<?php
/**
* Admin Plugin Prototype
*
* @license GPL 2 (http://www.gnu.org/licenses/gpl.html)
* @author Christopher Smith <chris@jalakai.co.uk>
*/
// must be run within Dokuwiki
if(!defined('DOKU_INC')) die();
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
/**
* All DokuWiki plugins to extend the admin function
* need to inherit from this class
*/
class DokuWiki_Plugin {
var $localised = false; // set to true by setupLocale() after loading language dependent strings
var $lang = array(); // array to hold language dependent strings, best accessed via ->getLang()
var $configloaded = false; // set to true by loadConfig() after loading plugin configuration variables
/**
* General Info
*
* Needs to return a associative array with the following values:
*
* author - Author of the plugin
* email - Email address to contact the author
* date - Last modified date of the plugin in YYYY-MM-DD format
* name - Name of the plugin
* desc - Short description of the plugin (Text only)
* url - Website with more information on the plugin (eg. syntax description)
*/
function getInfo(){
trigger_error('getInfo() not implemented in '.get_class($this), E_USER_WARNING);
}
// plugin introspection methods
// extract from class name, format = <plugin type>_plugin_<name>[_<component name>]
function getPluginType() { list($t) = explode('_', get_class($this), 2); return $t; }
function getPluginName() { list($t, $p, $n) = explode('_', get_class($this), 4); return $n; }
function getPluginComponent() { list($t, $p, $n, $c) = explode('_', get_class($this), 4); return (isset($c)?$c:''); }
// localisation methods
/**
* getLang($id)
* use this function to access plugin language strings
* to try to minimise unnecessary loading of the strings when the plugin doesn't require them
* e.g. when info plugin is querying plugins for information about themselves.
*
* @param $id id of the string to be retrieved
* @return string string in appropriate language or english if not available
*/
function getLang($id) {
if (!$this->localised) $this->setupLocale();
return (isset($this->lang[$id]) ? $this->lang[$id] : '');
}
/**
* locale_xhtml($id)
*
* retrieve a language dependent file and pass to xhtml renderer for display
* plugin equivalent of p_locale_xhtml()
*
* @param $id id of language dependent wiki page
* @return string parsed contents of the wiki page in xhtml format
*/
function locale_xhtml($id) {
return p_cached_xhtml($this->localFN($id));
}
/**
* localFN($id)
* prepends appropriate path for a language dependent filename
* plugin equivalent of localFN()
*/
function localFN($id) {
global $conf;
$plugin = $this->getPluginName();
$file = DOKU_PLUGIN.$plugin.'/lang/'.$conf['lang'].'/'.$id.'.txt';
if(!@file_exists($file)){
//fall back to english
$file = DOKU_PLUGIN.$plugin.'/lang/en/'.$id.'.txt';
}
return $file;
}
/**
* setupLocale()
* reads all the plugins language dependent strings into $this->lang
* this function is automatically called by getLang()
*/
function setupLocale() {
if ($this->localised) return;
global $conf; // definitely don't invoke "global $lang"
$path = DOKU_PLUGIN.$this->getPluginName().'/lang/';
$lang = array();
// don't include once, in case several plugin components require the same language file
@include($path.'en/lang.php');
if ($conf['lang'] != 'en') @include($path.$conf['lang'].'/lang.php');
$this->lang = $lang;
$this->localised = true;
}
// configuration methods
/**
* getConf($id)
*
* use this function to access plugin configuration variables
*/
function getConf($id){
global $conf;
$plugin = $this->getPluginName();
if (!$this->configloaded){
if ($pconf = $this->loadConfig() !== false){
foreach ($pconf as $key => $value){
if (isset($conf['plugin'][$plugin][$key])) continue;
$conf['plugin'][$plugin][$key] = $value;
}
$this->configloaded = true;
}
}
return $conf['plugin'][$plugin][$id];
}
/**
* loadConfig()
* reads all plugin configuration variables into $this->conf
* this function is automatically called by getConf()
*/
function loadConfig(){
$path = DOKU_PLUGIN.$this->getPluginName().'/conf/';
$conf = array();
if (!@file_exists($path.'default.php')) return false;
// load default config file
include($path.'default.php');
return $conf;
}
// standard functions for outputing email addresses and links
// use these to avoid having to duplicate code to produce links in line with the installation configuration
function email($email, $name='', $class='', $more='') {
if (!$email) return $name;
$email = obfuscate($email);
if (!$name) $name = $email;
$class = "class='".($class ? $class : 'mail')."'";
return "<a href='mailto:$email' $class title='$email' $more>$name</a>";
}
function external_link($link, $title='', $class='', $target='', $more='') {
global $conf;
$link = htmlentities($link);
if (!$title) $title = $link;
if (!$target) $target = $conf['target']['extern'];
if ($conf['relnofollow']) $more .= ' rel="nofollow"';
if ($class) $class = " class='$class'";
if ($target) $target = " target='$target'";
if ($more) $more = " ".trim($more);
return "<a href='$link'$class$target$more>$title</a>";
}
// output text string through the parser, allows dokuwiki markup to be used
// very ineffecient for small pieces of data - try not to use
function render($text, $format='xhtml') {
return p_render($format, p_get_instructions($text),$info);
}
// deprecated functions
function plugin_localFN($id) { return $this->localFN($id); }
function plugin_locale_xhtml($id) { return $this->locale_xhtml($id); }
function plugin_email($e, $n='', $c='', $m='') { return $this->email($e, $n, $c, $m); }
function plugin_link($l, $t='', $c='', $to='', $m='') { return $this->external_link($l, $t, $c, $to, $m); }
function plugin_render($t, $f='xhtml') { return $this->render($t, $f); }
}
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment