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.

Time estimate:

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.

About these Instructions

You can use any supported combination of OS and IDE to create this plugin. These instructions were written using IntelliJ IDEA on Mac OS X. If you are using another OS or IDE combination, you should use the equivalent operations for your specific environment.

This tutorial was last tested with JIRA 6.0.4. 

Required knowledge

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. 

Plugin source

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:

git clone https://bitbucket.org/atlassian_tutorial/adding-an-issue-view-tab-in-jira-agile.git

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:

  1. If you have not already set up the Atlassian Plugin SDK, do that now: Set up the Atlassian Plugin SDK and Build a Project.
  2. Open a terminal and navigate to the directory where you want to create the project.
  3. Enter the following command to create a plugin skeleton:

    atlas-create-jira-plugin
    
  4. Choose 1 for JIRA 5 when asked which version of JIRA you want to create the plugin for. 
  5. As prompted, enter the following information to identify your plugin:

    group-id

    com.example.plugins.tutorial.jiraagile

    artifact-id

    MyViewTab

    version

    1.0-SNAPSHOT

    package

    com.example.plugins.tutorial. jiraagile

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

  1. Change to the project directory created by the SDK and open the pom.xml file for editing.
  2. Add your company or organisation name and your website as the name and url values of the organization element:

    <organization>
        <name>Example Company</name>
        <url>http://www.example.com/</url>
    </organization>
    
  3. Update the description element:

    <description>Adds a view tab to JIRA Software boards.</description>
    
  4. 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 atlas-create-jira-plugin-module command.

  1. Open a command window and go to the plugin root folder (where the pom.xml is located).
  2. Run atlas-create-jira-plugin-module.

  3. Choose the option labelled Web Panel.
  4. Supply the following information as prompted:

    Plugin Module Name

    EinsteinQuotes

    Location

    atl.gh.issue.details.tab

  5. Choose Y for Show Advanced Setup.
  6. Accept the defaults for the module key, description, i18n name key, i18n description key, and weight.

  7. Enter Y for add resource.

  8. As prompted, configure the resource as follows:

    Resource Name

    view

    Resource Type

    velocity

    Location

    templates/reference-gh-issue-details-panel-1.vm

  9. Enter N when asked if you like to add a resource parameter.
  10. Enter Y when asked if you want to add another resource.

  11. As prompted, enter the following parameters for the resource:

    Resource Name

    iconLightbulb

    Resource Type

    download

    Location

    images/lightbulb.png

  12. Enter N when asked if you want to add a resource parameter and another resource.

  13. Enter Y when asked if you want to add a Velocity context parameter. 
  14. Accept the default for the fully qualified context provider class, which should be something like this:
    com.example.plugins.tutorial.jiraagile.web.contextproviders.MyContextProvider
  15. At the Add Conditions prompt, enter N.

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

  1. Open the plugin descriptor file, src/main/resources/ atlassian-plugin.xml, for editing.
  2. Add a few more child elements to the web-panel you just added:

    <label key="gh.issue.panel.reference" />
    <tooltip key="gh.issue.panel.reference.tooltip" />

Step 5. Add project resources

Copy this image to the src/main/resource/images directory:

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:

  1. Create a directory named templates under src/main/resources.
  2. Add a file to the new directory named reference-gh-issue-details-panel-1.vm with the following content:

    <div class="ghx-container">
        <h4>Einstein Quotes</h4>
        <blockquote>
            The secret to creativity is knowing how to hide your sources.
        </blockquote>
        <blockquote>
            Imagination is more important than knowledge. Knowledge is limited.
        </blockquote>
        <blockquote>
            I am enough of an artist to draw freely upon my imagination.
        </blockquote>
        <blockquote>
            When I examine myself and my methods of thought, I come to the conclusion that the gift of fantasy has meant more to me than any talent for abstract, positive thinking.
        </blockquote>
        <blockquote>
            The true sign of intelligence is not knowledge but imagination.
        </blockquote>
        <blockquote>
            To raise new questions, new possibilities, to regard old problems from a new angle, requires creative imagination and marks real advance in science.
        </blockquote>
        <blockquote>
            True art is characterized by an irresistible urge in the creative artist.
        </blockquote>
        <blockquote>
            The monotony and solitude of a quiet life stimulates the creative mind.
        </blockquote>
        <blockquote>
            It is the supreme art of the teacher to awaken joy in creative expression and knowledge.
        </blockquote>
    </div>

Step 7. Add UI text

Open the properties file in the resources directory, MyViewTab.properties, and add the following properties:

gh.issue.panel.reference=Reference Issue Tab Panel
gh.issue.panel.reference.tooltip=Reference Issue Tab Panel Tooltip

 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.

  1. Create a file named MyContextProvider.java in the source file directory of your project, and add the following content:

    package com.atlassian.tutorial.ghwebpanel.web.contextproviders;
    
    import java.util.Map;
    import com.atlassian.jira.util.collect.MapBuilder;
    import com.atlassian.plugin.PluginParseException;
    import com.atlassian.plugin.web.ContextProvider;
    
    public class MyContextProvider implements ContextProvider
    {
        private Long itemCount = 4L;
        @Override
        public void init(Map<String, String> params) throws PluginParseException
        {
            if (params.containsKey("itemCount"))
            {
                this.itemCount = Long.parseLong(params.get("itemCount"));
            }
        }
        @Override
        public Map<String, Object> getContextMap(Map context)
        {
            return MapBuilder.<String, Object>newBuilder()
                    .add("atl.gh.issue.details.tab.count", itemCount).toMap();
        }
    }

    Notice that our class:

    • Implements the ContextProvider interface.  

    • Overrides the init() and 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.
  2. 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:

  1. Make sure you have saved all your code changes to this point.
  2. Open a terminal window and navigate to the plugin root folder (where the pom.xml file is located).
  3. Run the following command:

    atlas-package
    

    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.

  4. In another console, go to the directory from which you want to run JIRA Software.
  5. 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.
  6. Enter the following command (use a different version if you wish):

    atlas-run-standalone --product jira --version 7.0.0 

    JIRA takes a few minutes to start up.

  7. 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 https://localhost:2009/jira
  8. Log in using the default credentials, admin/admin
  9. Choose an Scrum software development project as the new project to create. JIRA Software prompts you to create a project upon first login.
  10. Once you have created the project, go to the Administration Console by choosing Add-ons from the Administration cog icon. 
  11. Choose Manage Add-ons from the left menu.
  12. Click the Upload add-on link.
  13. Browse to the target directory under your plugin project home. The SDK created this directory when you ran atlas-package.  
  14. 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. 
  15. In JIRA Software, navigate to the board you created.
  16. Confirm that the quotes plugin appears on the right of the page, as shown below.

(tick) Success!

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.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport