Creating Plugins
From Sit
 |
SiT! Manual | Developers Guide → Creating Plugins | Chapter 6 |
Contents |
[edit] Creating Plugins
Your plugin is a regular PHP script, place your plugin in the plugins directory giving it a .php extension as normal.
Set the config variable $CONFIG['plugins'] array to include your plugin name (minus the .php extension)
[edit] Hooks
SiT provides a set of 'Plugin Contexts', which are points during SiT's normal execution where your plugin code can be executed. Your plugin should be developed to have a function for each Plugin Context where you would like additional code to execute. You need to register a hook for each of your plugin functions so that your function can be executed at a particular plugin context.
In your plugin call the function plugin_register() to set up your hook.
e.g.
plugin_register('a_context', 'my_function');
the function my_function() will then be called whenever the context 'a_context' is reached. We suggest you name your functions with a unique prefix to avoid clashes with existing functions or other plugins
Set the following variables in your plugin, where 'myplugin' is the name of your plugin (minus the .php extension)
$PLUGININFO['myplugin']['version'] = 0.01;
$PLUGININFO['myplugin']['description'] = '';
$PLUGININFO['myplugin']['author'] = '';
$PLUGININFO['myplugin']['legal'] = '';
$PLUGININFO['myplugin']['sitminversion'] = 3.45;
$PLUGININFO['myplugin']['sitmaxversion'] = 3.50;
sitminversion and sitmaxversion should be FLOATs that define the minimum version of SiT required for your plugin to run, and the maximum version your plugin is likely to support. Since the plugin infrastructure is likely to change quite often until at least v4.00 we recommend you set the sitmaxversion as the next major version, that is 3.50, 3.55, 3.60, 3.65 etc.
[edit] Function and Variable Names
We strongly recommend that you prefix all your function, class and variables names with a unique string, such as your plugin name to avoid clashes with SiT functions and other plugins.
[edit] Available Plugin Contexts
- about - Add to the about page
- ajaxdata_add_action - Add custom ajax data request actions (Added in 3.60)
- automata - Perform an action each time auto.php is run
- add_user_form - Add to the add user form
- billing_approve_form - Add to the billing approve form
- config_form - Add to the configuration form (Added in 3.60)
- config_save - Perform an action when the configuration is saved (Added in 3.60)
- contact_details - Add to the contact details table
- cp_menu - Add to the control panel menu page
- define_menu - Modify existing menu entries
- edit_contact_form - Add to the edit contact form
- edit_incident_form - Add to the edit incident form
- edit_profile_form - Add to the edit profile form
- edit_site_form - Add to the edit site form
- edit_site_save - Perform an action after a site is saved
- emailtemplate_list - Add to the email template list
- email_arrived - Perform an action after an inbound email arrives but before attachments are processed (Added in v3.50)
- feedback_reports_menu - Add to the feedback reports menu
- feedback_browse - Add to the bottom of the browse feedback page (Added in v3.60)
- feedback_browse_viewresponse - Add to the bottom of the browse feedback response page (Added in v3.60)
- holdingqueue_rowshade - Takes a parameter ($update) which passes the updateid, returns a css class to colour a row in the holding queue
- holiday_ack - Perform an action after holiday has been approved/disapproved
- holiday_cancelled - Perform an action after holiday is cancelled (each day). (Added in v3.45)
- holiday_chart_cal - Add to the top of the holiday chart page
- incident_closed - Perform an action after an incident is closed
- incident_closing - Perform an action before the 'close incident' window is closed (Added in v3.45)
- incident_closing_form1 - Add to the form that is displayed when closing an incident (To be added in v3.50p1)
- incident_created - Perform an action after an incident is created
- incident_created_contract - Perform an action after an incident is created and logged against a contract
- incident_created_site - Perform an action after an incident is created and logged against a site
- incident_details - Add to the incident details page
- incident_details_phone - Add after the phone number of the customer on the incident details page
- incident_details_mobile - Add after the mobile number of the customer on the incident details page
- incident_edited - Perform an action after an incident is updated
- incident_email_form1 - Add to the form that is displayed before sending an email from an incident (Added in v3.50)
- incident_email_form2- Add to the form that is displayed while sending an email from an incident (Added in v3.50)
- incident_email_tofield_autocomplete- Add to the form that is displayed while sending an email from an incident, directly below the 'cc' field, for adding autocomplete (Added in v3.60)
- incident_email_ccfield_autocomplete - Add to the form that is displayed while sending an email from an incident, directly below the 'to' field, for adding autocomplete (Added in v3.60)
- portal_header_menu - Add to the portal header menu
- pre_incident_closed - Perform an action before the incident is closed
- new_incident_form - Add to the new incident form
- noticetemplate_list - Add to the list of notice templates table
- save_contact_form - Perform an action when the edit contact form is saved
- save_profile_form - Perform an action when the edit profile form is saved
- search_contacts - Search through contacts
- search_incidents - Search through incidents
- search_kb - Search through the knowledgebase
- search_sites - Search through sites
- search_user_results - Search through user results
- site_created - Perform an action after a site is created
- site_details - Add to the site details page
- statistics_table_overview - Add to the statistics table
- trigger_actions - Add a trigger action
- trigger_types - Extend the list of available triggers
- trigger_variables - Extend the list of available trigger variables
- user_created - Perform an action after a user has been created
- cfgvar - Add a plugin config variable (Added in v3.60)
- triggername - Any trigger name can be used as a plugin context (see Triggers for more information)
[edit] Additional Pages
If your plugin needs to use additional pages, put those pages in a subdirectory (named for your plugin) inside plugins/ (e.g. plugins/myplugin/mypage.php)
[edit] Extending the SiT! menu
The SiT! menu is constructed using the $hmenu variable in strings.inc.php if you write a plugin you can extend these menus by adding additional elements to the array.
e.g. to add to the end of the support menu (key:30) you should do
$hmenu[30][XX] = array ('perm' => 'YY', 'name' => 'my entry', 'url' => "{$CONFIG['application_webpath']}plugins/myaddon/file.php");
ksort($hmenu[30], SORT_NUMERIC);
Where XX is a value for they key (should be larger than 40) and YY is the permission number required to access the menu entry.
To create a sub menu you would do
$hmenu[30][XX] = array ('perm' => 'YY', 'name' => 'my entry', 'url' => "{$CONFIG['application_webpath']}plugins/myaddon/file.php", 'submenu' => "Y")
Then add
$hmenu[Y] = array(...)
To modify an existing menu entry add a hook to the define_menu plugin context (v3.50+) and manipulate $hmenu as a global variable.
To remove an existing menu entry add a hook to the define_menu plugin context (v3.50+) and unset the array element holding the menu entry. e.g.
global $hmenu;
unset($hmenu[30][50]); // Remove the holding queue menu entry
For more examples of $hmenu menu definitions see strings.inc.php in /lib.
[edit] Plugin configuration
From SiT! v3.60 onwards you can use the 'cfgvar' hook to add your own configuration variables to SiT!'s configuration page.
plugin_register('cfgvar', 'myplugin_cfgvar');
function myplugin_cfgvar()
{
global $CFGTAB, $CFGCAT, $CFGVAR;
$CFGTAB['plugins'] = array_merge((array)$CFGTAB['plugins'], array('myplugin'));
$CFGCAT['myplugin'] = array('myplugin_myconfigoption');
$CFGVAR['myplugin_myconfigoption']['title'] = 'MyPlugin Setting';
$CFGVAR['myplugin_myconfigoption']['help'] = 'Set this to customise MyPlugin';
}
To add some intro text, add the following example. Don't forget to add $CATINTRO to global as well.
$CATINTRO['myplugin'] = 'This text will appear at the top somewhere';
If you want to add a selection box, you can add the following example
$CFGVAR['myplugin_myconfigoption']['options'] = 'yes|no|maybe';
$CFGVAR['myplugin_myconfigoption']['type'] = 'select';
For a checkbox use:
$CFGVAR['myplugin_myconfigoption']['type'] = 'checkbox';
The checkbox value will be stored as TRUE (for checked) or FALSE (for unchecked)
Other config variable types are percent, interfacestyleselect, languageselect, languagemultiselect, slaselect, userselect, siteselect, userstatusselect, roleselect, number, 1darray, 2darray, password and text (The default).
To use the value set by the user in your code use $CONFIG['myplugin_myconfigoption'], remember that you may need to make this Global if your code is inside a function.
[edit] Using additional tables
Should your plugin require additional tables then the name should be prepended with $CONFIG['db_tableprefix'] i.e. jobs becomes $CONFIG['db_tableprefix']jobs this allows the table prefixing to work. Ideally the name should contain a project specific abbreviation e.g. pp to ensure uniqueness e.g. $CONFIG['db_tableprefix']pp_jobs
[edit] Plugin Internationalisation
From v3.50 plugins can have their own i18n files, for example:
plugins/myplugin/i18n/en-GB.inc.php plugins/myplugin/i18n/fr-FR.inc.php
Where myplugin is the name of your plugin. The format of each of your i18n files is similar to the SiT i18n files, except your language keys should contain your plugin name to avoid clashes with other plugins or SiT itself.
<?php
$strMypluginPanda = '大熊猫';
?>
SiT will load your i18n files when it loads your plugin and it will load the default language first, followed by the language in use by the current user. This way if any strings aren't defined for the language in use the default language strings will be used.
To use a string in your plugin just reference the variable as you would any other, remembering to use it's global form if you use it inside a function.
Tip: you can even replace existing SiT strings with your own wording using this method, simply redefine the SiT i18n key within your plugin i18n file.
[edit] Creating more plugin contexts
As we're still developing the plugin interface there is currently (June 2010) only a limited selection of contexts available, this means that if you'd like your plugin to extend part of SiT! where there is no context, you have a problem.
To work-around this you can alter the SiT! source code and add your own context, it's fairly easy to do, although it may require some knowledge of the SiT! source code for you to understand exactly where to place it.
Find the place in the SiT! code where the plugin context should go, and insert the command:
plugin_do('mycontext');
Where mycontext is a unique context name that follows the naming conventions of the contexts in the list above.
If you do add your own context, please submit a patch so that it can be incorporated into a future release - saving you the trouble of re-adding the context code next time you upgrade.
