Adding a Detail View tab

Overview of the tutorial

In this tutorial, you'll learn how to 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, this module will extend a Jira Software-specific location in the interface.

The 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 app with the Atlassian Plugin SDK.

Our app will add 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 create them in our app as well.

Before you begin

To get the most out of this tutorial, you should know the following:

1. The basics of Java development, such as classes, interfaces, methods, and so on.
2. How to create an Atlassian plugin project using the Atlassian Plugin SDK.
3. How to use and administer Jira Software. 

App source

We encourage you to work through this tutorial. If you want to skip ahead or check your work when you are finished, you can find the app source code on Atlassian Bitbucket.

To clone the repository, run the following command:

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

Step 1. Create the app project

In this step, you will create your app skeleton using the Atlassian Plugin SDK.

1. Set up the Atlassian Plugin SDK and build a project if you did not do that yet.

2. Open a Terminal and navigate to the directory where you would like to keep your project.

3. To create an app skeleton, run the following command:

   1
   2
   atlas-create-jira-plugin
   

4. To identify your app, enter the following information when prompted.

   group-id	com.example.plugins.tutorial.jiraagile
   artifact-id	MyViewTab
   version	1.0-SNAPSHOT
   package	com.example.plugins.tutorial.jiraagile

5. Confirm your entries when prompted.

   The SDK generates the project home directory with project files, such as the POM (that is, Project Object Model definition file), stub source code, and app resources.

6. Navigate to the directory created in the previous step.

7. Delete the test directories.

   Setting up testing for your app isn't part of this tutorial. To delete the generated test skeleton, run the following commands:

   1
   2
   rm -rf ./src/test/java
   rm -rf ./src/test/resources/
   

8. Delete the unneeded Java class files.

   1
   2
   rm -rf ./src/main/java/com/example/plugins/tutorial/jiraagile/*
   

9. Import project in your favorite IDE.

Step 2. Review and tweak the stub code

It's a good idea to familiarize yourself with the project configuration file, known as the POM. 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 need to manually tweak some of the included metadata for your project.

1. Navigate to the project directory created by the SDK and open the pom.xml file.

2. Add your company or organization name and your website URL as the name and url values of the organization element:

   1
   2
   <organization>
       <name>Example Company</name>
       <url>http://www.example.com/</url>
   </organization>
   

3. Update the description element:

   1
   2
   <description>Adds a view tab to JIRA Software boards.</description>
   

4. Save the file.

Step 3. Add the web panel module

In this step, you will use the plugin module generator (that is, another atlas command) to generate the stub code for modules required by the app.

For this tutorial, you will need a Web Panel plugin module. You'll add this using the atlas-create-jira-plugin-module command.

1. In a Terminal window, navigate to the app root folder where the pom.xml is located.

2. Run the following command:

   1
   2
   atlas-create-jira-plugin-module
   

3. Select the Web Panel option.

4. Enter the following information when prompted.

   Plugin Module Name	EinsteinQuotes
   Location	atl.gh.issue.details.tab

5. Select Y for Show Advanced Setup.

6. Accept the defaults for:

   • module key
   • description
   • i18n name key
   • i18n description key
   • weight

7. Select Y for Add resource.

8. To configure the resource, enter the following when prompted.

   Resource Name	view
   Resource Type	velocity
   Location	templates/reference-gh-issue-details-panel-1.vm

9. Select N for Add a resource parameter.

10. Select Y for Add another resource.

11. Enter the following parameters for the resource when prompted.

    Resource Name	icon
    Resource Type	download
    Location	images/lightbulb.png

12. Select N for Add a resource parameter.

13. Select N for Add another resource.

14. Select Y for Add a Velocity context parameter. 

15. Accept the default for the fully qualified context provider class that should be something like this:
    com.example.plugins.tutorial.jiraagile.web.contextproviders.MyContextProvider

16. Select N for Add Conditions prompt.

17. Select N for Add another plugin module.

The SDK generates the module artifacts, indicating the new items in the output.

Step 4. Make adjustments to the generated module

The SDK got you started with your web panel module, but it left you a few things to do.

1. Navigate to src/main/resources/ and open the atlassian-plugin.xml file.

2. Add a few more child elements to the web-panel that you just added:

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

Step 5. Add project resources

1. Copy this image to the src/main/resource/images directory.

This will be the icon for the tab in the issue view.

Note that any icons that you create for your own custom tabs should be of a similar size, about 14 × 14 pixels.

Step 6. Create the Velocity template

In this step, you will create the Velocity template that produces custom view tab content.

1. Navigate to src/main/resources and create a directory folder.

2. In the new directory folder, create a file named reference-gh-issue-details-panel-1.vm.

3. Add the following content to the file:

   1
   2
   <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

1. In the same resources directory, open the properties file called MyViewTab.properties.

2. Add the following properties:

   1
   2
   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 your tab and the hover text for the icon.

Step 8. Write the Java code

If you remember, the web-panel module you added to the app descriptor specified a context-provider class. You need to create this class in your project. The class enables the Velocity template to interject its HTML into the Jira application context.

For more information about context-providers for web panels, see the Web Panel plugin module documentation.

1. Navigate to the root directory of your project and create a file named MyContextProvider.java.

2. Add the following content to the file:

   1
   2
   package com.example.plugins.tutorial.jiraagile.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 this 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 called atl.gh.issue.details.tab.count to the number on the tab indicator itself.

3. Save and close the file.

Step 9. Build, install, and run the app

In this step, you will start Jira Software and test the app.

1. Ensure that AMPS is configured to run with Jira Software. If you haven't done this before, see the Configure AMPS to run Jira with additional applications installed page.

2. Make sure you have saved all your code changes to this point.

3. In a Terminal window, navigate to the app root folder where the pom.xml file is located.

4. Run the following command:

   1
   2
   atlas-run
   

   Jira takes a few minutes to start, Terminal output will notify you of a successful build.

5. In a browser window, go to Jira home page. The URL is indicated in the Terminal output, such as localhost:2990/jira.

6. Log in using the default admin/admin credentials.

7. Select a Scrum software development project as the new project to create. Jira Software prompts you to create a project upon first login.

8. Go to the board for the project that you created.

9. Confirm that the Einstein Quotes app appears on the right side of the page, as shown on the image.

Next steps

As a next step, try adding another tab to your app. Notice that your context provider class is already built for adding multiple tabs, so you need to add another Velocity template, icon file, and web-panel module to the app descriptor.