This section will act as a walkthrough of how to build a plugin, from the bare basics all the way up to advanced topics. A general understanding of the concepts covered in the last section is assumed, as well as knowledge of how the event system works. Later topics in this section will require knowledge of database schemas and how they are used with MantisBT.
This walkthrough will be working towards building a single end result: the "Example" plugin as listed in the next section. You may refer to the final source code along the way, although every part of it will be built up in steps throughout this section.
This section will introduce the general concepts of plugin structure, and how to get a barebones plugin working with MantisBT. Not much will be mentioned yet on the topic of adding functionality to plugins, just how to get the development process rolling.
The backbone of every plugin is what MantisBT calls the "basename", a succinct, and most importantly, unique name that identifies the plugin. It may not contain any spacing or special characters beyond the ASCII upper- and lowercase alphabet, numerals, and underscore. This is used to identify the plugin everywhere except for what the end-user sees. For our "Example" plugin, the basename we will use should be obvious enough: "Example".
Every plugin must be contained in a single directory named to match the plugin's basename, as well as contain at least a single PHP file, also named to match the basename, as such:
Example/ Example.php
This top-level PHP file must then contain a concrete class deriving from
the MantisPlugin class, which must be named in the
form of %Basename%Plugin, which for our purpose
becomes ExamplePlugin.
Because of how MantisPlugin declares the
register()method as
abstract, our plugin must implement that method before PHP will find it semantically valid. This method is meant for one simple purpose, and should never be used for any other task: setting the plugin's information properties, including the plugin's name, description, version, and more.
Once your plugin defines its class, implements the
register()method, and sets at least the name and version properties, it is then considered a "complete" plugin, and can be loaded and installed within MantisBT' plugin manager. At this stage, our Example plugin, with all the possible plugin properties set at registration, looks like this:
Example/Example.php
<?php
class ExamplePlugin extends MantisPlugin {
function register() {
$this->name = 'Example'; # Proper name of plugin
$this->description = ''; # Short description of the plugin
$this->page = ''; # Default plugin page
$this->version = '1.0'; # Plugin version string
$this->requires = array( # Plugin dependencies, array of basename => version pairs
'MantisCore' => '1.2', # Should always depend on an appropriate version of MantisBT
);
$this->author = ''; # Author/team name
$this->contact = ''; # Author/team e-mail address
$this->url = ''; # Support webpage
}
}
This alone will allow the Example plugin to be installed with MantisBT, and is the foundation of any plugin. More of the plugin development process will be continued in the next section.