ratatoeskr/sys/plugin_api.php

Plugin API contains the plugin base class and other interfaces to Ratatöskr.

License

This file is part of Ratatöskr.  Ratatöskr is licensed unter the MIT / X11 License.  See “ratatoeskr/licenses/ratatoeskr” for more information.

Summary
ratatoeskr/sys/plugin_api.phpPlugin API contains the plugin base class and other interfaces to Ratatöskr.
Constants
APIVERSIONThe current API version (6).
Variables
$api_compatArray of API versions, this version is compatible to (including itself).
Functions
register_url_handlerRegister an URL handler.
RatatoeskrPluginAn abstract class to be extended in order to write your own Plugin.
Variables
Protected variables
Functions
__constructPerforming some neccessary initialisation stuff.
get_idget the Plugin-ID
get_custompriv_dirGet path to the custompriv directory of your plugin.
get_custompub_dirGet path to the custompub directory of your plugin.
get_custompub_urlGet URL (can be accessed from the web) to the custompub directory of your plugin.
get_template_dirGet path to your template directory to be used with STE.
register_url_handlerRegister a URL handler
register_ste_tagRegister a custom STE tag.
register_textprocessorRegister a textprocessor.
register_comment_validatorRegister a comment validator.
register_on_comment_storeRegister a function that will be called, after a comment was saved.
register_backend_pluginpageRegister a backend subpage for your plugin.
register_articleeditor_pluginRegister a plugin for the article editor in the backend.
get_backend_pluginpage_urlGet the URL to your backend plugin page.
get_article_extradataGet the ArticleExtradata object for this plugin and the given article.
prepare_backend_pluginpageAutomatically sets the page title and highlights the menu-entry of your backend subpage.
initWill be called after plugin is loaded.
atexitWill be called, when Ratatöskr will exit.
installWill be called after installation.
uninstallWill be called during uninstallation.
updateWill be called after your plugin was updated to a new version.

Constants

APIVERSION

The current API version (6).

Variables

$api_compat

$api_compat

Array of API versions, this version is compatible to (including itself).

Functions

register_url_handler

function register_url_handler($name,
$callback)

Register an URL handler.  See ratatoeskr/sys/urlprocess.php for more details.

Parameters

$nameThe name of the new URL
$callbackThe Function to be called (see url_process).

RatatoeskrPlugin

An abstract class to be extended in order to write your own Plugin.

Summary
Variables
Protected variables
Functions
__constructPerforming some neccessary initialisation stuff.
get_idget the Plugin-ID
get_custompriv_dirGet path to the custompriv directory of your plugin.
get_custompub_dirGet path to the custompub directory of your plugin.
get_custompub_urlGet URL (can be accessed from the web) to the custompub directory of your plugin.
get_template_dirGet path to your template directory to be used with STE.
register_url_handlerRegister a URL handler
register_ste_tagRegister a custom STE tag.
register_textprocessorRegister a textprocessor.
register_comment_validatorRegister a comment validator.
register_on_comment_storeRegister a function that will be called, after a comment was saved.
register_backend_pluginpageRegister a backend subpage for your plugin.
register_articleeditor_pluginRegister a plugin for the article editor in the backend.
get_backend_pluginpage_urlGet the URL to your backend plugin page.
get_article_extradataGet the ArticleExtradata object for this plugin and the given article.
prepare_backend_pluginpageAutomatically sets the page title and highlights the menu-entry of your backend subpage.
initWill be called after plugin is loaded.
atexitWill be called, when Ratatöskr will exit.
installWill be called after installation.
uninstallWill be called during uninstallation.
updateWill be called after your plugin was updated to a new version.

Variables

Protected variables

$kvstorageThe Key-Value-Storage for the Plugin.
$steAccess to the global STECore object.
$rel_path_to_rootRelative URL to the root of the page.

Functions

__construct

public function __construct($id)

Performing some neccessary initialisation stuff.  If you are overwriting this function, you really should call parent::__construct!

Parameters

$idThe ID of the plugin (not the name).

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.

register_url_handler

final protected function register_url_handler($name,
$fx)

Register a URL handler

Parameters

$nameName of URL
$fxThe function.

register_ste_tag

final protected function register_ste_tag($name,
$fx)

Register a custom STE tag.

Parameters

$nameName of your new STE tag.
$fxFunction to register with this tag.

register_textprocessor

final protected function register_textprocessor($name,  
$fx,  
$visible_in_backend = True)

Register a textprocessor.

Parameters

$nameThe name of the textprocessor-
$fxFunction to register (function($input), returns HTML).
$visible_in_backendShould this textprocessor be visible in the backend?  Defaults to True.

register_comment_validator

final protected function register_comment_validator($fx)

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).

Parameters

$fxValidator function.

register_on_comment_store

final protected function register_on_comment_store($fx)

Register a function that will be called, after a comment was saved.

Parameters

$fxFunction, that accepts one parameter (a Comment object).

register_backend_pluginpage

final protected function register_backend_pluginpage($label,
$fx)

Register a backend subpage for your plugin.

Parameters

$labelThe label for the page.
$fxA 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.

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

prepare_backend_pluginpage

register_articleeditor_plugin

final protected function register_articleeditor_plugin($label,
$fx,
$template)

Register a plugin for the article editor in the backend.

Parameters

$labelThe label for the plugin.
$fxA 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.
$templateThe 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.

get_backend_pluginpage_url

final protected function get_backend_pluginpage_url()

Get the URL to your backend plugin page.

Returns

The URL to your backend plugin page.

get_article_extradata

final protected function get_article_extradata($article)

Get the ArticleExtradata object for this plugin and the given article.

Parameters

$articleAn Article object.

Returns

An ArticleExtradata object for this plugin and the given article.

prepare_backend_pluginpage

final protected function prepare_backend_pluginpage()

Automatically sets the page title and highlights the menu-entry of your backend subpage.

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.

$api_compat
Array of API versions, this version is compatible to (including itself).
function register_url_handler($name,
$callback)
Register an URL handler.
public function __construct($id)
Performing some neccessary initialisation stuff.
final protected function register_url_handler($name,
$fx)
Register a URL handler
final protected function register_ste_tag($name,
$fx)
Register a custom STE tag.
final protected function register_textprocessor($name,  
$fx,  
$visible_in_backend = True)
Register a textprocessor.
final protected function register_comment_validator($fx)
Register a comment validator.
final protected function register_on_comment_store($fx)
Register a function that will be called, after a comment was saved.
final protected function register_backend_pluginpage($label,
$fx)
Register a backend subpage for your plugin.
final protected function register_articleeditor_plugin($label,
$fx,
$template)
Register a plugin for the article editor in the backend.
final protected function get_backend_pluginpage_url()
Get the URL to your backend plugin page.
final protected function get_article_extradata($article)
Get the ArticleExtradata object for this plugin and the given article.
A Key-Value-Storage assigned to Articles for plugins to store additional data.
final protected function prepare_backend_pluginpage()
Automatically sets the page title and highlights the menu-entry of your backend subpage.
Providing functions / classes to handle URLs
function url_process($url,
$actions,
&$data)
Choose an appropiate action for the given URL.
An Exeption a comment validator can throw, if the validation failed.
Representing a user comment
Representation of an article
Close