Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Clone this wiki locally
Together with the Plugin API Roundcube allows plugins and third party scripts to access the client object and register specific event listeners as well as custom actions and buttons.
Adding event listeners
This is generally done with the following two functions:
rcmail.addEventListener('event', callback); rcmail.removeEventListener('event', callback);
callback function gets the event object as one single argument. This event object usually contains event-specific properties. These are listed as arguments below the according event description.
There are yet a few events that your script can subscribe to listed in Plugin Events.
Custom actions and UI elements
Of course a plugin can add its own buttons somewhere in the document and let them call specific functions directly. Nevertheless we recommend to use the command interface of the RoundCube client. It will automatically handle all UI elements linked with a certain command and allows other plugins to hook into your custom commands.
As you can see in the example, there are a few methods you should know:
This method adds the given DOM node to a specific container of the current page. Containers can be extended with custom buttons and other UI elements. Since each skin can build the HTML page individually it's strongly recommended to use this method rather than appending DOM nodes directly to some contains. Roundcube's default skin defines following containers: 'taskbar', 'toolbar', 'tabs', 'userprefs', 'messagemenu', 'markmenu'.
rcmail.register_button(command, DomId, type, act, sel, over)
Buttons can be linked with the command they're triggering. This is useful if you make use of the
rcmail.enable_command() method to toggle the command status. All linked buttons will automatically be activated/deactivated.
- command: String of the command linked with this button
- DomID: ID of the button node
image|input|linkType of the button
- act: CSS class or image src for active state
- sel: CSS class or image src for selected state
- over: CSS class or image src for mouse overs
rcmail.register_command(command, handler, enable)
Custom commands have to be registered together with the callback function which should be executed if the command is triggered. The third argument activates the command right after registration.
rcmail.enable_command(command[, command, ...], enable)
Finally a plugin can toggle the status of its custom commands using this method. Several commands can be enabled/disabled with one call, the last argument just has to be a boolean value that either enables or disabled all commands in the arguments list.