User Tools

Site Tools


mantisbt:dynamic_plugin_requirements

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
mantisbt:dynamic_plugin_requirements [2007/10/28 16:39]
vboctor More comments.
mantisbt:dynamic_plugin_requirements [2008/10/29 04:25] (current)
Line 26: Line 26:
  
 There will need to be a simple and unified method for plugins to maintain their database schema, otherwise plugins will get released without proper upgrade paths for users.  The plugin manager should provide an automated schema upgrade mechanism that works the same as the Mantis upgrade mechanism.  For performance reasons, the schema for plugins should only be checked when the plugin management screens are accessed, where it should notify the user of the need to upgrade the schema. There will need to be a simple and unified method for plugins to maintain their database schema, otherwise plugins will get released without proper upgrade paths for users.  The plugin manager should provide an automated schema upgrade mechanism that works the same as the Mantis upgrade mechanism.  For performance reasons, the schema for plugins should only be checked when the plugin management screens are accessed, where it should notify the user of the need to upgrade the schema.
 +
  
 ==== Event Types ====  ==== Event Types ==== 
Line 42: Line 43:
   * No return value   * No return value
   * Includes EVENT_PAGE_TOP and EVENT_PAGE_BOTTOM   * Includes EVENT_PAGE_TOP and EVENT_PAGE_BOTTOM
-** Process event **+** Chain event **
   * Event allowing a plugin to process an input string and return a modified version to the originator.   * Event allowing a plugin to process an input string and return a modified version to the originator.
   * Parameters:   * Parameters:
Line 81: Line 82:
   * Send EVENT_PLUGIN_INIT signal   * Send EVENT_PLUGIN_INIT signal
   * Execute normal page contents with events as necessary   * Execute normal page contents with events as necessary
 +
  
 ==== Event Execution ==== ==== Event Execution ====
Line 89: Line 91:
   * For each registered callback:   * For each registered callback:
     * Include ''plugins/<basename>/events.php''     * Include ''plugins/<basename>/events.php''
-    * Call ''plugin_event_callback_<basename>_<function_name>()''+    * Call ''plugin_event_<basename>_<function_name>()''
     * Alter parameters for next callback if necessary     * Alter parameters for next callback if necessary
   * Output content if necessary   * Output content if necessary
   * Return callback values to event originator if necessary   * Return callback values to event originator if necessary
 +
 +
  
 ===== Plugin Hierarchy ===== ===== Plugin Hierarchy =====
Line 112: Line 116:
   * ''register.php'' is the only file required for a plugin to be valid.  It must contain two callbacks for plugin information and event registrations.  This file should only have the following callbacks, but may include additional functions or callbacks for more complex plugins.     * ''register.php'' is the only file required for a plugin to be valid.  It must contain two callbacks for plugin information and event registrations.  This file should only have the following callbacks, but may include additional functions or callbacks for more complex plugins.  
     * ''plugin_callback_<basename>_info()'' - This function must return an array of plugin information, including name, version, ad dependencies.       * ''plugin_callback_<basename>_info()'' - This function must return an array of plugin information, including name, version, ad dependencies.  
-    * ''plugin_callback_<basename>_register()'' - This function must return an array of event names and corresponding function callbacks.+    * ''plugin_callback_<basename>_init()'' - This function must set up the plugin, and hook any events needed.
     * ''plugin_callback_<basename>_schema()'' - This function is only required if the plugin needs to maintain changes or additions to the Mantis schema.  It must return an array of schema upgrades in the same format as the ''admin/schema.php'' upgrade script.     * ''plugin_callback_<basename>_schema()'' - This function is only required if the plugin needs to maintain changes or additions to the Mantis schema.  It must return an array of schema upgrades in the same format as the ''admin/schema.php'' upgrade script.
   * ''events.php'' is required for using event hooks.  It should contain all the event callback functions, or include additional scripts with the necessary callbacks.  All event callback functions must be named as ''plugin_event_callback_<basename>_<name>()'' This script will only be loaded if the plugin has registered for an event.   * ''events.php'' is required for using event hooks.  It should contain all the event callback functions, or include additional scripts with the necessary callbacks.  All event callback functions must be named as ''plugin_event_callback_<basename>_<name>()'' This script will only be loaded if the plugin has registered for an event.
   * ''lang/'' is only required if the plugin needs to use language strings that don't appear in the standard language files.  These files will only be loaded if the requested strings cannot be found otherwise.   * ''lang/'' is only required if the plugin needs to use language strings that don't appear in the standard language files.  These files will only be loaded if the requested strings cannot be found otherwise.
   * ''pages/'' is only required if a plugin needs to have its own pages.  They can be accessed by linking a url returned by the ''plugin_page()'' function.  These pages need not load the core libraries, as it will already be loaded for them.   * ''pages/'' is only required if a plugin needs to have its own pages.  They can be accessed by linking a url returned by the ''plugin_page()'' function.  These pages need not load the core libraries, as it will already be loaded for them.
 +
 +
 +
  
 ==== Sample Plugin (Super Cow Powers) ==== ==== Sample Plugin (Super Cow Powers) ====
Line 151: Line 158:
  
 /** /**
- Register callback methods for any events necessary.+ Intitialize the plugin.
  */  */
-function plugin_callback_supercow_register() { +function plugin_callback_supercow_init() { 
-  plugin_register( 'EVENT_PLUGIN_INIT', 'header' );+  plugin_event_hook( 'EVENT_PLUGIN_INIT', 'header' );
 } }
 </code> </code>
Line 165: Line 172:
  * Handle the EVENT_PLUGIN_INIT callback.  * Handle the EVENT_PLUGIN_INIT callback.
  */  */
-function plugin_event_callback_supercow_header() {+function plugin_event_supercow_header() {
   header( 'X-Mantis: This Mantis has super cow powers.' );   header( 'X-Mantis: This Mantis has super cow powers.' );
 } }
 </code> </code>
 +
 +
  
 ===== Feedback =====  ===== Feedback ===== 
  
   * (vboctor): EVENT_TEXT_GENERAL - You might need to differentiate where this text is going, e.g. normal text (like string_display()), text within an edit box (like string_attribute()).   * (vboctor): EVENT_TEXT_GENERAL - You might need to differentiate where this text is going, e.g. normal text (like string_display()), text within an edit box (like string_attribute()).
 +    * (jreese) For now, TEXT_GENERAL is for basic string_display(), with a TEXT_LINKS event for string_display_links(), etc.  Once the plugins make it into CVS Head, we should make a full effort to litter events throughout the codebase, and make sure we have full documentation of it all. 
   * (vboctor): EVENT_TEXT_GENERAL - I am assuming that you will be pipelining the results of one plug-in into another, right?   * (vboctor): EVENT_TEXT_GENERAL - I am assuming that you will be pipelining the results of one plug-in into another, right?
 +    * (jreese) That is the defined behavior of a processing type event, which TEXT_GENERAL is.  Other event types have different behaviors.
   * (vboctor): EVENT_TEXT_GENERAL - If you look at the current implementation you will notice that the order of applying the display filters affects the final results.  How are we going to handle such cases?  The order sensitivity is mainly relating to html tags.   * (vboctor): EVENT_TEXT_GENERAL - If you look at the current implementation you will notice that the order of applying the display filters affects the final results.  How are we going to handle such cases?  The order sensitivity is mainly relating to html tags.
 +    * (jreese) Any plugins that have order sensitivity should define a dependency on appropriate plugins. (jreese)
   * (vboctor): Default event - With the default events, how are you going to handle the return values returned by all these plug-ins?  Are you going to run one plugin, then dependent on the return value, decide whether to continue with the chain or not?   * (vboctor): Default event - With the default events, how are you going to handle the return values returned by all these plug-ins?  Are you going to run one plugin, then dependent on the return value, decide whether to continue with the chain or not?
 +    * (jreese) The default event type will have each plugin run independent of each other, all given the same parameters.  The return values of each plugin will be returned as an element of an array, and it will be up to the caller to determine how to handle that.
   * (vboctor): How is the admin going to enable/disable plug-ins after unpacking them in the right place in the directory structure?   * (vboctor): How is the admin going to enable/disable plug-ins after unpacking them in the right place in the directory structure?
 +    * (jreese) The manage plugins interface allows an admin to install/uninstall plugins at will (assuming dependencies are met). 
   * (vboctor): Some plug-ins may like to change the terminology of Mantis, for example, use 'ticket' rather than 'issue' You current approach only allows adding new strings.   * (vboctor): Some plug-ins may like to change the terminology of Mantis, for example, use 'ticket' rather than 'issue' You current approach only allows adding new strings.
 +    * (jreese) In this case, it should be perfectly feasible for a plugin to register a callback for the PLUGIN_INIT event that does nothing but force a lang_load() of the appropriate strings files in the plugin's path, which will then override any already-defined strings.
   * (vboctor): We need to rationalize how custom functions / plug-ins will overlap.  For example, if a developer have overridden a custom function to do some generically useful behavior, then he/she may want to share this in the form of a plug-in.   * (vboctor): We need to rationalize how custom functions / plug-ins will overlap.  For example, if a developer have overridden a custom function to do some generically useful behavior, then he/she may want to share this in the form of a plug-in.
 +    * (jreese) I believe the best way to handle this is to market plugins as ways to **enhance** Mantis, not to change how its core functionality works, which is what custom functions should do (and should still do).
   * (vboctor): I would love to allow the development of Mantis Packs which provide a way to develop a plugin that makes Mantis work better with a certain development process (e.g. scrum) or work better for users migrating their installations from a specific bug tracker (for example, the statuses, reports, custom fields, etc).   * (vboctor): I would love to allow the development of Mantis Packs which provide a way to develop a plugin that makes Mantis work better with a certain development process (e.g. scrum) or work better for users migrating their installations from a specific bug tracker (for example, the statuses, reports, custom fields, etc).
 +    * (jreese) Certainly any plugin could easily do nothing but provide pages that allow for migrating or exporting data.  Integration with other applications would be trickier, but the key way to allow this is by providing a smart and useful array of events for plugins to hook into.
   * (vboctor): We need to support attachment preview plug-ins.   * (vboctor): We need to support attachment preview plug-ins.
 +    * (jreese) I think this would be better added as a core feature.
   * (vboctor): We need to allow plug-ins to add new blocks to pages like issue view, update, etc.   * (vboctor): We need to allow plug-ins to add new blocks to pages like issue view, update, etc.
 +    * (jreese) Easily allowed by placing appropriate output type events in view pages.
   * (vboctor): It should be easy to develop features like Twitter notifications as plug-ins.  Once we do that, then the community can have plugins for all similar services like SMS, Jaiku, Pownce, etc.   * (vboctor): It should be easy to develop features like Twitter notifications as plug-ins.  Once we do that, then the community can have plugins for all similar services like SMS, Jaiku, Pownce, etc.
 +    * (jreese) Once again, this comes down to picking appropriate and useful events.
 +  * (DGtlRift): In the above explanation and examples should ''plugin_callback_<basename>_register()'' be ''plugin_callback_<basename>_init()''?
mantisbt/dynamic_plugin_requirements.1193603996.txt.gz · Last modified: 2008/10/29 04:31 (external edit)