From bd745354de0247ff4d1903cb9d96fd50dfb4bfce Mon Sep 17 00:00:00 2001 From: Kevin Chabowski Date: Sun, 14 Aug 2011 21:47:03 +0200 Subject: Continued work on the plugin API and added some documentation. --- ratatoeskr/sys/plugin_api.php | 72 +++++++++++++++++++++++++++++++++++++++++-- ratatoeskr/sys/urlprocess.php | 46 ++++++++++++++++++++++++++- 2 files changed, 114 insertions(+), 4 deletions(-) diff --git a/ratatoeskr/sys/plugin_api.php b/ratatoeskr/sys/plugin_api.php index e021e15..e5625f8 100644 --- a/ratatoeskr/sys/plugin_api.php +++ b/ratatoeskr/sys/plugin_api.php @@ -9,28 +9,94 @@ * See "ratatoeskr/licenses/ratatoeskr" for more information. */ -require_once(dirname(__FILE__) . "/db.php"); - +require_once(dirname(__FILE__) . "/models.php"); +/* + * Class: RatatoeskrPlugin + * An abstract class to be extended in order to write your own Plugin. + */ abstract class RatatoeskrPlugin { private $id; + + /* + * Variables: Protected variables + * + * $kvstorage - The Key-Value-Storage for the Plugin. + * $smarty - Access to the global smarty object. + */ protected $kvstorage; protected $smarty; + + /* + * Constructor: __construct + * Performing some neccessary initialisation stuff. + * If you are overwriting this function, you *really* should call parent::__construct! + * + * Parameters: + * $id - The ID of the plugin (not the name). + */ public function __construct($id) { global $smarty; $this->id = $id; + $this->kvstorage = new PluginKVStorage($id); $this->smarty = $smarty; } - public function get_id() { return $this->id; } + /* + * Functions: Some getters + * + * get_id - get the Plugin-ID + * get_additional_files_dir - Path to directory with the additional files + * get_template_dir - Path to template directory + */ + final public function get_id() { return $this->id; } + final protected function get_additional_files_dir() { return dirname(dirname(__FILE__)) . "/plugin_extradata/" . $this->id; } + final protected function get_template_dir() { return dirname(dirname(__FILE__)) . "/templates/plugintemplates/" . $this->id; } + + /* + * Function: register_url_handler + * Easy way for register a URL handler + * + * Parameters: + * $name - Name of URL + * $objfunction - Name of object function. + */ + final protected function register_url_handler($name, $objfunction) + { + register_url_handler($name, array($this, $objfunction)); + } + final protected function register_settings_page($get, $validate, $set, $structure) + + /* + * Functions: Functions that are called at special events + * + * init - Will be called after plugin is loaded. You should register your stuff here. + * install - Will be called after installation. If your plugin needs to initialize some database stuff or generate files, this is the right function. + * uninstall - Will be called during uninstallation. If you used the install function you should undo your custom installation stuff. + */ public function init() {} public function install() {} public function uninstall() {} } +$url_handlers = array(); +/* + * Function: register_url_handler + * Register an URL handler. See for more details. + * + * Parameters: + * $name - The name of the new URL + * $callback - The Function to be called (see ). + */ +function register_url_handler($name, $callback) +{ + global $url_handlers; + $url_handlers[$name] = $callback; +} + ?> diff --git a/ratatoeskr/sys/urlprocess.php b/ratatoeskr/sys/urlprocess.php index e81a0d4..2274197 100644 --- a/ratatoeskr/sys/urlprocess.php +++ b/ratatoeskr/sys/urlprocess.php @@ -9,6 +9,11 @@ * See "ratatoeskr/licenses/ratatoeskr" for more information. */ +/* + * Class: Redirect + * Exception that can be thrown inside an . + * throw new Redirect(array("..", "foo")); will redirect to "../foo" and won't touch $data. + */ class Redirect extends Exception { public $nextpath; @@ -18,9 +23,22 @@ class Redirect extends Exception parent::__construct(); } } - +/* + * Class: NotFoundError + * An Exception + */ class NotFoundError extends Exception { } +/* + * Function: url_action_simple + * Generate an action in a more simple way. + * + * Parameters: + * $function - A callback that gets the $data var as an input and returns the new $data var. Can throw an Exception. + * + * Returns: + * A callback that can be used as an url action. + */ function url_action_simple($function) { return function(&$data, $url_now, &$url_next) use ($function) @@ -37,6 +55,16 @@ function url_action_simple($function) }; } +/* + * Function: url_action_subactions + * Generate an action that contains subactions. Subactions can redirect to ".." to go to the level above. + * + * Parameters: + * $actions - Associative array of actions. + * + * Returns: + * A callback that can be used as an url action. + */ function url_action_subactions($actions) { return function (&$data, $url_now, &$url_next) use ($actions) @@ -47,6 +75,22 @@ function url_action_subactions($actions) }; } +/* + * Function: url_process + * Choose an appropiate action for the given URL. + * + * Parameters: + * $url - Either an array containing the URL components or the URL (both relative). + * $actions - Associative array of actions. + * Key is the name (anything alphanumeric, should usually not start with '_', reserved for special URL names, see beneath). + * Value is a callback of the form: function(&$data, $url_now, &$url_next). $data can be used for shared data between subactions. $url_next can be modified in order to redirect to another action / stop the routing. + * + * Special actions: + * _default - If nothing was found, this is the default. + * _notfound - If not even _default exists or NotFoundError was thrown. + * _prelude - If existant, will be executed before everything else. + * _epilog - If existant, will be executed after evrything else. + */ function url_process($url, $actions, &$data) { $epilog_running = 0; -- cgit v1.2.3-54-g00ecf