Plugin Resources

Plugins are tools to extend the functionality of RoundCube. They are not part of the application core but can be installed and activated individually.

How to write a plugin

Names, Files and Locations

Each plugin defines a folder in the local plugins directory which by default is [roundcuberoot]/plugins. Make sure you choose a unique, unix-style name for your plugin folder. A plugin can be built with any number of files inside this folder but there needs to be one file named the same as the folder itself (with .php added) which holds the plugin class definition. This class extends the rcube_plugin class and has again the same name as the plugin folder itself.

For example, if your plugin is called Fancy Emoticons the unix-name will probably be fancy_emoticons. This will lead to the following file structure:

plugins/
  fancy_emoticons/
    fancy_emoticons.php
    media/

Inside fancy_emoticons.php you create the plugin class with the name fancy_emoticons which will be explained in the next section.

The Plugin class

RoundCube defines an abstract class named rcube_plugin which provides basic functions and connections to the internal API. Each plugin consists of a class which extends rcube_plugin. The plugin API instantiates a plugin object and then calls the method init() which has to be implemented by the derived plugin class. This startup method is the place where a plugin registers hooks, actions and scripts that will be passed to the client.

To continue our sample plugin Fancy Emoticons, the plugin class could look like this:

/**
 * Fancy Emoticons
 *
 * Sample plugin to replace emoticons in plain text message body with real icons
 *
 * @version 1.0
 * @author Thomas Bruederli
 * @url http://roundcube.net/plugins/fancy_emoticons
 */
class fancy_emoticons extends rcube_plugin
{
  public $task = 'mail';
  private $map;

  function init()
  {
    $this->add_hook('message-body-after', array($this, 'replace'));
  
    $this->map = array(
      ':)'  => html::img(array('src' => $this->urlbase.'media/smiley-smile.gif', 'alt' => ':)')),
      ':-)' => html::img(array('src' => $this->urlbase.'media/smiley-smile.gif', 'alt' => ':-)')),
      ':('  => html::img(array('src' => $this->urlbase.'media/smiley-cry.gif', 'alt' => ':(')),
      ':-(' => html::img(array('src' => $this->urlbase.'media/smiley-cry.gif', 'alt' => ':-(')),
    );
  }

  function replace($args)
  {
    if ($args['type'] == 'plain')
      return array('body' => strtr($args['body'], $this->map));
  
    return null;
  }
}

Let's have a deeper look at the above example:

• The plugin class should be preceded by a commend block that describes the plugin.
• If your plugin is meant to only run in a certain task (e.g. mail,addressbook,settings) you should specify a public property $task. If this property is set the plugin will only be activated within that specific task in order to save memory and performance in all the other tasks.
• The method init() is mandatory and first links the hook message-body-after to the object method replace.
• The callback method replace receives one argument containing context-specific data. In this example we first check if the message type is plain and then the body field is altered and returned. The plugin API will replace the returned fields in it's original context.

Plugin hooks

The way plugin hooks work is that at various times while RoundCube is procesing, it checks to see if any plugins have registered functions to run at that time, and if so, the functions are run (by executing a "hook"). These functions may modify or extend the default behavior of RoundCube.

Registration of hooks is done by calling $this->add_hoook('hook-name', $callback) where the second argument is a ​PHP Callback which can link to a simple function or an object method.

The registered function receives one hash array as argument which contains specific data of the current context depending on the hook. See Plugin_API for a complete description of all hooks and their argument fields. The argument var may be altered by the plugin function and can (partially) be returned to the application at the end of the plugin function.

Custom actions

TBD.

Client scripts and UI elements

TBD.

Installing and activating Plugins

TBD.