Skip to end of metadata
Go to start of metadata

Purpose of this Module Type

The custom field plugin module allows you to add new custom field types and searchers to JIRA.
  1. Custom field types - these define the type of a custom field
  2. 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

(tick)

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

(tick)

The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.

<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>

In the example, appProps is the key for this particular module declaration, for component-import, in this case. 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.

valid-searcher 

(Since JIRA v5.2)

This provides an alternative way to define a relationship between a Custom Field Type and a Custom Field Searcher (see also the valid-customfield-type element in Custom Field Searcher below).

Defines the searchers used for this custom field type. The package and key attributes together specify the module-complete key under which the custom field searcher is registered.

This is most useful for when you have a new Custom Field Type that wants to use an existing searcher from core JIRA or another plugin.

Example

Here is the custom field JIRA defines for selecting users (taken from system-customfieldtypes-plugin.xml):

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

(tick)

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

(tick)

The unique identifier of the plugin module. You refer to this key to use the resource from other contexts in your plugin, such as from the plugin Java code or JavaScript resources.

<component-import key="appProps" interface="com.atlassian.sal.api.ApplicationProperties"/>

In the example, appProps is the key for this particular module declaration, for component-import, in this case. 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

(tick)

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>.

Note that since JIRA v5.2 it is also possible to define this relationship in the opposite direction, that is to define searchers that are appropriate for a given custom field type. Strictly speaking this field is no longer mandatory - you need to define the relationship here or in the custom field type configuration. Practically, however, we would normally expect to see a custom field searcher define the applicable custom field types that it knows about. The alternative mechanism is intended for new custom field types defined in other plugins to re-use existing searchers.

Example

Here is the custom field searcher JIRA defines for searching users (also taken from system-customfieldtypes-plugin.xml):

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).

(info) For more details, see the Creating a Custom Field Type.
(info) To learn more about the custom field Velocity templates, see Custom field Velocity context unwrapped

  • No labels

1 Comment

  1. Anonymous

    Please have a look at Preparing for JIRA 6.1#custom-field-types for new features for custom fields introduced in JIRA 6.1