aboutsummaryrefslogtreecommitdiff
path: root/ratatoeskr
diff options
context:
space:
mode:
Diffstat (limited to 'ratatoeskr')
-rw-r--r--ratatoeskr/sys/plugin_api.php205
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()
{
}