From B2evolution

[edit] File layout

A plugin that is named "example" must be put into a file _example.plugin.php and the class defined in that file must be named "example_plugin" and extend the Plugin class.

class example_plugin extends Plugin
{
}

A sample skeleton file gets shipped with b2evolution since version 1.9 in plugins/skeleton.plugin.php (see [1]).

[edit] File location

This file can be put directly into the plugins/ folder, but the preferred method is to use an additional folder (named after the plugin classname).

Any other files a plugin provides, like additional data (fonts, images, stylesheets) or documentation, must be put into a subfolder named after the plugin. In the above case this would be example_plugin/. Therefore it is better to also put the plugin class file there in the first place.

[edit] Filenames and their meaning in the plugin's subfolder

[edit] README.html, README.XX.html

If found, it gets automatically linked as online help and can be used by the plugin to link to from its Settings (see [2]) or if there are special html-IDs in it, these links get created automatically.

First it looks for a localized version in the user's language (e.g. README.de.html for german) and README.html gets used as fallback and should therefore be written in English.

See PluginDocumentation for more details.

[edit] Plugin classname

The plugin classname ("example_plugin" above) should be quite unique, because it's the "key" to the plugin's source: you cannot have different plugins with the same classname installed. So, make sure that it's meaningful and is not likely to conflict with plugins from other authors.

The classname is limited to 40 characters (including the "_plugin" suffix).

[edit] Hooking

A plugin registers callbacks by simply having special methods/functions in its Plugin class (also called hook names). For example, if you want to create a Renderer Plugin, you would add a method (function) called RenderItemAsHtml to your plugin class. Now b2evo knows that you want to hook this event and calls your plugin's method with a set of parameters. Please see PluginHooks for more info.

[edit] Database tables

[edit] Database table names

To keep the database clean/organized, you should use Plugin::get_sql_table(), which returns a canonical prefix (e.g. "evo_plugin_test_7_" for the test_plugin with ID 7).

[edit] Creating database tables

If you want to use database tables in your plugin, you should provide a Plugin::GetDbLayout() method, which defines what tables you want to use.

Then, on installation of the plugin, the admin gets informed that the tables need to be created, which is done after he confirms it.

[edit] Dropping database tables

When a plugin gets uninstalled, all database tables, which are prefixed with what Plugin::get_sql_table() returns, are dropped automatically (after the admin confirms it).

[edit] Backoffice

To implement functionality in the backoffice/admin area, there are several methods.

[edit] Tools tab

To register an entry in the Tools tab, hook the method AdminAfterMenuInit and register your tab:

function AdminAfterMenuInit()
{
  $this->register_menu_entry( 'Title of my tab' );
}

Then, implement the methods AdminTabAction and AdminTabPayload.

[edit] Use prefixes

If your plugin includes an external class (in the same source file as the Plugin's class) or is using global variables or functions (which is a bad idea in general), you should prefix the classname/functions/variables with your plugin's name. E.g., your plugin (example_plugin) uses a class XmlToArray and you include this class' source with your plugin. Then you should name the class example_plugin_XmlToArray.

[edit] Localization

You can make your plugin ready for translation: just use the Plugin::T_() method around your original English strings and follow this guide to generate the necessary files with translated strings.

[edit] Example

See the shipped Test Plugin for more details.

[edit] Appendix

[edit] API documentation

Plugin API documentation can be found at http://doc.b2evolution.net/. For the stable branch (currently 1.9.x) it's at: http://doc.b2evolution.net/stable/plugins/Plugin.html, for the 1.10.x branch: http://doc.b2evolution.net/v-1-10/plugins/Plugin.html and for the HEAD branch (2.0-dev): http://doc.b2evolution.net/HEAD/plugins/Plugin.html

[edit] Changes

• Item content now gets pre-rendered. So, if your renderer plugin generated dynamic content, which is not the same on each request and for each user, you have to use the DisplayItemAsHtml, DisplayItemAsXml and DisplayItemAsText hooks instead.

[edit] Plugins API version

The Plugins API version can be used in the GetDependencies method of your plugin, if you need a specific minimal API version for your plugin.

This is obsolete - please use min_app in GetDependencies instead, which refers to the application/b2evolution version.

Here's the list of API versions and what has changed:

• 1.0: the initial Plugins API, shipped with b2evo 1.8
• 1.1: shipped with b2evo 1.8.1
  • Added Plugin::get_plugin_url() method
  • Added events: AfterUserInsert, AfterUserUpdate, AfterUserDelete
• 1.2: shipped with b2evo 1.9
  • Added events: Logout
  • This list is incomplete: see changelog