inc/plugin.php

   1 <?php
   2 /**
   3  * DokuWiki Plugin base class
   4  *
   5  * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
   6  * @author     Christopher Smith <chris@jalakai.co.uk>
   7  */
   8
   9 /**
  10  * Do not inherit directly from this class, instead inherit from the specialized
  11  * ones in lib/plugin
  12  */
  13 class DokuWiki_Plugin {
  14
  15     var $localised = false;        // set to true by setupLocale() after loading language dependent strings
  16     var $lang = array();           // array to hold language dependent strings, best accessed via ->getLang()
  17     var $configloaded = false;     // set to true by loadConfig() after loading plugin configuration variables
  18     var $conf = array();           // array to hold plugin settings, best accessed via ->getConf()
  19
  20     /**
  21      * General Info
  22      *
  23      * Needs to return a associative array with the following values:
  24      *
  25      * base   - the plugin's base name (eg. the directory it needs to be installed in)
  26      * author - Author of the plugin
  27      * email  - Email address to contact the author
  28      * date   - Last modified date of the plugin in YYYY-MM-DD format
  29      * name   - Name of the plugin
  30      * desc   - Short description of the plugin (Text only)
  31      * url    - Website with more information on the plugin (eg. syntax description)
  32      */
  33     public function getInfo(){
  34         $parts = explode('_', get_class($this));
  35         $info = DOKU_PLUGIN . '/' . $parts[2] . '/plugin.info.txt';
  36         if(file_exists($info)) return confToHash($info);
  37
  38         msg(
  39             'getInfo() not implemented in ' . get_class($this) . ' and ' . $info . ' not found.<br />' .
  40             'Verify you\'re running the latest version of the plugin. If the problem persists, send a ' .
  41             'bug report to the author of the ' . $parts[2] . ' plugin.', -1
  42         );
  43         return array(
  44             'date' => '0000-00-00',
  45             'name' => $parts[2] . ' plugin',
  46         );
  47     }
  48
  49     // plugin introspection methods
  50     // extract from class name, format = <plugin type>_plugin_<name>[_<component name>]
  51     /**
  52      * @return string  plugin type
  53      */
  54     public function getPluginType() {
  55         list($t) = explode('_', get_class($this), 2);
  56         return $t;
  57     }
  58
  59     /**
  60      * @return string  plugin name
  61      */
  62     public function getPluginName() {
  63         list(/* $t */, /* $p */, $n) = explode('_', get_class($this), 4);
  64         return $n;
  65     }
  66
  67     /**
  68      * @return string  component name
  69      */
  70     public function getPluginComponent() {
  71         list(/* $t */, /* $p */, /* $n */, $c) = explode('_', get_class($this), 4);
  72         return (isset($c)?$c:'');
  73     }
  74
  75     // localisation methods
  76     /**
  77      * getLang($id)
  78      * use this function to access plugin language strings
  79      * to try to minimise unnecessary loading of the strings when the plugin doesn't require them
  80      * e.g. when info plugin is querying plugins for information about themselves.
  81      *
  82      * @param   string  $id     id of the string to be retrieved
  83      * @return  string  string in appropriate language or english if not available
  84      */
  85     public function getLang($id) {
  86         if (!$this->localised) $this->setupLocale();
  87
  88         return (isset($this->lang[$id]) ? $this->lang[$id] : '');
  89     }
  90
  91     /**
  92      * locale_xhtml($id)
  93      *
  94      * retrieve a language dependent file and pass to xhtml renderer for display
  95      * plugin equivalent of p_locale_xhtml()
  96      *
  97      * @param   string $id id of language dependent wiki page
  98      * @return  string     parsed contents of the wiki page in xhtml format
  99      */
 100     public function locale_xhtml($id) {
 101         return p_cached_output($this->localFN($id));
 102     }
 103
 104     /**
 105      * Prepends appropriate path for a language dependent filename
 106      * plugin equivalent of localFN()
 107      *
 108      * @param string $id id of localization file
 109      * @return string wiki text
 110      */
 111     public function localFN($id) {
 112         global $conf;
 113         $plugin = $this->getPluginName();
 114         $file = DOKU_CONF.'plugin_lang/'.$plugin.'/'.$conf['lang'].'/'.$id.'.txt';
 115         if (!file_exists($file)){
 116             $file = DOKU_PLUGIN.$plugin.'/lang/'.$conf['lang'].'/'.$id.'.txt';
 117             if(!file_exists($file)){
 118                 //fall back to english
 119                 $file = DOKU_PLUGIN.$plugin.'/lang/en/'.$id.'.txt';
 120             }
 121         }
 122         return $file;
 123     }
 124
 125     /**
 126      * Reads all the plugins language dependent strings into $this->lang
 127      * this function is automatically called by getLang()
 128      */
 129     function setupLocale() {
 130         if($this->localised) return;
 131
 132         global $conf, $config_cascade; // definitely don't invoke "global $lang"
 133         $path = DOKU_PLUGIN . $this->getPluginName() . '/lang/';
 134
 135         $lang = array();
 136
 137         // don't include once, in case several plugin components require the same language file
 138         @include($path . 'en/lang.php');
 139         foreach($config_cascade['lang']['plugin'] as $config_file) {
 140             if(file_exists($config_file . $this->getPluginName() . '/en/lang.php')) {
 141                 include($config_file . $this->getPluginName() . '/en/lang.php');
 142             }
 143         }
 144
 145         if($conf['lang'] != 'en') {
 146             @include($path . $conf['lang'] . '/lang.php');
 147             foreach($config_cascade['lang']['plugin'] as $config_file) {
 148                 if(file_exists($config_file . $this->getPluginName() . '/' . $conf['lang'] . '/lang.php')) {
 149                     include($config_file . $this->getPluginName() . '/' . $conf['lang'] . '/lang.php');
 150                 }
 151             }
 152         }
 153
 154         $this->lang = $lang;
 155         $this->localised = true;
 156     }
 157
 158     // configuration methods
 159     /**
 160      * getConf($setting)
 161      *
 162      * use this function to access plugin configuration variables
 163      *
 164      * @param string $setting the setting to access
 165      * @param mixed  $notset  what to return if the setting is not available
 166      * @return mixed
 167      */
 168     public function getConf($setting, $notset=false){
 169
 170         if (!$this->configloaded){ $this->loadConfig(); }
 171
 172         if(isset($this->conf[$setting])){
 173             return $this->conf[$setting];
 174         }else{
 175             return $notset;
 176         }
 177     }
 178
 179     /**
 180      * loadConfig()
 181      * merges the plugin's default settings with any local settings
 182      * this function is automatically called through getConf()
 183      */
 184     function loadConfig(){
 185         global $conf;
 186
 187         $defaults = $this->readDefaultSettings();
 188         $plugin = $this->getPluginName();
 189
 190         foreach ($defaults as $key => $value) {
 191             if (isset($conf['plugin'][$plugin][$key])) continue;
 192             $conf['plugin'][$plugin][$key] = $value;
 193         }
 194
 195         $this->configloaded = true;
 196         $this->conf =& $conf['plugin'][$plugin];
 197     }
 198
 199     /**
 200      * read the plugin's default configuration settings from conf/default.php
 201      * this function is automatically called through getConf()
 202      *
 203      * @return    array    setting => value
 204      */
 205     protected function readDefaultSettings() {
 206
 207         $path = DOKU_PLUGIN.$this->getPluginName().'/conf/';
 208         $conf = array();
 209
 210         if (file_exists($path.'default.php')) {
 211             include($path.'default.php');
 212         }
 213
 214         return $conf;
 215     }
 216
 217     /**
 218      * Loads a given helper plugin (if enabled)
 219      *
 220      * @author  Esther Brunner <wikidesign@gmail.com>
 221      *
 222      * @param   string $name   name of plugin to load
 223      * @param   bool   $msg    if a message should be displayed in case the plugin is not available
 224      * @return  DokuWiki_Plugin|null helper plugin object
 225      */
 226     public function loadHelper($name, $msg = true){
 227         $obj = plugin_load('helper',$name);
 228         if (is_null($obj) && $msg) msg("Helper plugin $name is not available or invalid.",-1);
 229         return $obj;
 230     }
 231
 232     // standard functions for outputing email addresses and links
 233     // use these to avoid having to duplicate code to produce links in line with the installation configuration
 234
 235     /**
 236      * email
 237      * standardised function to generate an email link according to obfuscation settings
 238      *
 239      * @param string $email
 240      * @param string $name
 241      * @param string $class
 242      * @param string $more
 243      * @return string html
 244      */
 245     public function email($email, $name='', $class='', $more='') {
 246         if (!$email) return $name;
 247         $email = obfuscate($email);
 248         if (!$name) $name = $email;
 249         $class = "class='".($class ? $class : 'mail')."'";
 250         return "<a href='mailto:$email' $class title='$email' $more>$name</a>";
 251     }
 252
 253     /**
 254      * external_link
 255      * standardised function to generate an external link according to conf settings
 256      *
 257      * @param string $link
 258      * @param string $title
 259      * @param string $class
 260      * @param string $target
 261      * @param string $more
 262      * @return string
 263      */
 264     public function external_link($link, $title='', $class='', $target='', $more='') {
 265         global $conf;
 266
 267         $link = htmlentities($link);
 268         if (!$title) $title = $link;
 269         if (!$target) $target = $conf['target']['extern'];
 270         if ($conf['relnofollow']) $more .= ' rel="nofollow"';
 271
 272         if ($class) $class = " class='$class'";
 273         if ($target) $target = " target='$target'";
 274         if ($more) $more = " ".trim($more);
 275
 276         return "<a href='$link'$class$target$more>$title</a>";
 277     }
 278
 279     /**
 280      * A fallback to provide access to the old render() method
 281      *
 282      * Since syntax plugins provide their own render method with a different signature and they now
 283      * inherit from Doku_Plugin we can no longer have a render() method here (Strict Standards Violation).
 284      * Instead use render_text()
 285      *
 286      * @deprecated 2014-01-22
 287      *
 288      * @param string $name
 289      * @param array  $arguments
 290      * @return null|string
 291      */
 292     public function __call($name, $arguments) {
 293         if($name == 'render'){
 294             dbg_deprecated('render_text()');
 295             if(!isset($arguments[1])) $arguments[1] = 'xhtml';
 296             return $this->render_text($arguments[0], $arguments[1]);
 297         }
 298         trigger_error("no such method $name", E_USER_ERROR);
 299         return null;
 300     }
 301
 302     /**
 303      * output text string through the parser, allows dokuwiki markup to be used
 304      * very ineffecient for small pieces of data - try not to use
 305      *
 306      * @param string $text   wiki markup to parse
 307      * @param string $format output format
 308      * @return null|string
 309      */
 310     public function render_text($text, $format='xhtml') {
 311         return p_render($format, p_get_instructions($text),$info);
 312     }
 313
 314     /**
 315      * Allow the plugin to prevent DokuWiki from reusing an instance
 316      *
 317      * @return bool   false if the plugin has to be instantiated
 318      */
 319     public function isSingleton() {
 320         return true;
 321     }
 322 }