Building Aliro Plugins

A plugin is a piece of code that runs in response to the triggering of an event. Any part of the CMS, both the Aliro core and the various add-ons, can trigger an event. The names of events are arbitrary, although they clearly have to be chosen with care to avoid name clashes. Event names should be registered with Aliro to ensure uniqueness. A plugin has a defined interface, and if you are creating a new event, you should publish a definition of the interface. The interface is some set of parameters that anyone triggering the event will pass, together with a definition of the variable that will be returned by the plugin. The Aliro plugin (mambot was another name for plugins, much used in the Mambo world) handler provides a method for triggering an event. It then invokes every plugin that is registered for that event, returning to the caller an array of the return values from the plugins. This mechanism provides loose coupling between various parts of the CMS so that the plugins do not need to know who is triggering them, nor does the triggering code need to know what plugins are present, provide they act in accordance with the defined interface for the event.

With Aliro, a plugin can be built as an independent entity. In this case, it will have its own packaging XML, which will start off something like:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE extinstall SYSTEM "http://www.aliro.org/xml/extinstall.dtd">
<extinstall version="2.0" type="mambot" userclass="botBadBehavior" triggers="onSystemStartUser, requestAdminControlPanelInfo">

The main XML element must specify a userclass attribute, which determines what class will be invoked when the module is needed. The type "mambot" is acceptable as an alternative to "plugin". Optionally, a method can be specified by putting a comma followed by the method name immediately after the class name in the userclass attribute. In any case, Aliro looks first for a method that matches the name of the trigger event. If one is found, then it is invoked, passing the parameters supplied by the triggering code. If there is no matching method name, then Aliro will use the method name given in the userclass attribute (if any) or failing that, the name "perform". If none of these match a method in the class, then the plugin will be ignored.

Note also that the event names that will trigger the plugin are listed in the "triggers" attribute. Specifying them in the XML means that Aliro knows exactly which plugins should be activated for any particular event. Unlike earlier systems, Aliro does not expect the plugins to be placed in groups, nor is there any need to load plugins. The class given in the "userclass" attribute should also be identified in the XML as being a class implemented in one of the files, so that Aliro can find it when needed.

Another way to build a plugin is as part of an application. An application is similar to a component, but can have modules and/or plugins integrated with it. In this case, the plugin details will be specified within the packaging XML for the application. For example, the Aliroboard forum application includes a plugin that provides a page for the user profile manager, showing a form that users can complete to modify their preferences for the forum, and the relevant part of the XML is:

	<plugin userclass="aliroboardProfileHTML,showProfile" triggers="loginProfileDisplayTabs" published="yes">
		<name>AliroBoard Profile Update</name>
		<formalname>bot_aliroboard_profile</formalname>
		<description>Provides a page for the profile update</description>
	</plugin>

In this case, the method is specified as "showProfile" as well as the class being stated to be "aliroboardProfileHTML". Considerable flexibility is available on how to build applications with this ability to specify the class and method that implements a plugin. Remember also that provided the packaging XML correctly identifies them, Aliro manages all the code loading required so that the class will be automatically loaded when needed.

If the plugin method is determined by the "userclass" attribute or the default of "perform", then the method that receives control from Aliro should have a declaration compatible with:

public function perform ($event, $pluginparams, $published, ...) {

although any of the names can be changed. The ... at the end of the parameter list indicates that any number from zero upwards of event specific parameters are coded here. Once again, it is important for the event interface to be defined, as errors will result from a plugin requiring more parameters than are supplied. The logic may fail if the plugin specifies too few or misinterprets the information in any other way. So a clear definition of the plugin interface is essential. The standard parameters are the name of the event that has triggered the plugin (the same method is permitted to handle multiple events), the parameters specific to this plugin and a boolean indicating whether the plugin is published (this could be described as activated). There are some situations where plugins should be called even if they are not active. For example, if they are operating on special codes in text for display to the user, it is desirable for the plugin to remove the special codes if it is not published, even though it does not process them as it would when published.

The "pluginparams" parameter is an object of the class aliroParameters containing the values set by the site administrator for the plugin. The definition of the options for the parameters is given in the packaging XML for the plugin.

When the plugin method is found because it matches the event name, the interface is a bit different. The precise definition is chosen in order to minimise differences from other CMS. This time, the class should be built to extend the "aliroPlugin" class. A simplified version of the start of the class for the Bad Behavior plugin mentioned earlier is:

class botBadBehavior extends aliroPlugin {

	public function onSystemStartUser ($request)

Here the parameter is the sole parameter supplied when the event is triggered. The standard parameters shown above are not provided. Clearly the name of the event is not needed, since it is the same as the name of the method. Because the class inherits from aliroPlugin, and because of the way it is invoked by the Aliro plugin handler, the method will already have available the object properties "published" and "params" which are the boolean and the aliroParameters object described above. Note that the class aliroPlugin has a constructor, and so if the plugin class being developed needs a constructor, it must receive parameters and call the parent constructor, something like this:

	public function __construct ($handler=null, $config=array()) {
		parent::__construct($handler, $config);
		// Do our own stuff...
	}

Building plugins using methods that correspond to event names is now the preferred approach.

Aliro Documentation : BuildingAddOnPlugins

Building Aliro Plugins