Getting the identifier

Every plugin has to have the unique identifier. It will be used as plugin's filename and as a namespace for the resources and database's table. Identifier can contain only digits and letters and has to start with a letter.

Let's assume that the identifier of The Warehouse plugin is warehouse.

Setting up the project

Please download the base of the new plugin, unzip it and go to the plugin directory. The structure of the plugin project is fully described on Plugin Overview page.

Edit pom.xml

Please open pom.xml to change basic plugin information:

• artifactId - it will be use as a identifier of the plugin (be sure not to change parent/artifactId)
• groupId - together with artifactId it will be used as a package of Your classes
• version - version of the plugin
• name, description, organization/name and orgranization/url - for information purposes only

This is the Warehouse's pom.xml:

<project>

	<modelVersion>4.0.0</modelVersion>

	<parent>
		<groupId>com.qcadoo.mes</groupId>
		<artifactId>mes-plugins</artifactId>
		<version>0.2</version>
	</parent>

	<groupId>com.warehousecorporation</groupId>
	<artifactId>warehouse</artifactId>
	<version>1.0-SNAPSHOT</version>

	<packaging>jar</packaging>

	<name>Very Simple Warehouse</name>

	<organization>
		<name>WarehouseCorporation.com</name>
		<url>http://www.warehousecorporation.com/</url>
	</organization>

	<description>This is a very simple warehouse for Qcadoo MES system.</description>

</project>

Rename files and directories

According to Plugin Overview we need to rename some files and directories:

• src/main/java/pluginpackage/ to src/main/java/com/warehousecorporation/warehouse
• src/main/reosurces/locales/pluginidentifier_en.properties to src/main/reosurces/locales/warehouse_en.properties
• src/main/reosurces/META-INF/css/pluginidentifier/ to src/main/reosurces/META-INF/css/warehouse/
• src/main/reosurces/META-INF/img/pluginidentifier/ to src/main/reosurces/META-INF/img/warehouse/
• src/main/reosurces/META-INF/js/pluginidentifier/ to src/main/reosurces/META-INF/js/warehouse/
• src/main/reosurces/META-INF/WEB-INF/jsp/pluginidentifier/ to src/main/reosurces/META-INF/WEB-INF/jsp/warehouse/

We also need to replace identifier in src/main/reosurces/model.xml and src/main/reosurces/view.xml to warehouse and package in src/main/reosurces/context.xml to com.warehousecorporation.warehouse.

Maven archetype

Another way to set up a new plugin project is to use a special maven archetype. When using this method you input certain parameters, which automatically generate the whole project with sample files (no need to change folder names or file names any more!). To do so you just need to have maven installed and be in the directory where you want your project.

To generate a new plugin project use the following maven command:

mvn archetype:generate -DarchetypeGroupId=com.qcadoo -DarchetypeArtifactId=qcadoo-plugin-archetype -DarchetypeVersion=0.4.0-SNAPSHOT -DartifactId=test3 -Dversion=0.4.0 -Didentifier=test4 -Dname=name -DvendorName=vendor -DvendorUrl=url [ -DgroupId=com.my.domain -Dpackage=package ]

• -DarchetypeGroupId - this should stay exactly as in the example above, it identifies the group to which the archetype belongs to
• -DarchetypeArtifactId - just like above, it identifies the artifact id of the archetype
• -DarchetypeVersion - this will change with time, it identifies the archetype's version. Currently 0.4.0-SNAPSHOT
• -DartifactId - required parameter, this will be your plugin's artifact id (set in the project's pom.xml)
• -Dversion - required parameter, this is your plugin's version (set in the project's pom.xml)
• -Didentifier - required parameter, this will be your plugin's name, appropriate folders and files will be renamed using it (i.e. the locale files), it will be used in the sample view.xml and model.xml as the view/model names.
• -Dname - required parameter, this will be your plugin's name (set in the project's pom.xml)
• -DvendorName - required parameter, this will be the name of the vendor who developed the plugin
• -DvendorUrl - required parameter, this will be the URL address of the vendor who developed the plugin
• -DgroupId - optional parameter, this is your plugin's group id (set in the project's pom.xml), the default value is "com.qcadoo.mes"
• -Dpackage - optional parameter, this should match your plugin's package structure which will be set in the root-context.xml, the default value is the same as the groupId
  

You can skip all parameter and use only:

mvn archetype:generate

In that case you will be prompted for all parameters in the command line.

After running the aforementioned command a project with the following structure will be created:

• src/
  • main/resources/
    • <identifier>/
      • model/
        • <identifier>.xml
      • view/
        • <identifier>.xml
      • locales/
        • <identifier>_en.properties
        • <identifier>_pl.properties
    • qcadoo-plugin.xml
    • root-context.xml
  • pom.xml

Where <identifier> will be replaced with the parameter you used. <identifier>.xml in the model and view folder are sample xml files for, respectively, the model and the view containing a simple view with a grid and a form and a model which contains 2 fields: a name and a number. Locale files contain all the necessary translations to get you up and running.

Pom.xml, qcadoo-plugin.xml and root-context.xml are all automatically filled out with the mvn archetype:generate parameters.

Generate Eclipse project

To generate Eclipse project we need to open terminal and type mvn eclipse:eclipse. Before opening the project you must have a Maven plugin installed in Eclipse. We suggest using Q4E which is now becoming Eclipse's official Maven plugin under the name Eclipse IAM. Please see the following page for instruction how to install it:

http://code.google.com/p/q4e/wiki/Installation

After you installed this plugin and restarted Eclipse you can import the project by following these steps:

• select File > Import in the menu
• select Maven 2 > Maven 2 Project in the Import dialog box
• click Next and select the warehouse plugins directory