Updated Mar 30, 2008 by pavolbiely
Labels:	Phase-Implementation

PluginAPI

Interested in creating a new plugin?

Plugin API

Plugins are files or group of files which, after installing, bring new and unseen features to SigmaCMS.

Interface

To create a plugin you have to write a class which implements the PluginAPI interface. This interface contains methods which must be used in every plugin.

Method	Type	Return Type	Description
name()	dynamic	string	Plugin name.
author()	dynamic	string	Author’s name, company, URL etc.
version()	dynamic	string	Version number. We recommend using version numbering in form of major and minor numbers Example: 0.1, 1.5, 2.3…
install()	dynamic	boolean	Returns true if a plugin installs successfully. Otherwise, it returns false.
uninstall()	dynamic	boolean	Returns true if a plugin uninstalls successfully. Otherwise, it returns false.
dependency()	dynamic	array	Plugin may depend on different plugins. This method returns an array containing IDs of the plugins this plugin depends on.

Handling

The maintaining and the co-operation among the plugins is provided via the Plugin class.

Method	Type	Return Type	Description
registerAll()	static	void	Creates instances from all installed and activated plugins.
unregisterAll()	static	void	Destroys all instances of registered plugins.
register(id)	static	void	Registers a plugin. Each plugin is registered only once according to the singleton pattern.
unregister(id)	static	void	Unregisters a plugin.
isRegistered(id)	static	boolean	Returns true if a plugin is registered. Otherwise, it returns false.
isInstalled(id)	static	boolean	Returns true if a plugin is installed. Otherwise, it returns false.
getPlugin(id)	static	mixed	Returns an instance to a plugin.
getPlugins()	static	array	Returns an array with instances of all registered plugins.

The Main Class

By default, all plugins are located in the /plugins directory. Name of each plugin consists of the prefix plugin. and the suffix .php (example: plugin.gzip.php). The string among these two affixes is also considered the plugin ID and saved to the sigma_plugin table in database. It is used for the unique identification. The plugin filename must be lowercase. The Plugin class must implement the PluginAPI interface and its name must begin with the prefix Plugin_ and continue with the lowercase plugin ID string with exception of the first character which is uppercase (example: Plugin_Gzip).

Example

<?php

class Plugin_Gzip implements PluginAPI
{
    public function name()
    {
        return 'Gzip Compression';
    }

    public function author()
    {
        return 'PaBi3';
    }
    
    public function version()
    {
        return '0.1';
    }

    public function install()
    {
        if (!extension_loaded('zlib')) {
            echo "<p>The server does not support zlib extension.</p>\n";
            return false;
        }
        return true;
    }

    public function uninstall()
    {
        return true;
    }

    public function dependency()
    {
        return array();
    }

    public function event_preSkin()
    {
        if (extension_loaded('zlib')) {
            ob_start('ob_gzhandler');
        }
    }
}

Tips & Suggestions

For a better plugin co-operation you should use the Plugin::getPlugin() method which returns an instance to the specified plugin.
Should the dependency() method in the example above not return an empty array, you have to install and activate all the plugins stored in the array.
When the core calls the Plugin::register() method, performing of some actions is ineligible. Therefore, it is not recommended to create your own constructor or destructor unless you really know what you are doing.
If a plugin uses the database we recommend adding a prefix to tables in the following form: plugin_<pluginId>. The rest of the name is up to you.

Administration

In order to create an administration for plugin, you have to write another plugin class with the same name as the plugin has, but extended with the prefix Admin_ (example: Admin_Plugin_Silverlight). The files containing a plugin administration have different locations from the regular plugins. By default, they are located in a directory with following structure: /plugins/plugin.<pluginId>/admin.php. Plugin ID must be lowercase. There are two optional methods below which may be implemented by every plugin:

Method	Type	Return Type	Description
initialize()	dynamic	void	First page the user will open when he clicks the plugin administration link.
menu()	dynamic	void	Menu which normally contains a XHTML unordered list.

The Administration Class

Methods below are useful for each plugin administration class:

Method	Type	Return Type	Description
getAllowedSections()	static	array	Returns an array of sections in administration which are accessible by any member regardless of the access rights.
initialize()	static	void	Initializes the administration. This method is called automatically by the core.
header([, title…])	static	void	Generates a header for XHTML code.
footer()	static	void	Generates a footer for XHTML code.
image(path, desc)	static	string	Prints an image element. The path parameter is an image name without extension. By default images are stored in the /administration/icons directory.
redirect(path)	static	void	Redirects to desired URL. Only a relative path may be passed as the path parameter.
confirm(url, question)	static	void	Shows a confirmation dialog with ‘Yes’ and ‘No’ buttons. The url parameter is the URL to which the user is redirected after he clicks the ‘Yes’ button. The second parameter is a question which is to be answered by clicking the ‘Yes’ or ‘No’ button .
addEvent(name [, param…])	static	void	Adds an event to a specified place. This is very useful when you plan to integrate this plugin with others.
templates()	static	void	Returns a new instance of the `Admin_Templates` class which manages templates.

Example

<?php

class Admin_Plugin_Gzip
{
    public function initialize()
    {
        Admin::header('Gzip Compression');
        echo "Hello World (gzip)!\n";
        Admin::footer();
    }

    public function menu()
    {
        echo "<ul>\n";
        echo "<li><a href='index.php?action=plugin.gzip'>Gzip Compression</a></li>\n";
        echo "</ul>\n";
    }
}

The example above is a simple administration class for the Gzip plugin. You can access the administration section via the following URL: index.php?action=plugin.gzip.

Special Methods of the Plugin Class

Under special methods we understand the so-called actions, events and keywords. Each of them has different kind of use.

Actions

Action is a method the name of which begins with the prefix action_. The rest of the name is up to you. The main reason why you would want to use an action is to execute a code before a skin is generated. Calling an action is very simple: index.php?plugin=eshop&method=addItem. As a result of using such an URL, the action_addItem() method of the Plugin_Eshop class gets called. These methods are commonly ended with the exit() or Main::setSkin() method.

Events

Event is a method the name of which begins with the prefix event_. The rest of the name is up to you. Event is a place in the code where all the methods of the registered plugins with the prefix event_ are called. Events may have an unlimited number of parameters. You can specify your own events or pick up from events below:

Method	Type	Return Type	Description
event_preSkin()	dynamic	void	Event which is called before a skin is generated.
event_posSkin()	dynamic	void	Event which is called after a skin is generated.
event_preAction(action)	dynamic	void	Event which is called before an action gets called.
event_posAction(action)	dynamic	void	Event which is called after an action gets called.
event_preUpload(file, path)	dynamic	void	Event which is called before a file is uploaded. The file parameter is an array which comes from $FILES. The path parameter is the target path to which the file should be uploaded.
event_posUpload(file,path,upload)	dynamic	void	Event which is called after a file is uploaded. Parameters are the same as in the previous method. If upload is true, the file was uploaded successfully.
event_logIn(username)	dynamic	void	Event which is called after a member successfully logs in.
event_logInFailed(username)	dynamic	void	Event which is called after a member fails to log in.

Keywords

Keyword is a method the name of which begins with the prefix parse. The rest of the name is up to you. Keywords are methods which can be called by the user in XHTML (or other) code.

Example: If a developer creates a parse_print(message) method, the administrator can call it using the <%print(Hello World)%> keyword. Keywords may have an unlimited number of parameters.

Special Methods of the Plugin Administration Class

Unlike the normal plugin class, the administration class has only own events and pages. Events in administration are absolutely independent from the normal plugin events. List of predefined events in administration is below (further description is not necessary because the names of events and their parameters correspond to their functionality):

Events

Method	Type	Return
event_preAdminSkin()	dynamic	void
event_posAdminSkin()	dynamic	void
event_adminSkinHeader()	dynamic	void
event_memberAdd(username)	dynamic	void
event_memberEdit(username)	dynamic	void
event_memberDelete(username)	dynamic	void
event_pluginEdit(pluginId)	dynamic	void
event_pluginPriorityUp(pluginId)	dynamic	void
event_pluginPriorityDown(pluginId)	dynamic	void
event_pluginInstall(pluginId)	dynamic	void
event_pluginUninstall(pluginId)	dynamic	void
event_configUpdate()	dynamic	void
event_skinAdd(template,skin)	dynamic	void
event_skinEdit(template,skin)	dynamic	void
event_skinDelete(template,skin)	dynamic	void
event_logOut(username)	dynamic	void
event_languageAdd(id,lang)	dynamic	void
event_languageDelete(id,lang)	dynamic	void
event_preSkinTextarea(id,name,content)	dynamic	void
event_posSkinTextarea(id,name,content)	dynamic	void
event_preTemplateTextarea(id,name,content)	dynamic	void
event_posTemplateTextarea(id,name,content)	dynamic	void

Pages

Page is a method the name of which begins with the prefix page_. The rest of the name is up to you. Pages are just pages in common sense of word.

Example: If a developer creates a page_helloworld( method, in the Gzip plugin, you would call it via the following URL: index.php?action=plugin.gzip&page=hellworld. That is all there is to pages.

Templates

Installation

Installation or uninstallation of templates is processed in the install() or uninstall() method of a plugin class. An instance to the template manager is acquired via the Admin::templates() method. The only two useful methods of this class are described below:

Method	Type	Return Type	Description
insertNewTemplate(templateId, pluginId [, content [, keywords]])	dynamic	void	Creates a new template for specified a plugin. The first two parameters correspond to their names. The content parameter is the default content of a template. It could contain any XHTML (or other) code. The last parameter contains keywords separated by commas which you can use in templates.
deleteOldTemplate(templateId, pluginId)	dynamic	void	Deletes an old template from a specified plugin. If the templateId parameter is (asterisk), all templates will be deleted.

Example

$templates = Admin::templates();
$templates->insertNewTemplat('showItem','articles',NULL,'title,body,content,author,date');
$templates->deleteOldTemplate('*', 'weblog');

Managing

For managing templates you have to create a form for editing them. Methods below will make it easier to create it.

Method	Type	Return Type	Description
addTemplate (templateId, pluginId, description)	dynamic	void	Adds a textarea to the form containing the content of a template specified by the templateId parameter. The description parameter is a brief summary of template’s purpose.
addTitle(title)	dynamic	void	Should your plugin have too many templates, it is better to make the form more understandable by adding a title above the individual groups of the templates.
buildForm(redirectUrl)	dynamic	void	Creates the whole form. The redirectUrl parameter is the target URL to which you are redirected after submitting the form.

Example

$templates = Admin::templates();

$templates->addTitle('List of all News');
$templates->addTemplate('list','news','News it the List');
$templates->addTemplate('listEmpty','news','No news to display.');

$templates->addTitle('Opened News for Reading');
$templates->addTemplate('show','news','News');
$templates->addTemplate('notFound','news','The News were not found.');

$templates->buildForm();

Usage

Usage of templates consists of creating a new instance of the Template class, setting keywords with the setParam() method and analyzing the code with the analyze() method. When creating a template, you must pass two parameters to the constructor. The first one is (almost) always the instance of the plugin you work with. The second parameter templateId refers to the template ID which belongs to the plugin passed as the first parameter.

$template = new Template($this,'item');
$template->setParam('url', 'sigmacms-content-management-system');
$template->setParam('title', 'SigmaCMS – Content Management System');
$template->setParam('content', 'Some content goes here.');
$template->setParam('author', 'John Carrot');
$template->setParam('date', date('Y-m-d H:i'));
$template->analyze();