Tutorial - Adding a Detail View Tab
Level of experience:
This is an advanced tutorial. You should have completed at least one intermediate tutorial before working through this tutorial. See the list of tutorials in DAC.
It should take you approximately 1 hour to complete this tutorial.
On this page:
Overview of the tutorial
In this tutorial, you'll use a web panel plugin module to add a custom tab to JIRA Software boards. While the web panels module is common to Atlassian products, our module will extend a JIRA Software-specific location in the interface. This tutorial is intended to show you how to make a customization to JIRA Software, but also to walk you through the development flow for developing a JIRA Software plugin with the Atlassian plugin SDK.
Our plugin adds a tab in the JIRA Software UI similar to the existing ones, such as Details and People tab. Notice that each tab has a heading, icon link on the left, and tab content. We'll need to account for these in our plugin as well.
To get the most out of this tutorial, you should be familiar with:
- The basics of Java development, such as classes, interfaces, methods, and so on.
- How to create an Atlassian plugin project using the Atlassian Plugin SDK.
- How to use and administer JIRA Software.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you have finished, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
Alternatively, you can download the source as a ZIP archive by choosing download here: https://bitbucket.org/atlassian_tutorial/adding-an-issue-view-tab-in-jira-agile
Step 1. Create the plugin project
You can create your project scaffolding using the Atlassian Plugin SDK, as follows:
- If you have not already set up the Atlassian Plugin SDK, do that now: Set up the Atlassian Plugin SDK and Build a Project.
- Open a terminal and navigate to the directory where you want to create the project.
Enter the following command to create a plugin skeleton:
- Choose 1 for JIRA 5 when asked which version of JIRA you want to create the plugin for.
As prompted, enter the following information to identify your plugin:
- Confirm your entries when prompted.
The SDK generates the project home directory with project files, such as the POM (Project Object Model definition file), stub source code, and plugin resources.
Step 2. Review and tweak the generated stub code
It's a good idea to familiarise yourself with the project configuration file, known as the POM (Project Object Model definition file). The POM defines general settings for the project, including project dependencies and build settings.
The SDK generates and maintains the POM on its own, for the most part. However, you do need to tweak some of the included metadata for your project by hand, as follows:
- Change to the project directory created by the SDK and open the
pom.xmlfile for editing.
Add your company or organisation name and your website as the
urlvalues of the
- Save the file.
Step 3. Add the web panel module to the plugin descriptor
Now you will use the plugin module generator (another
atlas command) to generate the stub code for modules needed by the plugin.
For this tutorial, you will need a Web Panel plugin module. You'll add this via the
- Open a command window and go to the plugin root folder (where the
- Choose the option labelled
Supply the following information as prompted:
Plugin Module Name
- Choose Y for Show Advanced Setup.
Accept the defaults for the module key, description, i18n name key, i18n description key, and weight.
Enter Y for add resource.
As prompted, configure the resource as follows:
- Enter N when asked if you like to add a resource parameter.
Enter Y when asked if you want to add another resource.
As prompted, enter the following parameters for the resource:
Enter N when asked if you want to add a resource parameter and another resource.
- Enter Y when asked if you want to add a Velocity context parameter.
- Accept the default for the fully qualified context provider class, which should be something like this:
At the Add Conditions prompt, enter N.
Enter N when asked if you want to add another plugin module.
The SDK generates the module artifacts, indicating the new items in the output.
Step 4. Make a few small adjustments to the generated module
The SDK got us started with our web panel module, but it left us a few things to do. We'll do those next:
- Open the plugin descriptor file,
atlassian-plugin.xml, for editing.
Add a few more child elements to the web-panel you just added:
Step 5. Add project resources
Copy this image to the
This will be the icon for the tab in the issue view.
Any icons you create for your own custom tabs should be a similar size, about 14x14 pixels.
Step 6. Create the Velocity template
Create the Velocity template that produces our custom view tab content:
- Create a
directorynamed templates under
Add a file to the new directory named
reference-gh-issue-details-panel-1.vmwith the following content:
Step 7. Add UI text
Open the properties file in the resources directory,
MyViewTab.properties, and add the following properties:
This text will appear in the UI as the heading text for our tab and the hover text for the icon.
Step 8. Write the Java code
If you recall, the
web-panel module you added to the plugin descriptor specified a
context-provider class. We need to create this class in our project. It enables our Velocity template to interject its HTML into the JIRA application context. For more about
context-providers for web panels, see the Web Panel Plugin Module documentation.
Create a file named
MyContextProvider.javain the source file directory of your project, and add the following content:
Notice that our class:
- Overrides the
getContextMap()methods. The methods can access and add to the context map, which are the context variables available for use in our Velocity templates.
- Sets the value of a well-known variable,
atl.gh.issue.details.tab.count, to the number on the tab indicator itself.
- Save and close the file.
Step 9. Build, install and run the plugin
Now let's start up JIRA Software, and try out the plugin:
- Make sure you have saved all your code changes to this point.
- Open a terminal window and navigate to the plugin root folder (where the
pom.xmlfile is located).
Run the following command:
This command builds your plugin code, which may take a minute or two. When done, you should see informational log printouts in the console, with a "BUILD SUCCESSFUL" message. Now start up JIRA.
- In another console, go to the directory from which you want to run JIRA Software.
- Ensure that AMPS is configured to run JIRA with JIRA Software installed. If you haven't done this before, see Configure AMPS to run JIRA Core with additional applications installed.
Enter the following command (use a different version if you wish):
JIRA takes a few minutes to start up.
- When the console output indicates that JIRA is done starting up, open a browser window and navigate to the URL indicated in the console, such as
- Log in using the default credentials, admin/admin
- Choose an Scrum software development project as the new project to create. JIRA Software prompts you to create a project upon first login.
- Once you have created the project, go to the Administration Console by choosing Add-ons from the Administration cog icon.
- Choose Manage Add-ons from the left menu.
- Click the Upload add-on link.
- Browse to the
targetdirectory under your plugin project home. The SDK created this directory when you ran
- Choose the JAR file in the directory. There should be two, so choose the one that does not have "test" in its file name.
Make sure the plugin installs correctly.
- In JIRA Software, navigate to the board you created.
- Confirm that the quotes plugin appears on the right of the page, as shown below.
Taking it further
Try adding another tab to your plugin. Notice that our context provider class is already built for adding multiple tabs, so you simply need to add another Velocity template, icon file, and web-panel module to the plugin descriptor.