Creating Plugins

From Sit
Jump to: navigation, search
Warning.png The information in this article (or section) relates to SiT! v3.69 and earlier. Other versions may behave differently, check the version you are using and the documentation carefully.

Contents

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)

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.60;
$PLUGININFO['myplugin']['sitmaxversion'] = 3.69;

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.

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.

Available Plugin Contexts

Plugin contexts 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.

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)

Extending the SiT! menu

The SiT! menu is constructed using the $hmenu variable in lib/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' => application_url() . "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' => application_url() . "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.

Find out the version of SiT! in use

You can make your plugin compatible with several versions of SiT! even if things in SiT! change by checking the application version number.

e.g.

plugin_register('about', 'myplugin_about');
function myplugin_about()
{
    global $application_version;
    if ($application_version < 3.60)
    {
        // Do this.
    }
    else
    {
        // Do that.
    }
}

The version number is a float, you can also check the variable $application_revision if you wish, this is an additional part of the version number which is a string (e.g. "beta1")

Plugin configuration

Plugin Configuration page

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. Example:

    global $CONFIG;
    if (($CONFIG['myplugin_myconfigoption']) == 'yes')
    {
        echo "Hello World!";
    }

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

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.

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.

See Also

Personal tools
project