This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision Last revision Both sides next revision | ||
plugins:roundcubeplugins [2014/02/18 15:01] mrpink [Installation] |
plugins:roundcubeplugins [2017/10/29 01:36] nuxwin |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ======RoundcubePlugins Plugin Documentation====== | + | <WRAP center round important 60%> |
+ | **Bear in mind that this documentation is for the last released version. If you use an older version, you must refer to the README.md file inside the plugin archive.** | ||
+ | </WRAP> | ||
+ | <markdown> | ||
+ | # i-MSCP RoundcubePlugins plugin | ||
- | Plugin allows to use Roundcube Plugins with i-MSCP. | + | Provides plugins for the Roundcube Webmail Suite. |
- | ===== Included Roundcube Plugins ===== | + | ## Requirements |
- | ==== additional_message_headers ==== | + | - i-MSCP 1.5.x Serie (version >= 1.5.2) |
+ | - Roundcube >= 1.3.x | ||
- | Adds a header identifying the originating ip for the mails sent via webmail. | + | ## Installation |
- | ==== archive ==== | + | 1. Be sure that all requirements are met |
+ | 2. Upload the plugin through the plugin management interface | ||
+ | 3. Activate the plugin through the plugin management interface | ||
- | Archive plugin adds a new button to the Roundcube toolbar to move messages to an (user selectable) archive folder. The button will only appear after the user configured the Archive folder. | + | ## Update |
- | + | ||
- | Roundcube user config: Settings -> Preferences -> Special Folders -> Archive | + | |
- | ==== calendar ==== | + | 1. Be sure that all requirements are met |
+ | 2. Backup your plugin configuration file if needed | ||
+ | 3. Upload the plugin through the plugin management interface | ||
+ | 4. Restore your plugin configuration file if needed | ||
+ | 5. Update the plugin list through the plugin management interface | ||
- | Calendar plugin is a full calendar for Roundcube. | + | ## Configuration |
- | + | ||
- | Roundcube user config: Settings -> Preferences -> Calendar | + | |
- | + | ||
- | ==== contextmenu ==== | + | |
- | Adds context menus to the message list, folder list and address book. | + | See the [configuration](https://github.com/i-MSCP/plugins/blob/master/incubator/RoundcubePlugins/config.php) file for a fast overview. |
- | Possibility to mark mails as read/unread, delete, reply and forward mails. | + | |
- | ==== dkimstatus ==== | + | When changing a configuration parameter in the plugin configuration file, you |
+ | must not forget to trigger a plugin list update through the plugin management | ||
+ | interface, else your changes won't be taken into account. | ||
- | Displays the DKIM Signature status of each mail in Roundcube. | + | ### Roundcube plugin definitions |
- | ==== emoticons ==== | + | This plugin make it possible to install any Roundcube plugin by adding plugin |
+ | definitions in the plugin [configuration file](https://github.com/i-MSCP/plugins/blob/master/incubator/RoundcubePlugins/config.php). | ||
- | Emoticons inserts nice smileys and other emoticons when the appropriate text representations e.g. :-) are discovered in the mail text. | + | #### Basic Roundcube plugin definition |
- | ==== logon_page ==== | + | A basic Roundcube plugin definition looks as follows: |
- | Allows to display additional information (HTML code block) at logon page. | + | ```php |
- | Configuration: Put your content into the file config-templates/logon_page/logon_page.html. It will be parsed by Roundcube templates engine, so you can use all template features (tags). | + | 'name' => [ |
- | + | 'enabled' => true | |
- | ==== managesieve ==== | + | ] |
+ | ``` | ||
- | Uses the managesieve protocol and allows the user to manage his sieve mail rules. A default Spam sieve rule will be created after the user opened the Filters configuration in Roundcube. For this plugin you need Dovecot 2 on your system (please check INSTALLATION section). | + | Here we provide a definition for the `name` plugin and we tell that it must be |
- | + | enabled. | |
- | Roundcube user config: Settings -> Filters | + | |
- | ==== newmail_notifier ==== | + | #### Installing a Roundcube plugin through the PHP dependency manager (Composer) |
- | Can notify on new mails by focusing browser window and changing favicon, playing a sound and displaying desktop notification (using webkitNotifications feature). | + | Most of time, you will have to go one step further by telling how to get and |
- | + | install the plugin. This can be done by adding a `composer` section as follows: | |
- | Roundcube user config: Settings -> Preferences -> Mailbox View | + | |
- | + | ||
- | ==== pdfviewer ==== | + | |
- | + | ||
- | Roundcube inline pdf viewer. | + | |
- | + | ||
- | ==== pop3fetcher ==== | + | |
- | Plugin pop3fetcher allows to add pop3 accounts and automatically fetch emails from them. | + | ```php |
- | + | 'name' => [ | |
- | Roundcube user config: Settings -> Preferences -> Other Accounts | + | ... |
+ | 'composer' => [ | ||
+ | 'require' => [ | ||
+ | 'vendor/name' => '^1.0' | ||
+ | ] | ||
+ | ] | ||
+ | ] | ||
+ | ``` | ||
- | ==== tasklist ==== | + | Basically, a `composer` section is what you would put in a |
+ | [composer.json](https://getcomposer.org/doc/04-schema.md) file to make the PHP | ||
+ | dependency manager (Composer) able to download and install a PHP dependency, | ||
+ | here, a Roundcube plugin. | ||
- | Task management plugin for Roundcube. | + | In the example above, we require the `vendor/name` composer package. |
- | + | ||
- | ==== zipdownload ==== | + | |
- | Adds an option to download all attachments of a message in one zip file. | + | You can learn further about composer by looking at the official |
+ | [documentation](https://getcomposer.org/doc/). | ||
- | + | #### Roundcube plugins not available through plugins.roundcube.net nor through packagist.org | |
- | ===== Requirements ===== | + | |
- | * i-MSCP versions >= 1.1.0 | + | Sometime, a plugin is not available through official |
- | * Plugin compatible with Roundcube 0.9.x | + | [Roundcube plugin](https://plugins.roundcube.net/) repository, nor through |
- | * Dovecot version 2.x is required if you want to use the Roundcube plugin managesieve. | + | [packagist.org](https://packagist.org) repository. In such a case and |
- | + | if the plugin provides a `composer.json` file, you can define your own | |
- | ===== Installation ===== | + | repository as follows: |
- | **1. Install needed Debian/Ubuntu packages** | + | ```php |
+ | 'name' => [ | ||
+ | ... | ||
+ | 'composer' => [ | ||
+ | 'repositories' => [ | ||
+ | 'type' => 'path', | ||
+ | 'url' => PERSISTENT_PATH . '/plugins/RoundcubePlugins/name', | ||
+ | ], | ||
+ | ... | ||
+ | ] | ||
+ | ] | ||
+ | ``` | ||
- | **Debian Wheezy** | + | In the above example, we define a `path` repository in which composer will look |
+ | for the `name` plugin. We assume here that the Roundcube plugin has been | ||
+ | downloaded manually under the `<PERSISTENT_PATH>/plugins/RoundcubePlugins/name` | ||
+ | directory. | ||
- | Only necessary if you want to use the Roundcube Plugin managesieve. | + | #### Getting a Roundcube plugin from a Git repository |
- | + | ||
- | # aptitude update | + | |
- | # aptitude install dovecot-sieve dovecot-managesieved | + | |
- | + | ||
- | **2. Get the plugin from Plugin Store** | + | |
- | http://i-mscp.net/filebase/index.php/Filebase/ | + | It is possible to grab a plugin from a Git repository automatically by adding a |
+ | `git` section as follows: | ||
- | **3. Plugin upload and installation** | + | ```php |
+ | 'name' => [ | ||
+ | ... | ||
+ | 'git' => [ | ||
+ | 'repository' => 'https://domain.tld/vendor/name.git' | ||
+ | ], | ||
+ | ... | ||
+ | ] | ||
+ | ``` | ||
- | * Login into the panel as admin and go to the plugin management interface | + | By doing this, the repository will be automatically cloned under the |
- | * Upload the RoundcubePlugins plugin archive | + | `<PERSISTENT_PATH>/plugins/RoundcubePlugins/name` directory (eg: |
- | * Install the plugin | + | `/var/www/imscp/gui/data/persistent/plugins/RoundcubePlugins/repository_name)` |
- | ===== Update ===== | + | However, note that usage of the `git` section above is only needed if the Git |
+ | repository holds more than one plugin. Most of time, you can do the same thing | ||
+ | through composer, using a | ||
+ | [VCS](https://getcomposer.org/doc/05-repositories.md#vcs) repository. | ||
- | **1.** Get the plugin from github | + | For instance: |
- | # cd /usr/local/src | + | ```php |
- | # git clone git://github.com/i-MSCP/plugins.git | + | 'name' => [ |
+ | ... | ||
+ | 'composer' => [ | ||
+ | 'repositories' => [ | ||
+ | 'type' => 'vcs', | ||
+ | 'url' => "https://domain.tld/vendor/name.git" | ||
+ | ], | ||
+ | ... | ||
+ | ] | ||
+ | ] | ||
+ | ``` | ||
- | **2.** Create new Plugin archive | + | #### Roundcube plugin configuration |
- | # cd plugins | + | A last step is needed if you want to override default Roundcube plugin |
- | # tar cvzf RoundcubePlugins.tar.gz RoundcubePlugins | + | parameters. To to so, you can add a `config` section as follow: |
- | **3.** Backup your current plugin config | + | ```php |
+ | 'name' => [ | ||
+ | ... | ||
+ | 'config' => [ | ||
+ | 'file' => 'config.inc.php', | ||
+ | 'include_file' => '/foo/bar/baz.php, | ||
+ | 'parameters' => [ | ||
+ | 'param1' => 'value', | ||
+ | 'param2' => 'value' | ||
+ | ] | ||
+ | ] | ||
+ | ] | ||
+ | ``` | ||
- | # plugins/RoundcubePlugins/config.php | + | where: |
- | # plugins/RoundcubePlugins/config-templates/logon_page/logon_page.html | + | |
- | + | ||
- | **4.** Plugin upload and update | + | |
- | * Login into the panel as admin and go to the plugin management interface | + | - `file` is an OPTIONAL parameter that allows to override default plugin |
- | * Upload the RoundcubePlugins plugin archive | + | configuration template filename |
- | * Update the plugin list | + | - `include_file` is an OPTIONAL parameter that allows to provide the path of a file |
+ | that will be included in the Roundcube plugin configuration file. Note that the | ||
+ | file must be readable by the control panel user (eg: vu2000). A good place for | ||
+ | that file could be the `<PERSISTENT_PATH>/plugins/RoundcubePlugins` directory. | ||
+ | - `parameters`: is an OPTIONAL parameter that allows to provide plugin parameters. | ||
+ | Those parameters will be added at the end of the plugin configuration file | ||
- | ===== Configuration ===== | + | To resume, if you want to override a Roundcube plugin configuration parameter, |
+ | you must not edit its configuration file directly. Instead, you must process as | ||
+ | above. This is needed because the i-MSCP Roundcube package doesn't save your | ||
+ | changes on reconfiguration/update. | ||
- | For the different configuration options please check the plugin config file. | + | ##### Configuration script |
- | # plugins/RoundcubePlugins/config.php | + | Sometime a plugin can require more configuration works. For that purpose, you |
- | + | can provide your own configuration script as follows | |
- | After you made your config changes, don't forget to update the plugin list. | + | |
- | * Login into the panel as admin and go to the plugin management interface | + | ```php |
- | * Update the plugin list | + | 'name' => [ |
- | + | ... | |
- | ===== Authors ===== | + | 'config' => [ |
+ | ... | ||
+ | 'script' => '/foo/bar/baz.pl' | ||
+ | ] | ||
+ | ] | ||
+ | ``` | ||
+ | In the above example, we provide the `/foo/bar/baz.pl` Perl script. That script | ||
+ | will be executed automatically with the current action passed as first | ||
+ | argument: | ||
- | * Rene Schuster <mail@reneschuster.de> | + | - On Roundcube plugin pre-configuration: `/foo/bar/baz.pl pre-configure` |
- | * Sascha Bay <info@space2place.de> | + | - On Roundcube plugin configuration: `/foo/bar/baz.pl configure` |
+ | - On Roundcube pre-deconfiguration: `/foo/bar/baz.pl pre-deconfigure` | ||
+ | - On Roundcube deconfiguration: `/foo/bar/baz.pl deconfigure` | ||
+ | |||
+ | Note that the script must provides a correct | ||
+ | [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)). | ||
+ | |||
+ | For instance: | ||
+ | |||
+ | - `#!/usr/bin/env perl` for a Perl script | ||
+ | - `#!/usr/bin/env php` for a PHP script | ||
+ | - `#!/bin/sh` for a shell script | ||
+ | - ... | ||
+ | |||
+ | See [configure-managesieve.pl](https://github.com/i-MSCP/plugins/blob/master/incubator/RoundcubePlugins/config/scripts/configure-managesieve.pl) for an | ||
+ | example. | ||
+ | |||
+ | ## List of default Roundcube plugin definitions | ||
+ | |||
+ | - `additional_message_headers`: Add additional headers to or remove them from outgoing messages. | ||
+ | - `archive`: Adds a button to move the selected messages to an archive folder. | ||
+ | - `calendar`: Provide calendaring features. | ||
+ | - `contextmenu`: Creates context menus for various parts of Roundcube using commands from the toolbars. | ||
+ | - `emoticons`: Adds emoticons support. | ||
+ | - `logon_page`: Logon screen additions. | ||
+ | - `managesieve`: Adds a possibility to manage Sieve scripts (incoming mail filters). | ||
+ | - `newmail_notifier`: Provide notifications for new emails. | ||
+ | - `odfviewer`: Open Document Viewer plugin. | ||
+ | - `pdfviewer`: Inline PDF viewer plugin. | ||
+ | - `password`: Password Change for Roundcube. | ||
+ | - `rcguard`: Enforces reCAPTCHA for users that have too many failed logins | ||
+ | - `tasklist`: Task management plugin. | ||
+ | - `vcard_attachments`: Detects vCard attachments and allows to add them to address book... | ||
+ | - `zipdownload`: Adds an option to download all attachments to a message in one zip file... | ||
+ | |||
+ | ## License | ||
+ | |||
+ | i-MSCP - internet Multi Server Control Panel | ||
+ | Copyright (C) 2017 Laurent Declercq <l.declercq@nuxwin.com> | ||
+ | |||
+ | This program is free software; you can redistribute it and/or modify | ||
+ | it under the terms of the GNU General Public License as published by | ||
+ | the Free Software Foundation; version 2 of the License | ||
+ | |||
+ | This program is distributed in the hope that it will be useful, | ||
+ | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
+ | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | ||
+ | GNU General Public License for more details. | ||
+ | |||
+ | See [LICENSE](https://github.com/i-MSCP/plugins/blob/master/incubator/RoundcubePlugins/LICENSE) | ||
+ | </markdown> |