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
{
    // your code here
}

A sample skeleton file gets shipped with b2evolution since version 1.9 in plugins/skeleton.plugin.php (see http://evocms.cvs.sourceforge.net/evocms/b2evolution/blogs/plugins/skeleton.plugin.php?view=markup).

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.

Filenames and their meaning in the plugin’s subfolder

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 List of Plugin Hooks) 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 Plugin Documentation for more details.

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).

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 Plugins, 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 List of Plugin Hooks for more info.

Database tables

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).

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.

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).

Backoffice

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

Tools tab

To register an entry in the Tools, 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.

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'’.

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.

Example

See the shipped Test Plugin for more details.