Plugin descriptor

1. Plugin descriptor overview

Every plugin must contain descriptor file qcadoo-plugin.xml. It gathers all most important data about plugin informations and structure.

All changes that are made by plugin (like adding table to database, adding new view, changing existing system behavior etc) must be defined in modules section of this file.

2. Descriptor structure

2.1. Basic structure

Plugin descriptor must have general structure:

<?xml version="1.0" encoding="UTF-8"?>

<plugin plugin="pluginIdentifier" group="pluginGroup" version="pluginVersion"
     xmlns="http://schema.qcadoo.org/plugin" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://schema.qcadoo.org/plugin http://schema.qcadoo.org/plugin.xsd">

     // HERE PUT PLUGIN CONTENT

</plugin>

Where:

pluginIdentifier - unique identifier of plugin
pluginGroup - in most cases it will represent the plugins "location" in the main menu
pluginVersion - version of plugin. Version can contain at most three numbers separated by dots (ex. 4.1.15 , 0.1.01 , 5)

All plugin informations should be put inside <plugin> tag.

2.2. Plugin additional informations

Plugin additional informations section is required. It contains informations like name, description or producer. This data are information only - changing it will not affect any of plugin behavior.

Informations section must match schema:

<information>
     <name>pluginName</name>
     <description>pluginDescription</description>
     <vendor>
          <name>vendorName</name>
          <url>vendorUrl</url>
     </vendor>
	 <license>license</license>
</information>

Where:

pluginName - (required) name of plugin displayed to user
pluginDescription - (optional) additional description of plugin

<vendor> tag is optional. If specified:

vendorName - (required) represents name of vendor displayed to user
vendorUrl - (optional) Url to vendor's website
license - AGPL or if it is not open source then just "Commercial".

2.3. Plugin dependencies

Plugin may required other plugins to work correctly - for example when it extends some existing model or views. In this case it is necessary to define dependencies section:

<dependencies>
     <dependency>
          <plugin>dependencyPluginIdentifier</plugin>
          <version>dependencyPluginVersion</version>
     </dependency>

     // HERE PUT OTHER DEPENDENCIES

</dependencies>

Inside <dependencies> tag one or more dependency can be defined. Each dependency consists:

dependencyPluginIdentifier - (required) identifier of plugin that this plugin requires
dependencyPluginVersion - (optional) required version of this plugin

Dependency plugin version can specify minimum version, maximum version or both. For example:

dependency version	description
`[0.4.0`	requires plugin in version greater or equals 0.4.0
`(2.1,3.0]`	requires plugin in version greater than 2.1 and smaller or equals 3.0
`4.0.15)`	requires plugin in version smaller than 4.0.15

2.4. Plugin modules definition

Modules definition are the most important part of plugin descriptor file.

<modules>

     // HERE PUT MODULE DEFINITIONS

</modules>

<modules> tag contains all module definitions. Every module represents single change to the system made by plugin. For more informations about avaliable modules see full modules list.

For every module type used in descriptor corresponding schema should be added to root <plugin> tag.

2.5. Plugin features definition

Modules definition are the most important part of plugin descriptor file.

<features>
  <end-user/>
  <external-integration system="subiekt"/>
  <internal-integration/>
  <dev-library/>
  <plugin-pack/>
</features>

what type of features does this plugin deliver - one plugin can have many:

end-user - plugin contains functions that are clearly visible to the end-user in the GUI
external-integration - adds API and functions to integrate with external systems
internal-integration - see MDR-5 - Suggest to turn on internal integration plugins
dev-library - has services, entities and/or utils that should be reused by other plugins
plugin-pack - just aggregates some plugins with it's dependancies into a package

3. Example

Here is example of plugin descriptor:

<?xml version="1.0" encoding="UTF-8"?>

<plugin plugin="clients" version="1.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="http://schema.qcadoo.org/plugin" 
     xmlns:model="http://schema.qcadoo.org/modules/model"
     xmlns:view="http://schema.qcadoo.org/modules/view"
     xmlns:menu="http://schema.qcadoo.org/modules/menu"
     xmlns:localization="http://schema.qcadoo.org/modules/localization"
     xsi:schemaLocation="
          http://schema.qcadoo.org/plugin
          http://schema.qcadoo.org/plugin.xsd
          http://schema.qcadoo.org/modules/model
          http://schema.qcadoo.org/modules/model.xsd
          http://schema.qcadoo.org/modules/view
          http://schema.qcadoo.org/modules/view.xsd
          http://schema.qcadoo.org/modules/localization
          http://schema.qcadoo.org/modules/localization.xsd
          http://schema.qcadoo.org/modules/menu
          http://schema.qcadoo.org/modules/menu.xsd
          ">

     <information>
          <name>Clients Extension</name>
          <description>This plugin allows to store client data and add client to order</description>
          <vendor>
               <name>Qcadoo Limited</name>
               <url>http://www.qcadoo.com</url>
          </vendor>
     </information>

     <dependencies>
          <dependency>
               <plugin>basic</plugin>
               <version>[0.4.0</version>
          </dependency>
          <dependency>
               <plugin>orders</plugin>
          </dependency>
     </dependencies>

     <modules>

          <localization:translation path="locales" />

          <model:model model="client" resource="model/client.xml" />

          <model:model-field plugin="orders" model="order">
               <model:belongsTo name="client" plugin="clients" model="client" />
          </model:model-field>

          <menu:menu-item name="clients" category="orders" view="clients" />

          <view:view resource="view/clients.xml" />

          <view:view-tab resource="view/productsExtension.xml" />

     </modules>

</plugin>