====== 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:

<code php>
<?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'
);
?>
</code>

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.
</note>

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.

<code php>
<?php

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

?>
</code>

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>

<note>
For more informations about a plugin organization, see [[http://fr.dotclear.org/documentation/2.0/resources/plugins/files|cette page]]
</note>

**_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:

<code php>
<?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;
        }
}
?>
</code>

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 [[http://www.php.net/manual/fr/language.pseudo-types.php#language.types.callback|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.  
</note>

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