mantisbt:plugins_overview
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
mantisbt:plugins_overview [2007/12/03 10:42] – jreese | mantisbt:plugins_overview [2008/02/15 15:33] – daryn | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Plugin System Overview ====== | ||
- | Author: John Reese | ||
- | |||
- | Status: Work in Progress | ||
- | |||
- | |||
- | ===== Design Overview ===== | ||
- | |||
- | The dynamic plugins system for Mantis is based on a philosophy of simplicity and lightweight design. | ||
- | |||
- | ==== Inversion of Control ==== | ||
- | |||
- | Rather than having each plugin execute and use the plugin API to set things up, the Mantis plugin manager uses the Inversion of Control design theories. | ||
- | |||
- | ===== Event System ==== | ||
- | |||
- | Before going in depth with the inner workings of the plugin system, we will give an overview of the event system, which plays a critical role in giving plugins the flexibility and extensibility that they need. A full reference of the core events can be found in the [[plugins_events|Plugin Event Reference]]. | ||
- | |||
- | ==== Overview ==== | ||
- | |||
- | The Mantis event system requires all events to be ' | ||
- | |||
- | ==== Event Types ==== | ||
- | |||
- | There are multiple event types defined in the core event system. | ||
- | |||
- | === Execute === | ||
- | |||
- | This is the most basic event type in Mantis. | ||
- | |||
- | === Output === | ||
- | |||
- | This type of event is designed specifically for plugins to generate output that will be displayed to the user. The event is passed either a separator string, or an array of prefix, separator, and postfix strings; | ||
- | |||
- | === Chain === | ||
- | |||
- | This event type is designed to allow plugins to process some input data one after the other, which each callback being passed the output from the callback before it. The parameter passed to the event becomes the input data for the first callback to process, and the return value of the last callback is returned to the event originator. | ||
- | |||
- | === Default === | ||
- | |||
- | The default event type is designed to be as flexible and generic as possible. | ||
- | |||
- | |||
- | |||
- | |||
- | ===== Developing Plugins ===== | ||
- | |||
- | This section covers the major topics needed to get started with plugin development. | ||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | |||
- | ==== Registering a Plugin ==== | ||
- | |||
- | The most important step of getting a plugin to actually //work// with Mantis is properly advertising your plugin to the plugin manager, so that it may discover your plugin and allow the administrator to install it. This is done not only by creating the proper directory structure for your plugin, but by creating the right files with the right callback functions. | ||
- | |||
- | An example plugin with just the basic structure and registration can be seen with the [[plugins_sample# | ||
- | |||
- | === Basic Structure === | ||
- | |||
- | In order to have a valid plugin, you must choose a succinct, one-word ' | ||
- | |||
- | A barebones plugin named '' | ||
- | < | ||
- | plugins/ | ||
- | testing/ | ||
- | register.php | ||
- | </ | ||
- | |||
- | |||
- | === register.php === | ||
- | |||
- | This is the single most essential file for a plugin; | ||
- | |||
- | == plugin_callback_< | ||
- | |||
- | This callback must exist for Mantis to recognize your plugin, and it gives your plugin the chance to tell Mantis more about itself, including its name, authors, and dependencies. | ||
- | |||
- | * '' | ||
- | * '' | ||
- | * '' | ||
- | * '' | ||
- | * '' | ||
- | * '' | ||
- | * '' | ||
- | * '' | ||
- | |||
- | == plugin_callback_< | ||
- | |||
- | This callback allows your plugin to set itself up, include any necessary API's, declare or hook events, etc. The only restriction is that anything beyond basic setup should be extracted to a callback hooked to '' | ||
- | |||
- | == plugin_callback_< | ||
- | |||
- | For plugins that need to hook many events at startup, this callback can be created to return an array af event name/ | ||
- | |||
- | ==== Using the Event System ==== | ||
- | |||
- | The event system is what makes Mantis plugins flexible and extensible. | ||
- | |||
- | === Basic Structure === | ||
- | |||
- | To conform to the recommended event usage patterns, there should be a file in in your plugin' | ||
- | |||
- | Building from the example above, your plugin should have the following structure: | ||
- | < | ||
- | plugins/ | ||
- | testing/ | ||
- | events.php | ||
- | register.php | ||
- | </ | ||
- | |||
- | === events.php === | ||
- | |||
- | This file will be included automatically by Mantis at runtime, but only when an event hooked by your plugin has been triggered. | ||
- | |||
- | == plugin_event_< | ||
- | |||
- | This is the generic format for hooked event functions. | ||
- | |||
- | === Hooking Events === | ||
- | |||
- | The simplest way for a plugin to hook a function to an event is by calling **'' | ||
- | |||
- | === Declaring Events === | ||
- | |||
- | Events must be declared before they can be used, with not only the event name, but the event type, which determines how its callback functions will be handled. | ||
- | |||
- | == event_declare( name, type ) == | ||
- | |||
- | This function will declare a single event with a given name and type. The only types currently allowed are: | ||
- | * EVENT_TYPE_EXECUTE | ||
- | * EVENT_TYPE_OUTPUT | ||
- | * EVENT_TYPE_CHAIN | ||
- | * EVENT_TYPE_DEFAULT | ||
- | |||
- | For example: | ||
- | < | ||
- | <?php | ||
- | event_declare( ' | ||
- | </ | ||
- | |||
- | == event_declare_many( events ) == | ||
- | |||
- | This function will declare multiple events at once, taking a key/value array of event name/type pairs. | ||
- | < | ||
- | <?php | ||
- | event_declare_many( array( | ||
- | ' | ||
- | ' | ||
- | ) ); | ||
- | </ | ||
- | |||
- | |||
- | |||
- | |||
- | |||
- | ==== Language Strings ==== | ||
- | |||
- | In order to make plugins more accessible and available to international users, plugins can utilize the benefits of the Mantis language system to consolidate text into separate files for each language, allowing the plugin to be easily translated for different languages. | ||
- | |||
- | === Using Strings === | ||
- | |||
- | Using international language strings in plugins is just as easy as it is in the core Mantis system. | ||
- | |||
- | === Declaring Strings === | ||
- | |||
- | If your plugin needs to use language strings that aren't already declared by the core Mantis system, it is very simple to provide the appropriate language files with your plugin. | ||
- | |||
- | Drawing on the example plugin used above, the structure should follow this pattern: | ||
- | < | ||
- | plugins/ | ||
- | testing/ | ||
- | lang/ | ||
- | strings_english.txt | ||
- | strings_german.txt | ||
- | events.php | ||
- | register.php | ||
- | </ | ||
- | |||
- | The language file itself should follow the same format as standard Mantis language files, a PHP script that declares strings in the following pattern: | ||
- | < | ||
- | <?php | ||
- | $s_plugin_testing_title = " | ||
- | $s_plugin_testing_manage = " | ||
- | </ | ||
- | |||
- | The above string would then be displayed using something like the following code: | ||
- | < | ||
- | <?php | ||
- | echo lang_get( ' | ||
- | </ | ||
- | |||
- | |||
- | |||
- | ==== Configuration ==== | ||
- | |||
- | Many plugins will likely have some elements that can or need to be configurable by the site admin or end-user, such as access thresholds or behavioral preferences. | ||
- | |||
- | === Default Configurations === | ||
- | |||
- | To allow the usage of default configurations for plugins, developers can create a callback method in the plugin' | ||
- | |||
- | === General Usage === | ||
- | |||
- | To retrieve a plugin configuration value, your plugin can call **'' | ||
- | |||
- | ==== Creating Pages ==== | ||
- | |||
- | In order to create entirely new features, plugins must be able to create new pages without needing to worry about all of the Mantis core API. For this reason, the Mantis plugin system includes a very simplified method for structuring and linking to plugin pages. | ||
- | |||
- | === Structure === | ||
- | |||
- | Plugin pages can be named and structured as needed, but they must all be located in the '' | ||
- | |||
- | Using the above example plugin as a basis, new pages can be created in the following pattern: | ||
- | < | ||
- | plugins/ | ||
- | testing/ | ||
- | lang/ | ||
- | strings_english.txt | ||
- | strings_german.txt | ||
- | pages/ | ||
- | about.php | ||
- | manage.php | ||
- | events.php | ||
- | register.php | ||
- | </ | ||
- | |||
- | === Usage === | ||
- | |||
- | Once a page has been created, it can be linked to by using the **'' | ||
- | |||
- | === Example Page === | ||
- | |||
- | == about.php == | ||
- | |||
- | This is an example of a basic display page, which outputs the standard Mantis header and footer, but does nothing else: | ||
- | < | ||
- | <?php | ||
- | html_page_top1( lang_get( ' | ||
- | html_page_top2(); | ||
- | |||
- | # Create a basic href link to the manage.php plugin page | ||
- | echo 'A href="', | ||
- | |||
- | html_page_bottom1( __FILE__ ); | ||
- | </ | ||
- | |||
- | ===== Advanced Plugin Topics ===== | ||
- | |||
- | ==== Schema Management ==== | ||
- | |||
- | |||
- | |||
- | |||
- | ==== Installation / Upgrade / Uninstallation ==== | ||
- | |||
- | In order to allow more advanced plugins the ability to handle the process of installing, upgrading, or uninstalling, | ||
- | |||
- | === plugin_callback_< | ||
- | |||
- | This callback is executed before the normal plugin installation process has started. | ||
- | |||
- | === plugin_callback_< | ||
- | |||
- | This callback is executed after the normal schema upgrade process has executed. | ||
- | |||
- | === plugin_callback_< | ||
- | |||
- | 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.txt · Last modified: 2011/12/30 10:35 by tandler