Forums / Cotonti / Documentation / [Plugins] Plugin development

Category: Plugins
Type: Article, Reference guide
Languages: English

Contents:

1. Default files/folders
2. Using and understanding hooks
3. Using the XTemplate system, defining tags and using rows
4. Setting config values and using them
5. Writing localisations and using $L / {PHP.L}

Added 10 minutes later:

I will do this as soon as I find the time for it.

Added 9 hours later:

Introduction
So you want to write your own plugins? This guide will help you use the Cotonti plugins system. Cotonti (extended) plugins are normal PHP scripts, modified for use with the Cotonti CMS.

Getting started
The first step in the process of developing a plugin is setting up the directory structure and creating some default files. Your plugin directory structure should look like this:



If the plugin you will be writing is not going to use template files and/or language strings, you are free to omit the respective folders.

Your plugin name, when used as a filename or code, should:

• be unique
• be all lowercase
• consist of only letters, numbers and dashes (-)

All files inside your plugin folder (root) have a predefined code structure:

<?PHP

/* ====================
[BEGIN_SED_EXTPLUGIN]
Code=pluginname
Part=main
File=pluginname
Hooks=standalone
Tags=
Order=10
[END_SED_EXTPLUGIN]
==================== */

/**
 * Plugin description
 *
 * @package Plugin name
 * @version 1.0
 * @author You
 * @copyright Your company
 * @license BSD
 */

defined('SED_CODE') or die("Wrong URL.");

// Your plugin code

?>

The first thing you will notice is the presence of some setup values. These values are used by Cotonti to setup and configure your plugin when it is installed through the adminpanel.

Code: the plugin name
Part: the second part of the filename (example: ‘index’ for pluginname.index.php). default: main
File: the filename without extension (example: pluginname.index)
Hooks: Cotonti hook code, or ‘standalone’ for standalone pages
Tags: list of tags using this format: file.tpl:{TAG_ONE},{TAG_TWO}
Order: integer, default 10, order by which plugins are executed by a hook

The following javadoc comment block is optional, but recommended. You are free to modify this to your liking.

Finally, there is one line of code which is required for all your php files, as a security feature. It will prevent your file from being included (and executed) in non-Cotonti php files.

Using and understanding hooks
The Cotonti plugins system is based upon the simple principle of including blocks of code inside the core files. If you look into these core files, which are located in system/core/.../, you will find blocks of code like this:

$extp = sed_getextplugins('index.main');
if (is_array($extp))
	{ foreach($extp as $k => $pl) { include_once($cfg['plugins_dir'].'/'.$pl['pl_code'].'/'.$pl['pl_file'].'.php'); } }

The ‘index.main’ code is the unique hook code. The hook looks up a list of plugins using this hook code, and executes the corresponding plugin files with a simple include_once. Knowing this, you will be able to better understand the way your plugin works and interacts with the Cotonti core. You should treat the plugin code as if it were part of the core code, replacing the hook code. This means that you can use and modify core variables and use global Cotonti functions. This also means you can use the $usr[] variable for accessing data concerning the visitor, which is mostly useful for granting or denying access. The downside is that you need to be aware of naming conflicts. For example, most single character variable names are in use by the Cotonti core. This means it is not safe so use these variable names inside your plugin, because you might overwrite a system variable, introducing new bugs and errors.

The order by which plugin files are included by a hook is defined by the plugin. In most cases it is okay to use the default value (10), but in some special cases you will want to have control over the order by which the plugin code is included. This will allow you to make two plugins successfully work together. The plugin with the lowest value will be included first.[/]