User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:plugins_overview

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
mantisbt:plugins_overview [2008/02/08 11:11] jreesemantisbt:plugins_overview [2011/12/30 10:35] (current) tandler
Line 41: Line 41:
  
 The default event type is designed to be as flexible and generic as possible.  The parameter to the event is passed directly to each hooked callback, and the return value from the callback is placed in an array with the callback name as the key.  The resulting array is then passed back to the originator.  Any event that doesn't fit one of the other event types can use this type to do anything. The default event type is designed to be as flexible and generic as possible.  The parameter to the event is passed directly to each hooked callback, and the return value from the callback is placed in an array with the callback name as the key.  The resulting array is then passed back to the originator.  Any event that doesn't fit one of the other event types can use this type to do anything.
 +
 +
  
  
Line 46: Line 48:
  
 ===== Developing Plugins ===== ===== Developing Plugins =====
 +
 +The plugin system for Mantis utilizes a class-based hierarchy for plugins, with all plugins deriving from the ''MantisPlugin'' class.  There are a few [[#plugin classes|pre-defined plugin classes]] which make it simpler and easier to develop certain types of plugins, but these classes simply extend ''MantisPlugin'' itself, and add any simplicity on top of that.
  
 This section covers the major topics needed to get started with plugin development.  Anything else will be in the [[plugins_overview#advanced_plugin_topics|Advanced Topics]] section. This section covers the major topics needed to get started with plugin development.  Anything else will be in the [[plugins_overview#advanced_plugin_topics|Advanced Topics]] section.
Line 87: Line 91:
   * ''version'' - Your plugin's version string.  **Required value.**   * ''version'' - Your plugin's version string.  **Required value.**
   * ''requires'' - An array of key/value pairs of basename/version plugin dependencies.  Prefixing a version with '''<''' will allow your plugin to specify a maximum version (non-inclusive) for a dependency.   * ''requires'' - An array of key/value pairs of basename/version plugin dependencies.  Prefixing a version with '''<''' will allow your plugin to specify a maximum version (non-inclusive) for a dependency.
 +  * ''uses'' - Similar to 'requires', but soft dependencies; only fails if the soft dependency is registered, but not yet initialized
   * ''author'' - Your name, or an array of names.   * ''author'' - Your name, or an array of names.
   * ''contact'' - An email address where you can be contacted.   * ''contact'' - An email address where you can be contacted.
Line 94: Line 99:
  
 Overriding this function allows your plugin to set itself up, include any necessary API's, declare or hook events, etc.  Alternatively, your can plugin can hook the ''EVENT_PLUGIN_INIT'' event that will be called after all plugins have be initialized. Overriding this function allows your plugin to set itself up, include any necessary API's, declare or hook events, etc.  Alternatively, your can plugin can hook the ''EVENT_PLUGIN_INIT'' event that will be called after all plugins have be initialized.
 +
  
 ==== Using the Event System ==== ==== Using the Event System ====
Line 99: Line 105:
 The event system is what makes Mantis plugins flexible and extensible.  Events can be utilized in many ways and from many locations, but there is a standard 'acceptable' method suggested for using events within plugins. The event system is what makes Mantis plugins flexible and extensible.  Events can be utilized in many ways and from many locations, but there is a standard 'acceptable' method suggested for using events within plugins.
  
-=== Basic Structure ===+For more detailed information on the event system, see the [[event_system]].
  
-To conform to the recommended event usage patterns, there should be a file in in your plugin's root directory named ''events.php'', which should contain all of the hooked events' callback functions.+=== Hooking Events ===
  
-Building from the example above, your plugin should have the following structure: +There are two ways to hook events in your plugins.  Once you've hooked an event, the appropriate callback function will be called whenever the event is triggered.  
-<code> + 
-plugins/ +== hook() == 
-  testing/ + 
-    events.php +The first way is with 'batch' event hookingwhere all of the events needed by your plugin are hooked automatically during plugin initilization.  This can be achieved by overriding the ''hook()'' function of your plugin class and returning an array of event => callback pairs.  If you need multiple callbacks for a single event, use an array of function names as the value for an event pair. 
-    register.php+ 
 +<code php
 +<?php 
 + 
 +class ... { 
 +  ... 
 + 
 +  function hook() { 
 +    return array( 
 +      // single callback per event 
 +      'EVENT_PLUGIN_INIT' => 'test', 
 + 
 +      // multiple callbacks per event 
 +      'EVENT_PLUGIN_INIT' => array( 'test', 'test' ), 
 +    ); 
 +  } 
 + 
 +  // Callback function 
 +  function test( $p_event, $p_params ) {} 
 +}
 </code> </code>
  
-=== events.php ===+== plugin_event_hook() ==
  
-This file will be included automatically by Mantis at runtimebut only when an event hooked by your plugin has been triggered.  Therefore, you should **not** rely on this file to do anything but declare functions of the following form:+Howeverthe simplest way for a plugin to hook a individual function to an event is by calling **''plugin_event_hook( event, function )''**, passing the full event name and the name of the class's callback function.  An event can be hooked at any time, even after the normal hook initialization.  
  
-== plugin_event_<basename>_<function>( event, params ) ==+<code php> 
 +<?php
  
-This is the generic format for hooked event functions The ''event'' parameter will be passed the entire event name, to differentiate between calls from multiple events ''params'' is an arbitrary value passed by the event originator, and may vary wildly depending upon the event type and the specific event being hooked.  The value this function should return may also vary by event type and the event itself Documentation for core events (and especially that of events from other plugins) should be read carefully to properly receive and return values.+class ... 
 +  ...
  
-=== Hooking Events ===+  function hook() { 
 +    return array( 
 +      'EVENT_PLUGIN_INIT' => 'test', 
 +    ); 
 +  }
  
-The simplest way for a plugin to hook a function to an event is by calling **''plugin_event_hookeventfunction )''**passing the full event name and the ''<function>'' portion of the callback function from the section above.  An event can be hooked at any time, even after the normal hook initialization.  Once you've hooked the event, your function will be called whenever the event is triggered.  For plugins that need hook many events or callbacks at once, there is a convenience function **''plugin_event_hook_manyarray )''** which takes an array of event name keys mapping to callback functions.+  function test$p_event$p_params 
 +    plugin_event_hook( 'EVENT_PAGE_LAYOUT', 'test2); 
 +  
 + 
 +  function test2() {} 
 +
 +</code>
  
 === Declaring Events === === Declaring Events ===
Line 130: Line 167:
  
 This function will declare a single event with a given name and type.  The only types currently allowed are: This function will declare a single event with a given name and type.  The only types currently allowed are:
-  * EVENT_TYPE_EXECUTE +  * ''EVENT_TYPE_EXECUTE'' 
-  * EVENT_TYPE_OUTPUT +  * ''EVENT_TYPE_OUTPUT'' 
-  * EVENT_TYPE_CHAIN +  * ''EVENT_TYPE_CHAIN'' 
-  * EVENT_TYPE_DEFAULT+  * ''EVENT_TYPE_DEFAULT''
  
 For example: For example:
-<code>+<code php>
 <?php <?php
 event_declare( 'EVENT_PLUGIN_TESTING_1', EVENT_TYPE_DEFAULT ); event_declare( 'EVENT_PLUGIN_TESTING_1', EVENT_TYPE_DEFAULT );
Line 143: Line 180:
 == event_declare_many( events ) == == event_declare_many( events ) ==
  
-This function will declare multiple events at once, taking a key/value array of event name/type pairs.  For example: +This function will declare multiple events at once, taking an array of event name => type pairs.  For example: 
-<code>+<code php>
 <?php <?php
 event_declare_many( array( event_declare_many( array(
Line 345: Line 382:
  
 This callback is executed after the normal uninstallation process, and should handle such operations as reverting database schemas, removing unnecessary data, etc.  This callback should be used only if Mantis would break when this plugin is uninstalled without any other actions taken, as users may not want to lose data, or be able to re-install the plugin later. This callback is executed after the normal uninstallation process, and should handle such operations as reverting database schemas, removing unnecessary data, etc.  This callback should be used only if Mantis would break when this plugin is uninstalled without any other actions taken, as users may not want to lose data, or be able to re-install the plugin later.
 +
mantisbt/plugins_overview.1202487105.txt.gz · Last modified: 2008/10/29 04:31 (external edit)

Driven by DokuWiki