diff options
Diffstat (limited to 'ratatoeskr')
| -rw-r--r-- | ratatoeskr/sys/plugin_api.php | 205 |
1 files changed, 105 insertions, 100 deletions
diff --git a/ratatoeskr/sys/plugin_api.php b/ratatoeskr/sys/plugin_api.php index 18e129b..c286fdc 100644 --- a/ratatoeskr/sys/plugin_api.php +++ b/ratatoeskr/sys/plugin_api.php @@ -9,31 +9,29 @@ * See "ratatoeskr/licenses/ratatoeskr" for more information. */ +use r7r\ste\STECore; + require_once(dirname(__FILE__) . "/models.php"); require_once(dirname(__FILE__) . "/textprocessors.php"); require_once(dirname(__FILE__) . "/../frontend.php"); -/* - * Constant: APIVERSION +/** * The current API version (6). */ define("APIVERSION", 6); -/* - * Array: $api_compat - * Array of API versions, this version is compatible to (including itself). +/** + * @var int[] Array of API versions, this version is compatible to (including itself). */ $api_compat = [3, 4, 5, 6]; $url_handlers = []; /* master URL handler */ -/* - * Function: register_url_handler - * Register an URL handler. See <ratatoeskr/sys/urlprocess.php> for more details. +/** + * Register an URL handler. See ratatoeskr/sys/urlprocess.php for more details. * - * Parameters: - * $name - The name of the new URL - * $callback - The Function to be called (see <url_process>). + * @param string $name The name of the new URL + * @param callable $callback The Function to be called (see <url_process>). */ function register_url_handler($name, callable $callback) { @@ -45,32 +43,27 @@ $pluginpages_handlers = []; $articleeditor_plugins = []; -/* - * 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. - * $ste - Access to the global STECore object. - * $rel_path_to_root - Relative URL to the root of the page. - */ + /** @var PluginKVStorage The Key-Value-Storage for the Plugin */ protected $kvstorage; + + /** @var STECore Access to the global STECore object */ protected $ste; + + /** @var string Relative URL to the root of the page */ protected $rel_path_to_root; - /* - * 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). + * @param int $id - The ID of the plugin (not the name). */ public function __construct($id) { @@ -82,96 +75,103 @@ abstract class RatatoeskrPlugin $this->rel_path_to_root = $rel_path_to_root; } - /* - * Functions: Some getters - * - * get_id - get the Plugin-ID - * get_custompriv_dir - Get path to the custompriv directory of your plugin. - * get_custompub_dir - Get path to the custompub directory of your plugin. - * get_custompub_url - Get URL (can be accessed from the web) to the custompub directory of your plugin. - * get_template_dir - Get path to your template directory to be used with STE. + /** + * Get the Plugin-ID + * @return int */ final public function get_id() { return $this->id; } + + /** + * Get path to the custompriv directory of your plugin. + * @return string + */ final protected function get_custompriv_dir() { return SITE_BASE_PATH . "/ratatoeskr/plugin_extradata/private/" . $this->id; } + + /** + * Get path to the custompub directory of your plugin. + * @return string + */ final protected function get_custompub_dir() { return SITE_BASE_PATH . "/ratatoeskr/plugin_extradata/public/" . $this->id; } + + /** + * Get URL (can be accessed from the web) to the custompub directory of your plugin. + * @return string + */ final protected function get_custompub_url() { return $GLOBALS["rel_path_to_root"] . "/ratatoeskr/plugin_extradata/public/" . $this->id; } + + /** + * Get path to your template directory to be used with STE. + * @return string + */ final protected function get_template_dir() { return "/plugintemplates/" . $this->id; } - /* - * Function: register_url_handler + /** * Register a URL handler * - * Parameters: - * $name - Name of URL - * $fx - The function. + * @param string $name Name of URL + * @param callable $fx The function. */ final protected function register_url_handler($name, $fx) { register_url_handler($name, $fx); } - /* - * Function: register_ste_tag + /** * Register a custom STE tag. * - * Parameters: - * $name - Name of your new STE tag. - * $fx - Function to register with this tag. + * @param string $name Name of your new STE tag. + * @param callable $fx Function to register with this tag. */ final protected function register_ste_tag($name, $fx) { $this->ste->register_tag($name, $fx); } - /* - * Function: register_textprocessor + /** * Register a textprocessor. * - * Parameters: - * $name - The name of the textprocessor- - * $fx - Function to register (function($input), returns HTML). - * $visible_in_backend - Should this textprocessor be visible in the backend? Defaults to True. + * @param string $name The name of the textprocessor- + * @param callable $fx Function to register (function($input), returns HTML). + * @param bool $visible_in_backend Should this textprocessor be visible in the backend? Defaults to True. */ final protected function register_textprocessor($name, $fx, $visible_in_backend=true) { textprocessor_register($name, $fx, $visible_in_backend); } - /* - * Function: register_comment_validator + /** * Register a comment validator. * - * A comment validator is a function, that checks the $_POST fields and decides whether a comment should be stored or not (throws an <CommentRejected> exception with the rejection reason as the message). + * A comment validator is a function, that checks the $_POST fields and decides whether a comment should be stored + * or not (throws an (@see CommentRejected} exception with the rejection reason as the message). * - * Parameters: - * $fx - Validator function. + * @param callable $fx Validator function. */ final protected function register_comment_validator($fx) { global $comment_validators; $comment_validators[] = $fx; } - /* - * Function: register_on_comment_store + + /** * Register a function that will be called, after a comment was saved. * - * Parameters: - * $fx - Function, that accepts one parameter (a <Comment> object). + * @param callable $fx Function, that accepts one parameter (a {@see Comment} object). */ final protected function register_on_comment_store($fx) { @@ -179,20 +179,19 @@ abstract class RatatoeskrPlugin $on_comment_store[] = $fx; } - /* - * Function: register_backend_pluginpage + /** * Register a backend subpage for your plugin. * - * Parameters: - * $label - The label for the page. - * $fx - A function for <url_process>. + * Your $fx should output output the result of a STE template, which should + * load "/systemtemplates/master.html" and overwrite the "content" section. * - * Your $fx should output output the result of a STE template, which should load "/systemtemplates/master.html" and overwrite the "content" section. + * If you need a URL to your pluginpage, you can use {@see RatatoeskrPlugin::get_backend_pluginpage_url()} and the + * STE variable $rel_path_to_pluginpage. * - * If you need a URL to your pluginpage, you can use <get_backend_pluginpage_url> and the STE variable $rel_path_to_pluginpage. + * See also {@see RatatoeskrPlugin::prepare_backend_pluginpage()} * - * See also: - * <prepare_backend_pluginpage> + * @param string $label The label for the page. + * @param callable $fx A function for <url_process>. */ final protected function register_backend_pluginpage($label, $fx) { @@ -210,20 +209,23 @@ abstract class RatatoeskrPlugin }; } - /* - * Function: register_articleeditor_plugin + /** * Register a plugin for the article editor in the backend. * - * Parameters: - * $label - The label for the plugin. - * $fx - A function that will be called during the articleeditor. - * This function must accept these parameters: - * * $article - An <Article> object or NULL, if no Article is edited right now. - * * $about_to_save - If True, the article is about to be saved. - * If you want to veto the saving, return the rejection reason as a string. - * If everything is okay and you need to save additional data, return a callback function that accepts the saved <Article> object (that callback should also write data back to the template, if necessary). - * If everything is okay and you do not need to save additional data, return NULL. - * $template - The name of the template to display in the editor, relative to your template directory. If you do not want to display anything, you can set ths to NULL. + * You $fx function must take two parameters: + * + * - $article: + * An {@see Article} object or null, if no Article is edited right now. + * - $about_to_save: + * If true, the article is about to be saved. + * If you want to veto the saving, return the rejection reason as a string. + * If everything is okay and you need to save additional data, return a callback function that + * accepts the saved {@see Article} object (that callback should also write data back to the template, if necessary). + * If everything is okay and you do not need to save additional data, return NULL. + * + * @param string $label The label for the plugin. + * @param callable $fx A function that will be called during the articleeditor. See above for a detailed explanation. + * @param string|null $template The name of the template to display in the editor, relative to your template directory. If you do not want to display anything, you can set ths to NULL. */ final protected function register_articleeditor_plugin($label, $fx, $template) { @@ -237,12 +239,10 @@ abstract class RatatoeskrPlugin ]; } - /* - * Function: get_backend_pluginpage_url + /** * Get the URL to your backend plugin page. * - * Returns: - * The URL to your backend plugin page. + * @return string The URL to your backend plugin page. */ final protected function get_backend_pluginpage_url() { @@ -250,23 +250,18 @@ abstract class RatatoeskrPlugin return "$rel_path_to_root/backend/pluginpages/p{$this->id}"; } - /* - * Function: get_article_extradata - * Get the <ArticleExtradata> object for this plugin and the given article. - * - * Parameters: - * $article - An <Article> object. + /** + * Get the {@see ArticleExtradata} object for this plugin and the given article. * - * Returns: - * An <ArticleExtradata> object for this plugin and the given article. + * @param Article $article + * @return ArticleExtradata */ final protected function get_article_extradata($article) { return new ArticleExtradata($article->get_id(), $this->id); } - /* - * Function: prepare_backend_pluginpage + /** * Automatically sets the page title and highlights the menu-entry of your backend subpage. */ final protected function prepare_backend_pluginpage() @@ -276,27 +271,37 @@ abstract class RatatoeskrPlugin $this->ste->vars["pagetitle"] = $this->ste->vars["pluginpages"][$this->id]; } - /* - * Functions: Functions that are called at special events - * - * init - Will be called after plugin is loaded. You should register your stuff here. - * atexit - Will be called, when Ratatöskr will exit. - * 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. - * update - Will be called after your plugin was updated to a new version. + /** + * Will be called after plugin is loaded. You should register your stuff here. */ public function init() { } + + /** + * Will be called, when Ratatöskr will exit. + */ public function atexit() { } + + /** + * Will be called after installation. If your plugin needs to initialize some database stuff or generate files, this is the right function. + */ public function install() { } + + /** + * Will be called during uninstallation. If you used the install function you should undo your custom installation stuff. + */ public function uninstall() { } + + /** + * Will be called after your plugin was updated to a new version. + */ public function update() { } |