[Sommaire] [Imprimer]

   1  <?php
   2  
   3      /**
   4       * \defgroup Plugin
   5       *
   6       * There is better documentation concerning plugins in the wiki:
   7       *
   8       * http://wiki.plogworld.net/index.php/PLog_1.0/Plugins
   9       *
  10       * The documentation here is only to be used as a reference for the methods
  11       * available in this class.
  12       */
  13  
  14  
  15      /**
  16       * \ingroup Plugin
  17       *
  18       * This is the base class from which every plugin object should inherit.
  19       */
  20      class PluginBase  
  21      {
  22  
  23          /**
  24           * This should be filled by the objects that extend this class to provide
  25           * some help on how to use the plugin.
  26           */
  27          var $desc = "This plugin has no description";
  28  
  29          /**
  30           * This should be filled with the author of the plugin.
  31           */
  32          var $author = "This plugin has no author";
  33  
  34          /**
  35           * This should not be modified as it is set by the plugin manager.
  36           * @private
  37           */
  38          var $id = "";
  39  
  40          /**
  41           * This should be filled with the author of the plugins
  42           */
  43          var $version = "1.0";
  44  
  45          /**
  46           * Set this to the html code that you would like to display when
  47           * configuring this plugin.
  48           */
  49          var $configMessage = "No configuration options available";
  50  
  51          /**
  52           * Error message, if any, that happened when configuring the plugin.
  53           */
  54          var $errorMessage = "No error message";
  55  
  56          /**
  57           * This contains information about the blog that is currently executing or configuring
  58           * this plugin.
  59           * @see BlogInfo
  60           */
  61          var $blogInfo;
  62  
  63          /**
  64           * This one contains the blog specific settings
  65           * @see BlogSettings
  66           */
  67          var $blogSettings;
  68  
  69          /**
  70           * User who is running the plugin.
  71           */
  72           var $userInfo;
  73           
  74         /**
  75          * folder where this plugins is stored. We shouldn't need to mess
  76          * around with this one, as it is automatically filled by the
  77          * plugin manager when the plugin loads
  78          */
  79         var $pluginFolder;
  80      
  81          /**
  82           * This attribute will store the original value of the $source parameter,
  83           * which was passed to the plugin in the constructor. The $source identifies
  84           * the code that initialized the plugin, and it should mainly be used to identify
  85           * whether the plugin is being called from admin.php ("admin") or index.php ("index")
  86           */
  87          var $source;
  88          
  89  
  90          /**
  91           * Constructor. Feel free to do here whatever you need to.
  92           *
  93           * @param source Only defined to be 'index' or 'admin'. This parameter should be used to determine
  94           * whether it is index.php registering this plugin ("index") or admin.php doing it ("admin") so that
  95           * we can perform different things. This means that the plugin can be initialized in two different ways
  96           * depending on whether we're being called via index.php or via admin.php so things like menu entries
  97           * or admin actions do not need to be registered unless it's admin.php calling, and so on.
  98           */
  99      	function PluginBase( $source = "" )
 100          {
 101              $this->source = $source;
 102              if($this->source == "admin")
 103                  lt_include( PLOG_CLASS_PATH."class/template/menu/menu.class.php" );
 104                  
 105          }
 106  
 107          /**
 108           * Returns a string with some information about the plugin.
 109           *
 110           * @return Returns a string describing the plugin.
 111           */
 112          function getDescription()
 113          {
 114              return $this->desc;
 115          }
 116  
 117          /**
 118           * Returns the string describing the author of this plugin.
 119           *
 120           * @return The author of the plugin.
 121           */
 122          function getAuthor()
 123          {
 124              return $this->author;
 125          }
 126  
 127          /**
 128           * Returns the identifier of the plugin, the name which can be used
 129           * in templates.
 130           *
 131           * @return The plugin identifier.
 132           */
 133          function getId()
 134          {
 135              return $this->id;
 136          }
 137  
 138          /**
 139           * This function is called only once when the plugin is registered. Please use this method
 140           * in case your plugin needs to perform some initializations before it is used, specially
 141           * if the initialization process requires access to the plugin/blog settings (because the
 142           * BlogInfo and UserInfo objects are not available in the constructor *yet* so this method
 143           * will be called once they are available)
 144           *
 145           * @return Nothing.
 146           */
 147          function register()
 148          {
 149              return true;
 150          }
 151  
 152          /**
 153           * @private
 154           */
 155          function setBlogInfo( &$blogInfo )
 156          {
 157              $this->blogInfo = $blogInfo;
 158              if( $this->blogInfo != null ) 
 159                  $this->blogSettings = $blogInfo->getSettings();
 160          }
 161  
 162          /**
 163           * @private
 164           */
 165          function setUserInfo( &$userInfo )
 166          {
 167              $this->userInfo = $userInfo;
 168          }
 169  
 170          /**
 171           * Changes the folder where plugins are loaded from
 172           *
 173           * @param folder The folder where plugins are stored
 174           */
 175          function setPluginFolder( $folder ) 
 176          {
 177              $this->pluginFolder = $folder;
 178          }
 179          
 180          /**
 181           * Returns the folder where plugins are located, ./plugins by default
 182           *
 183           * @return A string
 184           */
 185          function getPluginFolder()
 186          {
 187              return $this->pluginFolder;
 188          }
 189          
 190          /**
 191           * registers an admin action
 192           *
 193           * @param key
 194           * @param actionClass
 195           * @return true         
 196           */
 197          function registerAdminAction( $key, $actionClass )
 198          {
 199              lt_include( PLOG_CLASS_PATH."class/controller/admincontroller.class.php" );
 200  
 201              AdminController::registerAction( $key, $actionClass );
 202              
 203              return true;
 204          }
 205          
 206          /**
 207           * register a blog action
 208           *
 209           * @param key
 210           * @param actionClass
 211           * @return true
 212           */
 213          function registerBlogAction( $key, $actionClass )
 214          {
 215              lt_include( PLOG_CLASS_PATH."class/controller/blogcontroller.class.php" );
 216  
 217              BlogController::registerAction( $key, $actionClass );
 218              
 219              return true;
 220          }
 221          
 222          /**
 223           * registers a filter for the pipeline
 224           *
 225           * @param filterName Name of the class that implements the pipeline filter. It must implement the
 226           * PipelineFilter interface.
 227           * @return true
 228           */
 229          function registerFilter( $filterName )
 230          {
 231              lt_include( PLOG_CLASS_PATH."class/security/pipeline.class.php" );
 232  
 233              Pipeline::registerFilter( $filterName );
 234              
 235              return true;
 236          }
 237          
 238          /**
 239           * Adds a new entry to the admin menu, in case the plugin is registering anything there
 240           *
 241           * @param path The XPath to the option
 242           * @param id The identifier of the new option
 243           * @param url The url where this new option is pointing to
 244           * @param localeId
 245           * @param orPerms An array with permissions that will be ORed to determine whether this entry
 246           * can be shown to users or not.
 247           * @param andPerms An array with permission that will be ANDed to determine whether this entry
 248           * can be show to users or not.
 249           * @param siteAdmin Whether this new option can only be used by site admins         
 250           * @see Menu::addEntry
 251           */
 252  		function addMenuEntry( $path, 
 253                                 $id, 
 254                                 $url, 
 255                                 $localeId = null, 
 256                                 $orPerms = Array( "manage_plugins" ), 
 257                                 $andPerms = Array( "manage_plugins" ), 
 258                                 $siteAdmin = false )
 259          {
 260              lt_include( PLOG_CLASS_PATH."class/template/menu/menu.class.php" );
 261      
 262              // for 1.1 compatibility
 263              if( is_bool( $orPerms ) && is_bool( $andPerms )) {
 264                  if( $orPerms == true )
 265                      $orPerms = Array();
 266                  else
 267                      $orPerms = Array( "manage_plugins" );
 268                      
 269                  if( $andPerms == true ) {
 270                      $siteAdmin = true;
 271                      $andPerms = Array();
 272                  }
 273                  else {
 274                      $siteAdmin = false;
 275                      $andPerms = Array( "manage_plugins" );
 276                  }
 277              }
 278              
 279              $orPermsString = implode( ",", $orPerms );
 280              $andPermsString = implode( ",", $andPerms );
 281  
 282              // get hold of the menu structure
 283              $menu =& Menu::getMenu();
 284              // and create a valid menuEntry object
 285              $menuEntry = new MenuEntry( $id,
 286                                          Array( 
 287                                              "url" => $url, 
 288                                              "localeId" => $localeId,
 289                                              "orPerms" => $orPermsString,
 290                                              "andPerms" => $andPermsString,
 291                                              "siteAdmin" => (int)$siteAdmin ));
 292              // add the entry and return the result
 293              return $menu->addEntry( $path, $menuEntry );
 294          }
 295          
 296          /**
 297           * registers an event plugin
 298           *
 299           * @param eventType
 300           * @param eventClass
 301           * @return True if successful or false otherwise
 302           */
 303  		function registerNotification( $eventType )
 304          {
 305              // get a reference to the current plugin manager object
 306              $pm =& PluginManager::getPluginManager();
 307              return $pm->registerNotification( $eventType, $this );
 308          }
 309          
 310          /**
 311           * allows the plugin to throw any event, be it one of the core/standard ones
 312           * or a new custom one
 313           *
 314           * @see PluginManager::notifyEvent
 315           * @param eventType the event code
 316           * @param params an associative array with the even parameters, if any
 317           * @return true
 318           */
 319  		function notifyEvent( $eventType, $params = Array())
 320          {
 321              // get a handle to the plugin manager and throw the event with its parameters
 322              $pm =& PluginManager::getPluginManager();
 323              return( $pm->notifyEvent( $eventType, $params ));
 324          }
 325  
 326          /**
 327           * this method should be implemented by plugins, and will tell the plugin manager 
 328           * which configuration settings are stored in the database by this plugin. This will be
 329           * used later on, in case users want to completely remove any trace of this plugin
 330           * configuration.
 331           *
 332           * It is not mandatory to do so but it would help.
 333           *
 334           * @return An array of strings containing the configuration keys that are saved in the
 335           * database.
 336           */
 337  		function getPluginConfigurationKeys()
 338          {
 339              return Array();
 340          }
 341          
 342          /**
 343           * Returns true if the plugin has any global configuration key or false otherwise
 344           *
 345           * @return true if the plugin has any global configuration key or false otherwise
 346           */
 347  		function hasPluginConfigurationKeys()
 348          {
 349              return( count( $this->getPluginConfigurationKeys()) > 0 );
 350          }
 351          
 352          /**
 353           * Tells the plugin manager which custom tables have been created by this plugin. It will
 354           * help when making a back-up of the database structure, since the back-up feature will be able
 355           * to back-up the plugins' database tables too.
 356           *
 357           * @return An array of string with the name of the database tables used by the plugin.
 358           */
 359  		function getPluginDatabaseTables()
 360          {
 361              return Array();
 362          }
 363          
 364          /**
 365           * returns true whether the plugin has the given locale
 366           *
 367           * @param localeCode the locale that we'd like to check
 368           * @return whether the plugin provides the requested locale
 369           */
 370  		function hasLocale( $localeCode )
 371          {
 372            $path = "plugins/".$this->getId()."/locale/locale_".$localeCode.".php";
 373            
 374            return( File::isReadable( $path ));
 375          }
 376          
 377          /**
 378           * this method must be implemented by plugins that wish to "listen" for events
 379           * It will throw an Exception by default, since it means that the plugin registered for
 380           * an event but no implementation of the process() method is provided
 381           *
 382           * @param eventType The event identifier.
 383           * @param params An array with the parameters thrown by the event. The parameters are 
 384           * dependant on the event.
 385           */
 386          function process( $eventType, $params )
 387          {
 388              lt_include( PLOG_CLASS_PATH."class/object/exception.class.php" );
 389              throw( new Exception( "Plugin ".$this->id." registered for event $eventType but did not provide its own process() method!" ));
 390              die();
 391          }
 392          
 393          /**
 394           * Please use this method to perform any tasks that should be done only once when the plugin is installed
 395           * for the first time such as creation of new database tables, etc. 
 396           * This method will be called every time the "Plugin Centre" page is refreshed, so you should
 397           * not assume that this method will be called only once. 
 398           *
 399           * @return Always true
 400           */
 401          function install()
 402          {
 403               return true;
 404          }
 405          
 406          /**
 407           * returns the plugin version
 408           *
 409           * @return the version of LT for which this plugin was created. This is later on used by the plugin loader
 410           * to determine whether a plugin can be used with a certain version of LT. If 
 411           * PluginBase::version is not defined, this method will return "1.0".
 412           */
 413  		function getVersion()
 414          {
 415              if( $this->version == "" )
 416                  $this->version = "1.0";
 417                  
 418              return( $this->version );
 419          }
 420          
 421          /**
 422           * Returns the value of the source parameter
 423           *
 424           * @param return Source
 425           */
 426  		function getSource()
 427          {
 428              return( $this->source );
 429          }
 430      }
 431  ?>