path: root/ratatoeskr/sys/plugin_api.php

<?php
/*
 * File: 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.
 */

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).
 */
$api_compat = array(3, 4, 5, 6);

$url_handlers = array(); /* master URL handler */

/*
 * Function: register_url_handler
 * 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>).
 */
function register_url_handler($name, $callback)
{
    global $url_handlers;
    $url_handlers[$name] = $callback;
}

$pluginpages_handlers = array();

$articleeditor_plugins = array();

/*
 * 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.
     */
    protected $kvstorage;
    protected $ste;
    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).
     */
    public function __construct($id)
    {
        global $ste, $rel_path_to_root;
        $this->id        = $id;

        $this->kvstorage        = new PluginKVStorage($id);
        $this->ste              = $ste;
        $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.
     */
    final public function    get_id()             { return $this->id;                                                                         }
    final protected function get_custompriv_dir() { return SITE_BASE_PATH . "/ratatoeskr/plugin_extradata/private/" . $this->id;              }
    final protected function get_custompub_dir()  { return SITE_BASE_PATH . "/ratatoeskr/plugin_extradata/public/" . $this->id;               }
    final protected function get_custompub_url()  { return $GLOBALS["rel_path_to_root"] . "/ratatoeskr/plugin_extradata/public/" . $this->id; }
    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.
     */
    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.
     */
    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.
     */
    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).
     *
     * Parameters:
     *  $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).
     */
    final protected function register_on_comment_store($fx)
    {
        global $on_comment_store;
        $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.
     *
     * 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>
     */
    final protected function register_backend_pluginpage($label, $fx)
    {
        global $pluginpages_handlers;

        $this->ste->vars["pluginpages"][$this->id] = $label;
        asort($this->ste->vars["pluginpages"]);
        $pluginid = $this->id;
        $pluginpages_handlers["p{$this->id}"] = function(&$data, $url_now, &$url_next) use($pluginid, $fx)
        {
            global $ste, $rel_path_to_root;
            $ste->vars["rel_path_to_pluginpage"] = "$rel_path_to_root/backend/pluginpages/p$pluginid";
            $rv = call_user_func_array($fx, array(&$data, $url_now, &$url_next));
            unset($ste->vars["rel_path_to_pluginpage"]);
            return $rv;
        };
    }

    /*
     * 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.
     */
    final protected function register_articleeditor_plugin($label, $fx, $template)
    {
        global $articleeditor_plugins;

        $articleeditor_plugins[] = array(
            "label"    => $label,
            "fx"       => $fx,
            "template" => $this->get_template_dir() . "/" . $template,
            "display"  => $template != NULL
        );
    }

    /*
     * Function: get_backend_pluginpage_url
     * Get the URL to your backend plugin page.
     *
     * Returns:
     *  The URL to your backend plugin page.
     */
    final protected function get_backend_pluginpage_url()
    {
        global $rel_path_to_root;
        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.
     *
     * Returns:
     *  An <ArticleExtradata> object for this plugin and the given article.
     */
    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()
    {
        $this->ste->vars["section"]   = "plugins";
        $this->ste->vars["submenu"]   = "plugin" . $this->id;
        $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.
     */
    public function init() {}
    public function atexit() {}
    public function install() {}
    public function uninstall() {}
    public function update() {}
}

?>