====== Deploying New Extensions for Greenstone3 ======


===== Overview =====

Deploying extensions is now a relatively simple task in Greenstone, thanks to recent updates to the extension manager system in GAI (The Greenstone Administrator Interface). In order to make your extension available to the world of Greenstone users, you must first edit the //extension_project_list.xml// file located in http://svn.greenstone.org/main/trunk/greenstone3/ext/ (this tutorial assumes you are an experienced SVN user). In the //extension_project_list.xml// file you can define how users download, install and run your extension. This file is read by the GAI extension manager when it is run and creates the necessary buttons for each of these steps.

For reference, here is an example of an extension entry in the extension file:

<code>
<extensionList baseURL="http://svn.greenstone.org/gs3-extensions/">
  <extension>
    <name>Metadata Quality Tool</name>
    <group>Java / Web</group> 
    <fileStem>mat</fileStem>
    <description>
      ...
    </description>
    <sequenceList>
      <step id="installOptions" action="properties" label="Install options" dependsOn="AUTOMATIC_DOWNLOAD">
	<optionList id="Mat" label="Mat options">
	  <option id="User_Name" label="User name"/>
	  <option id="Password" label="Password"/>
	  <option id="Tomcat_Port" label="Tomcat port"/>
	  <option id="JVM_Version" label="Java Virtual Machine version"/>
	</optionList>
      </step>
      <step id="install" action="button" label="Install" dependsOn="installOptions">
	<command>
	  <os name="default">ant compile</os>
        </command>
      </step>
      <step id="controlPanel" action="panel" label="Control Panel" dependsOn="install">
	<class>org.greenstone.admin.guiext.mat.ControlPanel</class>
      </step>
      <step id="uninstall" action="button" label="Uninstall" dependsOn="install" rollbackTo="install">
	<command>
	  <os name="default">ant clean</os>
	</command>
      </step>
    </sequenceList>
  </extension>
  ...
</extensionList>
</code>

===== Basic extension information =====

Firstly you will want to go to the bottom of the file (one line above the </extension_list> tag) and create a new set of <extension> tags for your extension's information to reside within. Within these tags you will want to include the following tags:

  * **<name>**: Between these tags you include the name of your extension (e.g., <name>Example Extension</name>).

  * **<group>**: Here you write the name of the group of extensions that you want your extension to belong to (e.g., <group>Example Group</group>), this affects where your extension will be placed in the extension tree view in the extension manager.

  * **<fileStem>**: This indicates what folder the extension will be downloaded to within the //ext// directory within Greenstone 3. Also if your first <step> (discussed later) does not have a download action then one is automatically created by combining the base URL (specified as an attribute in the <extensionList> element at the top of the file) with this value (for example, if the base url is <nowiki>"http://svn.greenstone.org/gs3-extensions/"</nowiki> and the file stem value is "mat" then the resulting URL will be <nowiki>"http://svn.greenstone.org/gs3-extensions/mat"</nowiki>. A good guideline for deciding on this value is to use an abbreviated version of the extension name without spaces (e.g., "mat" rather than "Metadata Analysis Tool").

  * **<description>**: This is what users will see when they initially select your extension in the extension manager. You may want to include details such as: what does this extension do? who would find this extension useful? are there any software/hardware prerequisites for this extension?

===== Steps =====
==== Attributes ==== 

After this information you create each of the buttons available in the extension manager (e.g., Download, Install, Remove etc.). These are specified as a series of <step> elements within a <sequence_list> element. The order of the <step> elements specifies the order in which the buttons will be displayed. Each <step> element should have the following attributes:

  * **id**: This is the internal name for this step. It is used to control dependencies (e.g., the installation step depends on the download step), see "dependsOn" and "rollbackTo" for more details.

  * **label**: This attributes defines what text will be written on the button that corresponds to this step.

  * **action**: This can be one of five different values: "download", "properties", "button", "panel" and "remove". These are discussed later.

A step can also have two more optional attributes:

  * **dependsOn**: This attribute defines the id(s) of the step(s) that must be executed before this step is enabled. More than one value can be specified by separating each step id with a comma. Because you cannot specify the id of a download or remove button that is automatically created the ids "AUTOMATIC_DOWNLOAD" and "AUTOMATIC_REMOVE" respectively can be used to depend on these automatic steps.

  * **rollbackTo**: This attribute can be used to remove dependencies back to a specified step (for example, after an uninstall step you may wish to disable all steps that depend on the program being installed which could be achieved by rolling back to the install step). More that one step id can be specified in this attribute by separating each id with commas.  

==== Actions ==== 

There are five types of <step> elements and they are as follows:

==== Download ==== 

A download step can be used to download something from the Internet. As discussed earlier, a download step is expected to be the first step in the list of steps. If the automatic download button is not sufficient for your needs then by specifying your own download step as the first step the automatic button is no longer created. A download <step> element can contain the following elements:

  * **<mainSource>**: A download step must contain one of these elements. The URL for this resource is placed between the <mainSource> tags. It also requires a "method" attribute to specify how to obtain this resource. Here is what the <mainSource> element would look like in the example file above: <mainSource method="svn"><nowiki>http://svn.greenstone.org/gs3-extensions/mat/trunk/</nowiki></mainSource>

  * **<auxSource>**: These are exactly the same as a <mainSource> element except that there can be more than one of them and they can contain a "folder" attribute that specifies the folder for this download to be put into.

=== Properties ===

A properties step can be used to store user specified values in a properties file. A properties <step> element can contain:

  * **<optionList>**: <optionList> elements are used to group together sets of <option> elements. An <optionList> element can contain any of the following attributes. If an "id" attribute is specified then all options within that option list will be recorded as "[OPTIONLIST ID].[OPTION ID] = [VALUE]" in the properties file (if it is not set then only the option id is used). For example, the option list in the sample has the "id" attribute set to "Mat", so all properties will be recorded as "Mat.[OPTION ID]" (e.g., Mat.User_Name). A "label" attribute can also be specified, this is used to label the set of options in the extension manager. Finally, a "file" attribute can also be specified, properties within this option list will be saved to this file rather than the default file "build.properties". <optionList> elements need to contain at least one <option> element.
    * **<option>**: <option> elements specify the properties you want the user to set. An <option> element must contain an "id" attribute as this affects what the option is saved as in the property file. The "label" attribute is used as the property name in the extension manager. If the "label" attribute is not set then the "id" attribute will be used instead. Finally, a value can be placed within the <option> tags, this value will be used as the default value in the extension manager. For example, <option id="User_Name" label="User name">ADMIN</option> specifies that "ADMIN" will be used as the default value for the User_Name option.

=== Button ===

A button step performs one or more of two types of commands. A button <step> element can contain as many commands as necessary but needs to contain at least one. The two types of command are represented by two different elements:

  * **<command>**: These elements allow you to run commands on the command line. The commands can be specific to particular operating systems, this is controlled by <os> elements. Every <command> element must contain at least one <os> element.
    * **<os>**: An <os> element must have a "name" attribute that specifies the operating system for this command, several examples of valid operating system names include "Linux", "Mac OS [X]", "Windows" and "Windows [2000|7|95|98|NT|Vista|XP]". Setting the name to "default" allows you to specify an operating system independent command. For each <command> element the system will look for an <os> element that matches the current computer's operating system, if one cannot be found it will look for a "default" option, if a default option is not specified then an error message will be printed. To avoid this message an empty default <os> element (e.g., <os name="default"/>) can be placed into this <command> element. The actual command to be executed for the specified operating system is placed between the <os> tags.

  * **<callback>**: These elements allow you to call the Java method //doCallback(String param)// on the class specified between the <callback> elements. The <callback> element can have a "param" attribute and this is passed to the doCallback method as a Java String.

=== Panel ===

A panel step allows you to display a Java panel within the extension manager. The Java class that displays the panel must implement the //org.greenstone.admin.guiext.BasePanel// interface. Like the <callback> code, this class needs to be within //guiext.jar// which should be located at the top level of your extension's folder.

**<class>**: Between <class> tags you specify the name of the class that implements the //BasePanel// interface that will be shown within the extension manager (e.g., <class>org.greenstone.myextension.MyControlPanel</class>). 

=== Remove ===

Currently the only functionality provided by remove steps are to delete the directory of this current extension. Like download steps, if one of these is not specified as the last step then one is automatically created.