View Source

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	Description	Default
class	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	I.e. the identifier of the custom field type module.	N/A
i18n-name-key
name	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	Description	Default
class	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	I.e. the identifier of the custom field searcher module.	N/A
i18n-name-key
name	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