How to write a simple Custom Field?

Well, I have chosen this as the first topic because of the most obvious reason. This is what most of the people will start with. That is one reason why there are lot of customfield plug-ins around! No matter how many are there, you will need a new type. You always do!

Given the context, let me make a huge assumption - You know how to create a skeleton plugin! If not, go to here and do it before you continue!

So we are ready with the Skeleton. And I hope you already know what is atlassian-plugin.xml . Even if you don't, you already have a skeleton and I will tell you what you need for a custom field, I mean for my sample custom field!

For the example, I chose to create a Read Only customfield that stores the last edited user name! It is simple in functionality and enough to explain the basic concepts.

So here we go:

Modify the atlassin-plugin.xml to inclue the customfield module as follows. You will define the custom field class and the related velocity templates here!

<customfield-type key="readonly-user" name="Read Only User CF" class="com.jtricks.ReadOnlyUserCF">      
  <description>Read Only User CF Description</description>      
  <resource type="velocity" name="view" location="templates/com/jtricks/view-readonly-user.vm" />      
  <resource type="velocity" name="column-view" location="templates/com/jtricks/view-readonly-user.vm" />     
  <resource type="velocity" name="xml" location="templates/com/jtricks/view-readonly-user.vm" />     
  <resource type="velocity" name="edit" location="templates/com/jtricks/edit-readonly-user.vm" />
</customfield-type>

The structure is the same for all custom fields. You must have a unique key which is 'readonly-user' in this case.  Class is the most important thing which could be one of the JIRA custom field types. In this case I have chosen to write a class of my own just to explain the concepts. The class 'ReadOnlyUserCF' extends JIRA's TextCFType and will be explained later.

The next important thing is the velocity templates. You can define different or same templates for each functionalities. In this case, I have chosen to use the same for view, column-view and xml. view template is used in the 'View Issue' page, column-view template in 'Issue Navigator' & reports and xml in XML exports. For edit, I have chosen a different template as you can see there.

Let's have a look at the class!

public class ReadOnlyUserCF extends TextCFType{       
    private final JiraAuthenticationContext authContext;  
 
    public ReadOnlyUserCF(CustomFieldValuePersister customFieldValuePersister,  
         StringConverter stringConverter,  GenericConfigManager genericConfigManager,
         JiraAuthenticationContext authContext) {       
     super(customFieldValuePersister, stringConverter, genericConfigManager);     
     this.authContext = authContext;   
    }   
   
    @Override   
    public Map getVelocityParameters(Issue issue, CustomField field, FieldLayoutItem fieldLayoutItem){       
    Map params = super.getVelocityParameters(issue, field, fieldLayoutItem);       
    params.put("currentUser", authContext.getUser().getName());       
    return params;   
    }
}

The class extends TextCFType as our custom field in essence is a text field. You can extend SelectCFType if you are creating a custom select list and so on! The IDE will automatically prompt you to create a constuctor as the super class needs to be injected with the relevant parameters. I have injected an additional parameter 'JiraAuthenticationContext' in the constuctor here as it is required in our plug-in.

Now, you need to populate the velocity context with the variables you need. For that, all you need to do is to override the 'getVelocityParameters' method. This returns you a Map with lots of populated params and you can add additional key-value pairs into it as I have added 'currentUser'

params.put("currentUser", authContext.getUser().getName());

We have now the class ready with an additional parameter added into the velocity context! A list of parameters already in there can be found here.

Note: As you can see, 'authcontext' is already in there and I don't need an extra variable to be put in there as I can retieve the current user in the vm from this variable. I have done this just for the sake of the tutorial!

Now let's move no to the templates. The variables in the context is shared across all the templates. Let us have a look at the edit template.

<input type="text" name="$customField.id" value="$currentUser" id="$customField.id"   class="textfield" readonly="readonly" />

Here the highlighted currentUser is the variable we defined in the context in our class. the text field is marked as readonly as well! $customfield automatically comes from the context and we should kepp it as JIRA uses it to update the value back when you press UPDATE!

Note: $authContext.user.name will give you the same result as $currentUser

That is it for edit template. View templates looks like this:

#if ($value)  $value  #end

That's it! Simply displays the current value of the custom field. More complex things can be added if you want beautification, data conversions etc.

And now, we have our custom field ready!! Package it and deploy it into jira-home/plugins/installed-plugins (WEB-INF/lib if you created plugin-1 version). And see if it works 

If you need searching enabled, you need to tie it up with a JIRA's built in Searcher or one you have written! More of that and more about custom fields plugins be found here. And more on CustomFields here. Njoy!

Finf the full source code below. And feel free to post your comments/feedback!

readonly-cf.zip
File Size:	4 kb
File Type:	zip

Download File

---