The Best Open Source Email & Collaboration Software

English English down

WebApp: How to Tell WebApp About Your Plugin

So you had a great idea for a WebApp plugin or widget, and started creating Javascript and possibly even some PHP files. Now you certainly need to make your cool plugin available for use in WebApp. It will not do this by itself; so you need to register your plugin into the WebApp Plugin Framework. In this post, we'll tell you how to do this.

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:

  • js - folder for all Javascript files.
    • data - folder. All classes related to working with data are stored here.
    • dialogs - folder. All classes related to dialogs and user interface should be placed here.
    • SpreedPlugin.js. Main plugin class.
  • php - folder for all PHP files.
    • data - folder. Data stored here like list of timezones.
    • inc - folder. PHP classes stored here.
  • resources - folder.
    • css - folder. CSS resources places here.
    • icons - folder. Various icons stored here.
  • build.xml. Forr building spreed plugin
  • config.php. Defined `php` configuration constants.
  • manifest.xml. Manifest file.

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:

  • js- folder.
    • FBWidget.js. Widget class.
  • resources - folder.
    • css - folder. CSS files for the widget placed here.
  • images - folder //images for the widget go here.
    • facebook.png
  • build.xml
  • manifest.xml

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.

Previously, in Zarafa WebAccess, each plugin had to contain a manifest file; we copied this requirement to WebApp. In these manifest files, we can describe the contents of each plugin. This is the way in which WebApp can be told which Javascript and PHP files are provided and also which css-files must be applied to this plugin.

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>

Spreed files shown in Firebug

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:

  • LOAD_RELEASE - Load the concatenated-and-compressed files
  • LOAD_DEBUG - Load the concatenated files
  • LOAD_SOURCE - Load the original source files (for developers)

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.

Bonus: configuration of your plugin via config.php

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.

Useful Links:

 


Share:

Comments

Post new comment

 

Jobs at Zarafa

View zarafa tour 2013 video

Zarafa customers