The Plugin Interface

and reusable code add-ons

Mara supports a very simple plugin interface, which allows reusable code blocks of either php or javascript to be included into pages.

Installing a Plugin

This is a very straightforward process of expanding the archive (zip, tgz, 7z are permitted formats) into the plugin directory of the site. Since plugins should always be built such that the archive contains a subdirectory whose name matches the plugin, this should result in the files being put into the correct place.

Configuring a plugin

A plugin's own directory may contain a config.php file where customisable settings are stored. For most purposes, adjusting the settings in this should suffice. Other files in the plugin directory may contain replaceable data associated with the plugin's function. Plugins do not normally have browser-based configuration pages, although in some special cases these may exist.

Uninstalling

Plugin removal is a straightforward process of editing any pages which call the plugin to remove such references, and deleting the plugin's own directory. Since Mara plugins do not add code classes to the system or make any other such invasive modifications, removal should leave the system exactly as it was before installation. Calls to nonexistent plugins may result in entries being written to the server's php error log, and if error reporting is set on, screen messages.

Calling a plugin

  For a plugin using html or php:

In the calling page, enter the following at first place the plugin is needed:
<?php include(plugin('pluginname'))?>
 replacing pluginname with the name of the plugin.

  For a plugin containing only javascript:

<?php plugin('pluginname')?>

Depending on the nature of a plugin, the call to it may insert formatted text at the that position in the page, cause code to run at that point, or do nothing until a function within the plugin is called or some trigger condition arises, at some later point in the page. Exactly which depends on its purpose, and for this you should consult the plugin documentation. 

The plugin structure

Naming: Plugin names must be unique. Names are case sensitive, and it is thus advised to stick to lowercase naming.  Names may contain any characters which are legal in both linux and Microsoft Windows filesystems. Spaces are not permitted. 

Content: All plugins shall have a file named plugin.php in the root of the plugin's  directory. Optionally, a plugin.js file may also exist for javascript code. The plugin directory may contain other files as required, and if necessary may contain a subdirectory structure.

Plugins may contain pure HTML, if that is all that is required. If so, there should not be any <html>, <head> or <body> tags, just the formatted text.

In keeping with good programming practices, plugins containing code should expose only a minimum number of global variables. Where global variables are required, these should follow the naming convention pluginname_variablename so as to avoid collisions with other plugins.

Code plugins should preferably expose only those functions to the global namespace which need to be called from the invoking page. Where a plugin exposes multiple functions, their naming should be of the form pluginname_functionname() -for example email_send() -or if using OOP, as $email->send(). This is to reduce the possibility of naming collisions with other plugins.

The only mechanism available in php which provides private functions is OOP, therefore this does suggest the use objects as the best way to code Mara plugins without risk of namespace clashes. However, since OOP is significantly more difficult than conventional coding, we shall not make that an absolute requirement. If you want to code conventionally, just remember to name your functions uniquely and to avoid global variables as far as possible.

Coding Styles: Mara operates under a policy of openness and customisability. In contrast to most other such products, It is expressly intended that plugin code should be modifiable by the end user. For this reason, lucid and uncomplicated writing styles are preferred. It is recognised that object-oriented code may offer several advantages as regards plugins, and that code compression may improve the loading speed of javascript, thus such techniques may be used where appropriate. However, such features should not be employed solely as a means of obfuscating or overcomplicating code with a view to making it indecipherable. Likewise, the use of meaningless variable names ($a=1, $b=2 etc) is to be considered bad practice.  As regards commenting or documentation it is not required that all functions in a plugin be described in detail, but it is preferable if the main ones are.

If using advanced php features, for example anonymous functions, please state clearly the minimum php version required for your plugin.

Licensing: All plugins offered for inclusion into the Mara project must be fully functional, not time limited, and be released under a recognised free software license.   Plugin coders shall retain the rights to their work.