RT @jvoskuhl: @zarafagroupware Today i received my #Zarafa Certified Engineer certificate... Happy :-) http://t.co/ozMCGuCvCA
First of all, plugins have a separate directory in WebApp, called 'plugins'. This directory contains all addons (plugins and widgets). Each plugin or widget should have one separate directory. In order for your plugin to integrate into WebApp correctly, create a new folder in [WebApp root folder]/plugins directory with the name of your plugin e.g. plugins/facebookwidget or plugins/spreed.
For example, the Spreed plugin folder has the following contents:
An example of the contents of a widget is the facebook widget. This doesn't have a server side, so the php files are omitted:
The subfolder names and hierarchy given are just examples. They can be changed arbitrarily, but it still should stay intuitively understandable; the names given in the examples are "best practices". Only the manifest.xml file is mandatory.
Example manifest file for Spreed plugin:
<?xml version="1.0"?> <!DOCTYPE plugin SYSTEM "manifest.dtd"> <plugin version="2">
First block represents the common info about plugin - the version, the name, display title, who wrote it and a short description.
<info> <version>1.2</version> <name>spreed</name> <title>Zarafa Spreed Integration</title> <author>Zarafa</author> <authorURL>http://www.zarafa.com</authorURL> <description>Zarafa Spreed Integration, allows you to set-up a conference call from within emails, contact groups, or single contact cards.</description> </info>
Second block is the configuration. Here you can describe which configuration files are available. This block is optional.
<config> <configfile>config.php</configfile> </config>
Third block describes the components - the files that are used in your plugin. It gives you an ability to split your plugin up to the multiple components. Also external libraries can be included here for plugins.
<components> <component> <files>
Communication with clientside is done via class.spreedmodule.php
<server> <serverfile>php/plugin.spreed.php</serverfile> <serverfile type="module" module="spreedmodule">php/class.spreedmodule.php</serverfile> </server>
The client section indicates which files are present. WebApp only loads those files that are indicated using these tags, so list everything that must be included.
The optional 'load' attribute is important here, it indicates how files are loaded; it can take one of three values: source, debug or release.
source - this is one individual file that you created during development (note, if you use this, you must list *all* files),
debug - the one file concateneted, compiled from all your files, and
release - is the compressed debug file, with the comments cut off, variables' names changed.
If the 'load' attribute is omitted, then plugin files will be loaded in 'release' mode automatically.
<client> <clientfile load="release">js/spreed.js</clientfile> <clientfile load="debug">js/spreed-debug.js</clientfile> <clientfile load="source">js/SpreedPlugin.js</clientfile> <clientfile load="source">js/dialogs/AddressBookRecipientPanel.js</clientfile> // ... etc, listing all files in the dialogs directory <clientfile load="source">js/data/DialogTypes.js</clientfile> // ... etc, listing all files in the data directory </client>
Here are css files needed in your plugin. They are additional to core WebApp files, so you can add more styles and/or override existing css styles.
<resources> <resourcefile load="release">resources/css/spreed.css</resourcefile> <resourcefile load="source">resources/css/plugin.spreedstyles.css</resourcefile> </resources> </files> </component> </components> </plugin>
The information given in the info block can be used by the system administrators for plugin management.
The way WebApp is loaded can be defined in debug.php. The DEBUG_LOADER constant determines what to load. It can be one of the following values:
It is not required to provide all 3 loading types in your plugin. If you omit any, then the following happens to determine which files are loaded: If debug.php has DEBUG_LOADER equal to LOAD_SOURCE and the plugin has source files, then they are used. However, if the plugin doesn't provide source or if DEBUG_LOADER is set to LOAD_DEBUG, the fallback is debug. If no debug files are provided either, then the release files are loaded, regardless of the setting of DEBUG_LOADER. Note that, if you have no debug.php or DEBUG_LOADER is not set there, the release files are loaded, always.
The process of creating and maintaining release and debug files for your plugin is documented in chapter 13.2 of the WebApp developers' manual.
Before publishing your plugin, you should validate the manifest file, even if it works ok during development. Validation will check that the XML really is valid, and it checks that all resources listed in the manifest are available. It is useful for detecting errors in the XML markup. To perform validation run the following command:
xmllint --valid --path [path to webapp server] [path to manifest to validate]
If this command doesn't return any errors, you can assume WebApp will be able to properly load your plugin.
Plugins can be controlled by predefined PHP constants, for configuration. All WebApp plugins provided by Zarafa have at least one option, defined in a PHP file called config.php, to let the system administrator enable or disable the plugin for all users by default. We recommend that you follow this practice. We send this option to the client, and the Settings model is set up according to this value. For example, your plugin might contain the following config.php file:
<?php /** Enable the plugin for all clients */ define('PLUGIN_MYPLUGIN_USER_DEFAULT_ENABLE', false); ?>
Here we set the default value of the plugin settings for every user's first use, even before any changes can be made by the user. The configuration values should be unique across all plug-ins, so take care to substitute MYPLUGIN with something discernible.