Mantis plug-in development is a very simple task. What you need to do is put set of folders and files in place and the Mantis will identify your plug-in. Of course your plug-in must do something useful, its up to you to decide what your plug-in should do. Here I'll look at the basics of Mantis plug-in development.
I learn this when I developed an authentication plug-in for mantis to authenticate users using SimpleSamlPhp. But unfortunately there is no way to develop a authentication plug-in without hacking the code base. There were some discussion about developing authentication plug-in system in Mantis forums and mailing lists. Checkout the forums and mailing lists if you want to develop an authentication plug-in.
OK I'll stop , lets go through the process to get your plug-in up and running.
Create a folder inside the plug-ins directory and give it a name(Test). This is the base name of the plug-in it is used to identify the plug-in.
Create a PHP file inside the directory with the same name as the directory name(Test.php). This file is sufficient enough for mantis to identify your plug-in, all the others are optional.
Create a directory inside your plug-in directory and name it as pages. This will contain the pages for your plug-in. Only files with .php extension should be stored in this directory.
Crete another directory inside your plug-in directory and name it as files. This folder will hold the extra files you need for your plug-in. For example CSS files.
Create a directory named lang inside your plug-in directory. This directory will hold language files which can be used for localization.
Now you have all the folders which are identified by the Mantis as parts of your plugin. So, lets take a look at what goes inside the Test.php file.
All the mantis plugins are created by extending the MantisPlugin class. So, create a class TestPlugin in the Test.php file. Class name is formed by appending “Plugin” to the base name of your plugin.
class TestPlugin extends MantisPlugin{}
next you need to define a funcation named register in your class. This will override the register function in MantisPlugin class.
class TestPlugin extends MantisPlugin{
function register(){
}
}
now lets see what goes inside the register function
function register(){
$this->name='Test';
$this->version='1.0';
$this->require=array('MantisCore'=>'1.2.0');
$this->description='description';
$this->page='default plugin page';
$this->author='author name';
$this->url='support webpage';
$this->contact='author contacts';
}
Name and Version are must. Other details are optional. Now Mantis can identify your plugin and you can install it. Of course this is of no use.
Lets see what are the other functions that can go inside your class.
function events(){
return array();
}
function hooks(){
return array();
}
function config(){
return array();
}
What are all these functions?
function events()
Here you can define the events which are triggered by your plugin. Others can listen to these events and do something useful. You need to put them in an array. Key would by the event name and the value would be the event type. There are five event types defined in Mantis, each of those has their own purpose. Here are the event types.
EVENT_TYPE_EXECUTE
EVENT_TYPE_OUTPUT
EVENT_TYPE_CHAIN
EVENT_TYPE_FIRST
EVENT_TYPE_DEFAULT
see the Mantis documentation for more details on these event types. So lets add couple of events for the plugin.
Function events(){
$test_events=array();
$test_events['EVENT_TEST_FIRST']=EVENT_TYPE_EXECUTE ;
$test_events['EVENT_TEST_SECOND']=EVENT_TYPE_DEFAULT ;
return $test_events;
}
function hooks()
this is the function in which you register your event handlers. This function returns an array containing event name as the key and your event handler as the value. You can listen to your own events or any other events that are triggered by Mantis.
Here i'm going to add an event handler which will handle an event defined by my plugin.
function hooks(){
$handlers=array();
$handlers['EVENT_TEST_FIRST']='first';
}
function first($p_event){
echo 'hello';
}
every events handler receives some value for $p_event. This can be used to identify the event in cases where same function is used to handle many events. There are some other variables that comes as parameters to your function depending on the type of event you are handling.
function config()
this function allows you to define any configuration option for your plugin. They are stored in the array returned by this function. Names of configuration options are given as keys and default values are given as values of the array.
So lets add some configuration options to you plug-in.
function config(){
$my_config=array();
$my_config['test_config']='hello';
}
you can access these configuration options using plugin_config_get($config_name) function and modify those using plugin_config_set function.
now your Test.php file is complete. You can do something more useful in your event handlers and announce others of something important that you've done using events that you've defined.
So lets give it a test. Add a new file named first.php in to you pages directory. We are going to trigger our EVENT_TEST_FIRST event when some one access the page and see our first($p_event) function in action which is registered as an event handler for the triggered event.
Here is the code that goes inside the file.
<?php
echo 'testing events <br/>';
echo 'our event handler should print “hello” in the next ling <br/>';
event_signal();
?>
you can access the page using the url mentioned below, after you have installed the plugin. To install the plugin go to the manage page and then go to the manage plugin page by clicking the links in main page.
mantis/plugin.php?page=Test/first
similarly you can test your configurations using plugin_config_get and plugin_config_set function.
You can add a config.php file to pages directory to allow users to change configurations and you can process and set the values by forwarding submissions to another file in pages directory named config_update.php.
These are just to indicate the standard way of setting your configuration options. You can always do those as you like, but I suppose standard way is better.
