[Summary view] [Print] [Text view]

   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      protected $localised = false;        // set to true by setupLocale() after loading language dependent strings
  16      protected $lang = array();           // array to hold language dependent strings, best accessed via ->getLang()
  17      protected $configloaded = false;     // set to true by loadConfig() after loading plugin configuration variables
  18      protected $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       * @param  string $ext The file extension (usually txt)
 110       * @return string wiki text
 111       */
 112      public function localFN($id,$ext='txt') {
 113          global $conf;
 114          $plugin = $this->getPluginName();
 115          $file = DOKU_CONF.'plugin_lang/'.$plugin.'/'.$conf['lang'].'/'.$id.'.'.$ext;
 116          if (!file_exists($file)){
 117              $file = DOKU_PLUGIN.$plugin.'/lang/'.$conf['lang'].'/'.$id.'.'.$ext;
 118              if(!file_exists($file)){
 119                  //fall back to english
 120                  $file = DOKU_PLUGIN.$plugin.'/lang/en/'.$id.'.'.$ext;
 121              }
 122          }
 123          return $file;
 124      }
 125  
 126      /**
 127       * Reads all the plugins language dependent strings into $this->lang
 128       * this function is automatically called by getLang()
 129       */
 130      function setupLocale() {
 131          if($this->localised) return;
 132  
 133          global $conf, $config_cascade; // definitely don't invoke "global $lang"
 134          $path = DOKU_PLUGIN . $this->getPluginName() . '/lang/';
 135  
 136          $lang = array();
 137  
 138          // don't include once, in case several plugin components require the same language file
 139          @include($path . 'en/lang.php');
 140          foreach($config_cascade['lang']['plugin'] as $config_file) {
 141              if(file_exists($config_file . $this->getPluginName() . '/en/lang.php')) {
 142                  include($config_file . $this->getPluginName() . '/en/lang.php');
 143              }
 144          }
 145  
 146          if($conf['lang'] != 'en') {
 147              @include($path . $conf['lang'] . '/lang.php');
 148              foreach($config_cascade['lang']['plugin'] as $config_file) {
 149                  if(file_exists($config_file . $this->getPluginName() . '/' . $conf['lang'] . '/lang.php')) {
 150                      include($config_file . $this->getPluginName() . '/' . $conf['lang'] . '/lang.php');
 151                  }
 152              }
 153          }
 154  
 155          $this->lang = $lang;
 156          $this->localised = true;
 157      }
 158  
 159      // configuration methods
 160      /**
 161       * getConf($setting)
 162       *
 163       * use this function to access plugin configuration variables
 164       *
 165       * @param string $setting the setting to access
 166       * @param mixed  $notset  what to return if the setting is not available
 167       * @return mixed
 168       */
 169      public function getConf($setting, $notset=false){
 170  
 171          if (!$this->configloaded){ $this->loadConfig(); }
 172  
 173          if(isset($this->conf[$setting])){
 174              return $this->conf[$setting];
 175          }else{
 176              return $notset;
 177          }
 178      }
 179  
 180      /**
 181       * loadConfig()
 182       * merges the plugin's default settings with any local settings
 183       * this function is automatically called through getConf()
 184       */
 185      function loadConfig(){
 186          global $conf;
 187  
 188          $defaults = $this->readDefaultSettings();
 189          $plugin = $this->getPluginName();
 190  
 191          foreach ($defaults as $key => $value) {
 192              if (isset($conf['plugin'][$plugin][$key])) continue;
 193              $conf['plugin'][$plugin][$key] = $value;
 194          }
 195  
 196          $this->configloaded = true;
 197          $this->conf =& $conf['plugin'][$plugin];
 198      }
 199  
 200      /**
 201       * read the plugin's default configuration settings from conf/default.php
 202       * this function is automatically called through getConf()
 203       *
 204       * @return    array    setting => value
 205       */
 206      protected function readDefaultSettings() {
 207  
 208          $path = DOKU_PLUGIN.$this->getPluginName().'/conf/';
 209          $conf = array();
 210  
 211          if (file_exists($path.'default.php')) {
 212              include($path.'default.php');
 213          }
 214  
 215          return $conf;
 216      }
 217  
 218      /**
 219       * Loads a given helper plugin (if enabled)
 220       *
 221       * @author  Esther Brunner <wikidesign@gmail.com>
 222       *
 223       * @param   string $name   name of plugin to load
 224       * @param   bool   $msg    if a message should be displayed in case the plugin is not available
 225       * @return  DokuWiki_Plugin|null helper plugin object
 226       */
 227      public function loadHelper($name, $msg = true){
 228          $obj = plugin_load('helper',$name);
 229          if (is_null($obj) && $msg) msg("Helper plugin $name is not available or invalid.",-1);
 230          return $obj;
 231      }
 232  
 233      // standard functions for outputing email addresses and links
 234      // use these to avoid having to duplicate code to produce links in line with the installation configuration
 235  
 236      /**
 237       * email
 238       * standardised function to generate an email link according to obfuscation settings
 239       *
 240       * @param string $email
 241       * @param string $name
 242       * @param string $class
 243       * @param string $more
 244       * @return string html
 245       */
 246      public function email($email, $name='', $class='', $more='') {
 247          if (!$email) return $name;
 248          $email = obfuscate($email);
 249          if (!$name) $name = $email;
 250          $class = "class='".($class ? $class : 'mail')."'";
 251          return "<a href='mailto:$email' $class title='$email' $more>$name</a>";
 252      }
 253  
 254      /**
 255       * external_link
 256       * standardised function to generate an external link according to conf settings
 257       *
 258       * @param string $link
 259       * @param string $title
 260       * @param string $class
 261       * @param string $target
 262       * @param string $more
 263       * @return string
 264       */
 265      public function external_link($link, $title='', $class='', $target='', $more='') {
 266          global $conf;
 267  
 268          $link = htmlentities($link);
 269          if (!$title) $title = $link;
 270          if (!$target) $target = $conf['target']['extern'];
 271          if ($conf['relnofollow']) $more .= ' rel="nofollow"';
 272  
 273          if ($class) $class = " class='$class'";
 274          if ($target) $target = " target='$target'";
 275          if ($more) $more = " ".trim($more);
 276  
 277          return "<a href='$link'$class$target$more>$title</a>";
 278      }
 279  
 280      /**
 281       * output text string through the parser, allows dokuwiki markup to be used
 282       * very ineffecient for small pieces of data - try not to use
 283       *
 284       * @param string $text   wiki markup to parse
 285       * @param string $format output format
 286       * @return null|string
 287       */
 288      public function render_text($text, $format='xhtml') {
 289          return p_render($format, p_get_instructions($text),$info);
 290      }
 291  
 292      /**
 293       * Allow the plugin to prevent DokuWiki from reusing an instance
 294       *
 295       * @return bool   false if the plugin has to be instantiated
 296       */
 297      public function isSingleton() {
 298          return true;
 299      }
 300  }