
Name: PLUGIN_ARCHITECTURE
Version: 0.3
Summary: This document describe the Association Subscribers Manager (refered as "Assuma") addon system architecture.

WARNING: This document is not even close of a specification, it's only a working document for me (and almost only for me : it's notes)

I - Need:
---------

Assuma needs a addon system too allow easy extension and greater adaptation to any requirements.
Since it is coded in C++/Qt4 we want to use all the power of this framework. So we want to make the addon system very flexible and easy to learn.

II - Technical solution:
------------------------

From the express of the needs it is obvious that we will use the full  power of the Qt4 framework by allowing :
- C++ binary addons;
- Qt Script ECMA addons.

The roadmap for those to be included in the Assuma core application is :
  * 3.0 release : Qt ECMA scripts based addons supported;
  * 3.1 release : C++ binary addons supported. (this have been delayed, maybe in a later release of the 3.1 branch or most probably in the 3.2)

We also want a flexible yet easy to code/learn addon system, so will implements a unique interface for both kind of addons.
A addon will be described as a package which contains a description file (XML formatted) and the actual code.

All addons will be in the <data directory>/addons/ directory. 

A "package" consists in a directory like that :

Assuma root dir/
   |_ data/
       |_ addons/
           |_ MyAddon
	       |_ addon.xml
	       |_ MyAddon.js
	       |_ MyAddon.ui
	       |_ MyAddon.so
	       |_ MyAddon.qm

A addon directory contains at minimum a "addon.xml" file. The this file is mandatory and will be described later.
It can also contains all needed files (code, images, translations, etc.), and addon developpers are free to organize all 
those file into subdirectories. It is even strongly recommended for addons that are not trivials.

The C++ classes will be abstracted like the following :

    * AssumaAddonEngine :
        - will instanciate addons, 
	- manage them,
	- make global UI objects available to them.
    * AssumaAddonInstance :
	- the class wich represents an addon instance. Only descriptive, contains (meta)informations but not runable code.
    * AssumaAddonXmlHandler :
	- the XML handler for the addon.xml file.

III - Annexes :
---------------

A) addon.xml format and allowed tags :

Here are the general tags, used for information purpose.

<Addon> : this is the root tag, takes no attribute. Mandatory.
<Name>  : the addon name. Mandatory.
<Version> : the addon version number. Mandatory.
<Author> : authors of the addon, can be a CDATA. Optional.
<License> : the addon's license. Optional. Default: GPL3.
<Description> : A short addon description, tell the user about the addon features. Can be a CDATA. Optional.

Here are the addon system specific tags :

<Type> : Addon type, can be either "script" or "binary". Mandatory.
<CodeFile> : a code file can be a script (ECMA) or a binary plugin (.so, .dll and whatever it is on Mac OS X).
	    Put the relative path to all plugin code files here (one by element). Mandatory.
	    Multiple occurence are allowed.
<Ui> : the .ui file. Only used if <Type> is "script". Put the relative path to the file. Optional.
      WARNING: so far only one UI file is supported.
<Locale> : relative path to a translation  file. It must be the compiled form of Qt's i18n files (.qm). Optional.
	Takes a mandatory attribute : lang, which is the language code.
	Multiple occurence are allowed.


Example:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Addon>
  <!-- Information tags -->
  <Name>MyAddon</Name>
  <Version>0.1</Version>
  <Author>Arnaud Dupuis</Author>
  <License>GPL3</License>
  <Description>A description that can be in a CDATA element</Description>
  
  <!-- Addon tags -->
  <Type>script</Type>
  <CodeFile>MyAddon.js</CodeFile>
  <CodeFile>MyAddonConfig.js</CodeFile>
  <Ui>MyAddon.ui</Ui>
  <Locale lang="fr-FR">MyAddon_fr-FR.qm</Locale>
  <Locale lang="en-US">MyAddon_en-US.qm</Locale>
</Addon>