Built by Maven

Writing a Plugin - Part 1 - Defining a UI Page

Define the UI Elements in an XML File

All plugin UI elements are defined and mastered in a XML file. The file defines each UI element and its attributes including: label, type, style, help text, tooltip text and validation type. An example of this is shown below. This example is used to create a new reporting plugin. The plugin defines a report template, which is a list of pre-defined values in a drop-down list and a report format which is another drop down list of values. These values are passed into the report generator as parameters to let the generator know which report to generate in a particular format.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<pluginData>
        <fields>
                <fieldKey>reportTemplate</fieldKey>
                <fieldValue></fieldValue>
                <label>Report Template</label>
                <type>SELECTONE</type>
                <listOfChoices>List Tables</listOfChoices>
                <style>width: 50em;</style>
                <mandatory>true</mandatory>
                <version>1.0.0</version>
                <helpText>This field lists all the available reports that can be generated with this Reporting plugin.
                        Please select the report you would like to generate.</helpText>
                <toolTipText>The report to generate.</toolTipText>
                <validationType>NOTEMPTY</validationType>
                <headerTitle>Report Parameters</headerTitle>
                <classType>java.lang.String</classType>
        </fields>
        <fields>
                <fieldKey>reportFormat</fieldKey>
                <fieldValue>pdf</fieldValue>
                <label>Report Format</label>
                <type>SELECTONE</type>
                <listOfChoices>pdf,csv,xls,xml,html</listOfChoices>
                <style>width: 50em;</style>
                <mandatory>true</mandatory>
                <version>1.0.0</version>
                <helpText>This field lists all the available report formats that can be generated with this Reporting plugin.
                        Please select the format type you would like the report generated in.</helpText>
                <toolTipText>The format type of the report to generate.</toolTipText>
                <validationType>NOTEMPTY</validationType>
                <headerTitle>Report Parameters</headerTitle>
                <classType>java.lang.String</classType>
        </fields>
    <name>CustomReports</name>
    <displayName>My Custom Reports</displayName>
    <description>This reporting plugin contains the default custom reports that can be generated.</description>
    <panelTitle>My Custom Report Service</panelTitle>
    <version>1.0.0</version>
</pluginData>

The XML definition file must be named ui-plugin.xml and located in the same Java package as the plugin.

Field Attributes

Below is a list of all the attributes which are used to define the UI components.

Field Attribute Name Description
fieldKey Unique name used to retrieve the field value.
fieldValue The default value used to display the component.
label Label used to display the UI component.
type Used to define what UI component to display. Possible values are: TEXT, SECRET, TEXTAREA, RADIO, SELECTONE, SELECTMANY, CHECKONE, CHECKMANY.
listOfChoices Used only if type is one of: RADIO, SELECTONE, SELECTMANY, CHECKONE, CHECKMANY, the list of choices to display.
style CSS style used to display the UI component.
mandatory Defines if the component is a mandatory or optional field.
version Used to work out if the field is used in this version of the plugin.
helpText Text displayed when the user clicks the help button of the UI component.
toolTipText UI tooltip text, displayed when the UI component is hovered over.
validationType Type of validation used on the field value. Possible values are: FILE, URL, STRING, NOTEMPTY, INTEGER, NONE, EMAIL, DIRECTORY, PASSWORD.
headerTitle The section header used to display the UI component in.
classType The class type used for the fieldValue

Conclusion

We have seen how we can easily create a new RapidDeploy Plugin UI definintion. In Part 2 of this tutorial we will look at how to create the Java domain class which is used to store the UI data.

Download the example project here