This page last changed on Feb 23, 2010 by bspeakmon.
Purpose of this Module Type
The custom field plugin module allows you to add new custom field types and searchers to JIRA.
- Custom field types - these define the type of a custom field
- Custom field seachers - these define the ways a custom field type can be searched
Custom Field Type Configuration
The root element for the custom field type plugin module is customfield-type. It allows the following attributes and child elements for configuration:
Attributes
Name |
Required |
Description |
Default |
class |
|
The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances. The Java class of the custom field type module. Classes must implement com.atlassian.jira.issue.customfields.CustomFieldType, but there are several concrete implementations that should address the majority of users' needs, including text fields, text areas, user pickers, etc. See the CustomFieldType javadoc for details. |
|
key |
|
The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the complete module key. A module with key fred in a plugin with key com.example.modules will have a complete key of com.example.modules:fred. I.e. the identifier of the custom field type module. |
N/A |
i18n-name-key |
|
The localisation key for the human-readable name of the plugin module. |
|
name |
|
The human-readable name of the plugin module. I.e. the human-readable name of the custom field type module. |
The plugin key. |
Elements
Name |
Required |
Description |
description |
|
A human-readable description of this custom field type plugin module. May be specified as the value of this element for plain text or with the key attribute to use the value of a key from the i18n system. |
resource type="velocity" |
|
Velocity templates that implement the custom field views. |
Example
Here is the custom field JIRA defines for selecting users (taken from system-customfieldtypes-plugin.xml):
<customfield-type key="userpicker" name="User Picker"
class="com.atlassian.jira.issue.customfields.impl.UserCFType">
<description>
Choose a user from the user base via a popup picker window.
</description>
<!-- this template is used on the view issue page -->
<resource type="velocity" name="view"
location="templates/plugins/fields/view-user.vm" />
<!-- this template is used on the create/edit issue pages -->
<resource type="velocity" name="edit"
location="templates/plugins/fields/edit-userpicker.vm" />
<!-- this template is used when viewing an issue as XML -->
<resource type="velocity" name="xml"
location="templates/plugins/fields/xml-user.vm" />
</customfield-type>
Custom Field Searcher Configuration
The root element for the custom field searcher plugin module is customfield-searcher. It allows the following attributes and child elements for configuration:
Attributes
Name |
Required |
Description |
Default |
class |
|
The class which implements this plugin module. The class you need to provide depends on the module type. For example, Confluence theme, layout and colour-scheme modules can use classes already provided in Confluence. So you can write a theme-plugin without any Java code. But for macro and listener modules you need to write your own implementing class and include it in your plugin. See the plugin framework guide to creating plugin module instances. The Java class of the custom field searcher. Classes must implement com.atlassian.jira.issue.customfields.CustomFieldSearcher, but there are several concrete implementations that can handle searching for JIRA's built-in fields. See the CustomFieldSearcher javadoc for more details. |
|
key |
|
The identifier of the plugin module. This key must be unique within the plugin where it is defined.
Sometimes, in other contexts, you may need to uniquely identify a module. Do this with the complete module key. A module with key fred in a plugin with key com.example.modules will have a complete key of com.example.modules:fred. I.e. the identifier of the custom field searcher module. |
N/A |
i18n-name-key |
|
The localisation key for the human-readable name of the plugin module. |
|
name |
|
The human-readable name of the plugin module. I.e. the human-readable name of the custom field searcher module. |
The plugin key. |
Elements
Name |
Required |
Description |
description |
|
A human-readable description of this custom field searcher plugin module. May be specified as the value of this element for plain text or with the key attribute to use the value of a key from the i18n system. |
resource type="velocity" |
|
Velocity templates that implement the custom field searcher views. |
valid-customfield-type |
|
Defines the custom field types this searcher can apply to. The package and key attributes together specify the module-complete key under which the custom field is registered; if the searcher is defined in the same atlassian-plugin.xml as the type (which is the usual case), then package should be the same as the key attribute on <atlassian-plugin>. |
Example
Here is the custom field searcher JIRA defines for searching users (also taken from system-customfieldtypes-plugin.xml):
<customfield-searcher key="userpickersearcher" name="User Picker Searcher"
class="com.atlassian.jira.issue.customfields.searchers.UserPickerSearcher">
<description>
Allow to search for a user using a userpicker.
</description>
<!-- this template is used on the issue navigator search form -->
<resource type="velocity" name="search"
location="templates/plugins/fields/search-userpicker.vm" />
<!-- this element defines the valid custom field types for this searcher -->
<valid-customfield-type
package="com.atlassian.jira.plugin.system.customfieldtypes" key="userpicker" />
</customfield-searcher>
Notes
Types and searchers can be combined in different ways to produce new custom fields, for example a "user" custom field could take a simple text searcher (to enter the username as text) or a more complex "user picker searcher" (where the user is picked from a popup window).
For more details, see the How to create a new Custom Field Type.
To learn more about the custom field Velocity templates, see Custom field Velocity context unwrapped
|