Since JIRA 3.0 you have been able to create your own Custom Field Types through the plugin interface. In this tutorial, we'll take a look at a few simple examples and explain how you can easily achieve this.
A Quick Custom Field Types Primer
There's a few things you need to understand before diving into custom fields. A custom field type can have three components.
- Java Class encapsulating custom field logic
- Resource templates for display of custom field
- Module descriptor to enable the custom field module in JIRA
A custom field class extends the interface CustomFieldType. This interface provides methods to retrieve and store custom fields values. There are several extension points that are available to make creating new custom field types easier (e.g. CalculatedCFType, AbstractSingleFieldType, AbstractMultiSettableCFType). It is also possible to extend existing custom field types to add functionality (e.g. A currency type extending NumberCFType).
The second component are the resource templates which render the custom field. There are four view types available, each representing a different context to render the custom field.
view- basic read-only view of the value (e.g. view issue, move issue confirm screen)
column-view- read-only view for displaying in the issue navigator. will default to view if omitted
edit- renders the edit widget for the custom field (e.g. edit issue, edit defaults)
xml- xml view of the value (e.g. rss, xml views)
The values of these templates are usually Velocity template files that are either standard JIRA
.vm files, or ones written for the custom field and reside in your
templates directory. Make sure that their names are unique.
Linking the Java code and rendering views are the plugin-module descriptors in your
atlassian-plugin.xml. They allow JIRA to recognise what custom fields are available to the system and how to render them.
You can also take a look at the default custom fields that shipped with JIRA here.
Information about setting up a complete plugin development environment for a plugin can be found here.
You can compile the examples below in the same way.
Admin-only editable field
For the first example, we'll construct a custom field that is only be editable by JIRA administrators and appear as a plain text to others. This is a simple customisation of the shipped
TextCFType field and can be customized by changing one template and extending TextCFType in a new class. Step 1. Create a Plugin Skeleton is a good starting point.
First, we need to extend TextCFType. After creating and testing the skeleton by itself, edit MyPlugin.java like so (notice namespace.packagename.MyPlugin is this example's namespace and class name):
Second, we need to add the module to the
A few points:
- key must uniquely identify the module in this plugin file.
- name & description are displayed when creating a new custom field instance
This module definition exactly matches that of a standard text field except for one line.
We are customizing the edit Velocity template so that it displays as a text box for an administrator but appears as uneditable text for others. Source for
edit-jiraadminonlytext.vm is below.
The above template checks if the user is part of group jira-administrators. If they are, display the text box, else display the value only as uneditable text.
There's a few points to note.
- For what variables are available for a custom field you should check out the velocity context guide.
- #controlHeader and #controlFooter provide each custom field with the appropriate label and surrounding HTML table tags. This is required for all edit templates.
- Note: edit-jiraadminonlytext.vm needs to be in in a directory named templates/, in the same directory as atlassian-plugin.xml (which may need to be created if starting from Step 1. Create a Plugin Skeleton).
And that's it. Rebuild the plugin, deploy the JAR, login as an administrator and you should see it in the list of plugins. Once enabled, look for the custom field under 'Administration -> Issue Fields -> Custom Fields -> Add Custom Field.' Once added, log in as a normal user as well to test it out.
Logged in as an admin
Logged in as a non-admin
Last commented user calculated field
The next example deals with a Calculated Custom Field. Calculated don't actually store any values. You often want or need this when you want to search on fields not normally available in JIRA, but the information can be derived. In this case, we want to return the last user who commented on the issue, if they are not an administrator. We only want this field to be visible in the issue navigator and not the edit or view pages.
Coding the Custom Field Type
Before you implement the interface CustomFieldType you should check out the latest javadoc. A useful extension point for calculated custom fields is, unsurprisingly, CalculatedCFType, where only three methods need to be implemented (getStringFromSingularObject, getSingularObjectFromString, and getValueFromIssue). If you also choose to implement SortableCustomField you will need to implement compare() as well.
The key method used to retrieve the value of our custom field is getValueFromIssue.
Note that prior to 3.3, the method had a GenericValue as the issue parameter. If you're developing for those JIRA versions make sure you correct your method signatures.
The return type
Object is also known as the Transport Object. In this instance it is of type
User, but it could be any other type. The Transport type must remain consistent across all methods such as create, update and also the view and edit templates.
Wiring it together
Much like the previous example, we can reuse some of the the templates that ship with JIRA.
We can omit any resource types that we don't require. Thus both the edit and view templates are omitted here. The field should only appear when viewing through the issue navigator (column-view) and XML/RSS views (xml). The view user adds a link to the user details page and displays the full user name.
Fred is the last commenter
View in issue navigator
The last commenter field in itself isn't all that useful. While we can see it in on the issue navigator, we can't search for a particular user who commented it last. Searching in JIRA is handled by
CustomFieldSearchers. Again several pre-configured searchers are available. You must ensure that the Transport Object are compatible between the custom field and the custom field searcher. Thus we can only use the UserPicker searcher since this is the only one that indexes User objects.
This is quite similar to the CustomFieldType definition. The tag valid-customfield-type is used to associate the searcher to any number of custom field types.
Package refers to the atlassian-plugin key attribute at the top of a plug-in and and the
key refers to the module/customfield key.
Now when you create/edit your Last User Commented custom field, you'll be able to select the User Picker as a search template. You can now search on the last commenter field in the issue issue navigator.
Important When you change a search template for a custom field, you may need to perform a reindex before the search will work correctly. This issue is being tracked at JRA-4641.
Sorting in Issue Navigator
To enable sorting you simply need to implement the interface
The interface simply extends Comparable, so you need to implement the compare method.
The BestNameComparator is a simple helper type to facilitate comparing two users. You could just as easily write your own custom compare method.
Amazon search plugin
Lastly, a frivolous plug-in to give you some ideas on how to implement custom fields that perform remote look ups. Basically, we want a custom field that will take a text string and display a results from a search through the Amazon. There are several approaches to this, but by simplest solution is to treat the stored value as a simple text field and then add a viewHelper object that effectively transforms the string into the desired result.
Coding and Attaching the view helper
First we need to code our Amazon view helper. You can take a look in the source, but how it's been implemented isn't all that relevant. Once we have the view helper, we can pass this helper to the Velocity templates through the method getVelocityParameters
AmazonSearchViewHelper is now accessible the velocity template. It has the method
searchForBooks which returns a list of Books given some key words. We simply invoke this helper method in the template and display the results in a table.
You can utilise this same idea to display data from other remote systems, or even combine it with the readonly field to create your very own remote custom field.
Confluence Page Link custom field
The 'Confluence Page Link' custom field plugin provides an example of implementing a custom field that performs a remote look up through XML/RPC..
This custom field provides a pop-up searcher - allowing the user to enter a search query that is executed over publicly accessible pages within a specified Confleunce instance. The user can select a result and the URL of thatpage is stored in the custom field - a simple text field. The Confluence instance to search against is specified in a properties file.
A new webwork action 'ConfluencePageBrowserAction' is required - allowing the popup window view to be associated with the action that performs and returns results from the Confluence page search.
The webwork action is registered in the atlassian-plugin.xml file as follows:
The ConfluencePageBrowserAction class is where the search logic is coded:
The Confluence page browser template displays the search query text box and the results:
The popup appears as follows: