Custom field plugin module

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

Description

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

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.

Default: the plugin key.

*class and key attributes are required.

Elements

Name

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

<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

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

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.

Default: the plugin key.

*class and key attributes are required.

Elements

Name

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

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.

*valid-customfield-type element is required.

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>

Velocity context for custom fields

Below is a list of available objects in the Velocity context for custom fields.

Object

Description

customField

com.atlassian.jira.issue.fields.CustomField object. Information on the current field.

edit: yes, view: yes, col-view: yes

issue

com.atlassian.jira.issue.Issue object. Pretty much everything about the issue.

edit: yes, view: yes, col-view: yes

fieldLayoutItem

com.atlassian.jira.issue.fields.layout.field.FieldLayoutItem. Is field required? hidden?

edit: yes, view: no, col-view: no

action

Calling action.

edit: yes, view: no, col-view: no

displayParameters

Custom parameters to the template, such as whether to display headers or not

edit: yes, view: no, col-view: no

value

String value of the custom field. Thus this is a String for Date and other single valued fields, List of Strings for Multi selects and CustomFieldParams full of Strings for Cascading selects

edit: yes, view: yes, col-view: yes

customFieldParams

This is where the value is pulled from, for convenience

edit: yes, view: yes, col-view: yes

config

com.atlassian.jira.issue.customfields.config.CustomFieldConfig object.

edit: yes, view: no, col-view: no

configs

The various configuration items for that context. This include things like, default values, select list options and other configurable options

edit: yes, view: no, col-view: no

i18n

com.atlassian.jira.web.bean.I18nBean for your internationalisation needs

edit: yes, view: yes, col-view: yes

descriptor

The module descriptor of the current field

edit: yes, view: yes, col-view: yes

textutils

com.opensymphony.util.TextUtils for text manipulation needs

edit: yes, view: yes, col-view: yes

outlookdate

com.atlassian.jira.web.util.OutlookDate for formatting dates, JIRA style

edit: yes, view: yes, col-view: yes

authcontext

com.atlassian.jira.security.JiraAuthenticationContext for authentication information

edit: yes, view: yes, col-view: yes

dateutils

com.atlassian.core.util.DateUtils more date functions

edit: yes, view: yes, col-view: yes

req

HttpServletRequest object.

edit: yes, view: yes, col-view: yes

baseurl

The getContextPath of the req object

edit: yes, view: yes, col-view: yes

constantsManager

The com.atlassian.jira.config.ConstantsManager object for managing "constants" (issue types, resolutions etc.)

edit: yes, view: yes, col-view: yes

projectManager

com.atlassian.jira.project.ProjectManager

edit: yes, view: yes, col-view: yes

applicationProperties

com.atlassian.jira.config.properties.ApplicationProperties

edit: yes, view: yes, col-view: yes

jirautils

com.atlassian.jira.util.JiraUtils a random set of methods. has isPublic method

edit: yes, view: yes, col-view: yes

jirakeyutils

com.atlassian.jira.util.JiraKeyUtils an object used for parsing keys

edit: yes, view: yes, col-view: yes

buildutils

com.atlassian.jira.util.BuildUtils has information on build numbers, editions etc.

edit: yes, view: yes, col-view: yes

velocityhelper

com.atlassian.jira.util.JiraVelocityHelper random set of utility methods

edit: yes, view: yes, col-view: yes

userutils

com.atlassian.core.user.UserUtils untility for getting users

edit: yes, view: yes, col-view: yes

+ Other velocity parameters from the custom field type

Adding searching to a custom field

Custom fields need a custom field searcher before you can search them in the Issue Navigator. If a custom field type is a going to behave somewhat like an existing type, then you can reuse an existing searcher. For example, if you're creating a custom field type that's like a multi select list and want to reuse the default multi-select searcher, you could add the block below to your atlassian-plugin.xml (taken from system-customfieldtypes-plugin.xml)

<customfield-searcher key="multiselectsearcher" name="Multi Select Searcher"
    i18n-name-key="admin.customfield.searcher.multiselectsearcher.name"
    class="com.atlassian.jira.issue.customfields.searchers.MultiSelectSearcher">
    <description key="admin.customfield.searcher.multiselectsearcher.desc">Search for multiple values using a single select list.</description>

    <resource type="velocity" name="search" location="templates/plugins/fields/edit-searcher/search-multiselect.vm"/>
    <resource type="velocity" name="view" location="templates/plugins/fields/view-searcher/view-searcher-multioption.vm"/>
    <resource type="velocity" name="label" location="templates/plugins/fields/view-searcher/label-searcher-basictext.vm"/>
    <valid-customfield-type package="YOUR CUSTOM PACKAGE" key="YOUR CUSTOM FIELD KEY"/>
</customfield-searcher>

which will enable searching for any text based, multi-select custom field type. When creating the custom field, you will now be able to select the multi-select searcher and your custom field should then be displayed in the Issue Navigator.

Note that "YOUR CUSTOM PACKAGE" refers to the package (ie. the module key) of the custom field that the searcher applies to, which is the "key" attribute of the top-level atlassian-plugin element. "YOUR CUSTOM FIELD KEY" refers to the "key" attribute of the customfield element.

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

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport