inc/PluginInterface.php

   1 <?php
   2 /**
   3  * DokuWiki Plugin Interface
   4  *
   5  * Defines the public contract all DokuWiki plugins will adhere to. The actual code
   6  * to do so is defined in DokuWiki_PluginTrait
   7  *
   8  * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
   9  * @author     Christopher Smith <chris@jalakai.co.uk>
  10  */
  11 interface DokuWiki_PluginInterface {
  12     /**
  13      * General Info
  14      *
  15      * Needs to return a associative array with the following values:
  16      *
  17      * base   - the plugin's base name (eg. the directory it needs to be installed in)
  18      * author - Author of the plugin
  19      * email  - Email address to contact the author
  20      * date   - Last modified date of the plugin in YYYY-MM-DD format
  21      * name   - Name of the plugin
  22      * desc   - Short description of the plugin (Text only)
  23      * url    - Website with more information on the plugin (eg. syntax description)
  24      */
  25     public function getInfo();
  26
  27     /**
  28      * The type of the plugin inferred from the class name
  29      *
  30      * @return string  plugin type
  31      */
  32     public function getPluginType();
  33
  34     /**
  35      * The name of the plugin inferred from the class name
  36      *
  37      * @return string  plugin name
  38      */
  39     public function getPluginName();
  40
  41     /**
  42      * The component part of the plugin inferred from the class name
  43      *
  44      * @return string component name
  45      */
  46     public function getPluginComponent();
  47
  48     /**
  49      * Access plugin language strings
  50      *
  51      * to try to minimise unnecessary loading of the strings when the plugin doesn't require them
  52      * e.g. when info plugin is querying plugins for information about themselves.
  53      *
  54      * @param   string $id id of the string to be retrieved
  55      * @return  string in appropriate language or english if not available
  56      */
  57     public function getLang($id);
  58
  59     /**
  60      * retrieve a language dependent file and pass to xhtml renderer for display
  61      * plugin equivalent of p_locale_xhtml()
  62      *
  63      * @param   string $id id of language dependent wiki page
  64      * @return  string parsed contents of the wiki page in xhtml format
  65      */
  66     public function locale_xhtml($id);
  67
  68     /**
  69      * Prepends appropriate path for a language dependent filename
  70      * plugin equivalent of localFN()
  71      *
  72      * @param string $id id of localization file
  73      * @param  string $ext The file extension (usually txt)
  74      * @return string wiki text
  75      */
  76     public function localFN($id, $ext = 'txt');
  77
  78     /**
  79      * Reads all the plugins language dependent strings into $this->lang
  80      * this function is automatically called by getLang()
  81      *
  82      * @todo this could be made protected and be moved to the trait only
  83      */
  84     public function setupLocale();
  85
  86     /**
  87      * use this function to access plugin configuration variables
  88      *
  89      * @param string $setting the setting to access
  90      * @param mixed $notset what to return if the setting is not available
  91      * @return mixed
  92      */
  93     public function getConf($setting, $notset = false);
  94
  95     /**
  96      * merges the plugin's default settings with any local settings
  97      * this function is automatically called through getConf()
  98      *
  99      * @todo this could be made protected and be moved to the trait only
 100      */
 101     public function loadConfig();
 102
 103     /**
 104      * Loads a given helper plugin (if enabled)
 105      *
 106      * @author  Esther Brunner <wikidesign@gmail.com>
 107      *
 108      * @param   string $name name of plugin to load
 109      * @param   bool $msg if a message should be displayed in case the plugin is not available
 110      * @return  DokuWiki_PluginInterface|null helper plugin object
 111      */
 112     public function loadHelper($name, $msg = true);
 113
 114     /**
 115      * email
 116      * standardised function to generate an email link according to obfuscation settings
 117      *
 118      * @param string $email
 119      * @param string $name
 120      * @param string $class
 121      * @param string $more
 122      * @return string html
 123      */
 124     public function email($email, $name = '', $class = '', $more = '');
 125
 126     /**
 127      * external_link
 128      * standardised function to generate an external link according to conf settings
 129      *
 130      * @param string $link
 131      * @param string $title
 132      * @param string $class
 133      * @param string $target
 134      * @param string $more
 135      * @return string
 136      */
 137     public function external_link($link, $title = '', $class = '', $target = '', $more = '');
 138
 139     /**
 140      * output text string through the parser, allows dokuwiki markup to be used
 141      * very ineffecient for small pieces of data - try not to use
 142      *
 143      * @param string $text wiki markup to parse
 144      * @param string $format output format
 145      * @return null|string
 146      */
 147     public function render_text($text, $format = 'xhtml');
 148
 149     /**
 150      * Allow the plugin to prevent DokuWiki from reusing an instance
 151      *
 152      * @return bool   false if the plugin has to be instantiated
 153      */
 154     public function isSingleton();
 155 }
 156
 157
 158