Writing a plugin for Dotclear 2

Introduction

Plugins are pieces of code that add features to Dotclear, as for example a blogroll, a tool allowing import from another blogging software or a new syntax for writing posts.

Writing a plugin requires solid PHP knowledge, in particular object-oriented programming. Whenever its needed, direct links to the PHP documentation will be included in this tutorial.

First plugin

We are going to write a plugin that will display a text on the blog front-end.

Definition of plugin

A plugin is a directory located in the plugins directory (defined by DC_PLUGIN_ROOT). We are going to create an HelloWorld directory. In this directory, for the plugin to exists, we have to add a _define.php file containing the following code:

<?php
if (!defined('DC_RC_PATH')) { return; }
 
$this->registerModule(
        /* Name */                      "Hello World",
        /* Description*/                "Simple Hello World plugin",
        /* Author */                    "Olivier Meunier",
        /* Version */                   '1',
        /* Permissions */               'usage,contentadmin'
);
?>

All those fields are pretty simple to understand. Permissions takes a list of permissions and is used only to control the plugin activation. If the user doesn't have the rights, the plugin won't be load in the back-end.

We decided here that the plugin will be loaded for any user that can log in the back-end, which corresponds to the usage,contentadmin rights. For an administrator's only usage, we would have chosen the admin right.

Note:

Note that defined rights only works for the current blog. If the plugin had the admin permission and a user was administrator on blog A, but only a redactor on blog B, the plugin would be only active on blog A.

Finally, if you want to allow the plugin only to super-administrators, permission should be null (without quotes).

Organization of a plugin

Our plugin does, for now, nothing. We need to write other files for it to do something.

A plugin contains 3 other files (not always required):

_admin.php : defines the plugin's behaviour in the administration panel.
_public.php : defines the plugin's behaviour on the front-end.
_prepend.php : defines files that have to be loaded.

We will study the _admin.php file later. For now, let's learn about the _public.php and _prepend.php files.

_prepend.php allows us to load files needed by the plugin.

<?php
 
$__autoload['phpClassName'] = dirname(__FILE__).'/inc/class.name.of.the.class.php';
 
?>

This file is also used for calling behaviors.

Note:

A file can contain more than one class. In this case, you only need to include once the file, and use as a key for the $__autoload array the first class in the file. Other classes will be automatically loaded.

Note:

For more informations about a plugin organization, see cette page

_public.php allows us to display a text on the front-end. We are going to write a _public.php file with the following code:

<?php
if (!defined('DC_RC_PATH')) { return; }
 
$core->url->register('HelloWorld','HelloWorld','^HelloWorld$',array('HelloURL','HelloWorld'));
 
class HelloURL extends dcUrlHandlers
{
        public static function HelloWorld($args)
        {
                header('Content-Type: text/plain');
                echo 'Hello World';
                exit;
        }
}
?>

Let's explain this code. We just added an URL to our blog : /HelloWorld (just like /post/…).

The register function of the $core→url object takes 4 parameters :

A type, unique id for the url.
The URL base that can be obtain with $core→url→getBase(<url>).
A regular expression that indicated the front-end when to react.
The function to call when the URL is detected. This argument can be anything as long as it's a valid callback declaration.

In our case, Dotclear will call the static method HelloWorld contained in the HelloURL class when the URL /HelloWord is visited on the blog. This url has the HelloWorld? type and can be obtained with $core→url→getType('HelloWorld').

The HelloWorld method of the HelloUrl class takes only one argument : $args. It potentially contains the match of the regular expression defined before. Where, we didn't use one so we won't use this argument.

The method is quite simple : it creates a text/plain pages containing the words Hello World.

Note:

The HelloURL class inherits from dcUrlHandlers. In our case, it wasn't necessary, but could be if you wanted to return an 404 error page for example. You would then only have to call self::p404() to immediately get a 404 error page with HTTP headers and template corresponding.

Your plugin works ? Congratulation ! We will now improve it a little bit. Writing an administration page for a plugin