Adding a board configuration page

In this tutorial, you will build a board configuration page for your Jira Software Data Center app. We won't go into the details of adding settings to the page, but this tutorial will provide a good starting point if you want your app to have separate configurations per board.

To create this board configuration page, you'll create a new web panel located in jira.agile.board.configuration, and then add code to render the web panel. That's it!

This is what it will look like:

Step 1. Add a web panel with board context parameters

To create a board configuration page:

1. Create a web-panel with the label.

2. Set web-panel location to jira.agile.board.tools. 

3. Reference i18n properties from resource module.

4. Create a Soy template and put a reference in web-resource plugin module.

   The complete look of atlassian-plugin.xml:

   1
   2
   <atlassian-plugin key="${atlassian.plugin.key}" name="${project.name}" plugins-version="2">
       <plugin-info>
           <description>${project.description}</description>
           <version>${project.version}</version>
           <vendor name="${project.organization.name}" url="${project.organization.url}" />
       </plugin-info>
   
       <resource type="i18n" name="i18n" location="custom-board-tool-section"/>
   
       <web-resource key="soy" name="custom-board-tool-section Web Resources">
           <resource type="soy" location="/soy/configuration-board.soy" name="My.addOn.tpl.board.config.myConfigurationPage"/>
           <context>custom-board-tool-section</context>
       </web-resource>
   
       <web-panel key="my-configuration-page" location="jira.agile.board.configuration" weight="1">
           <label key="my.configuration.page.label">My Configuration Page</label>
           <resource type="soy" name="view" location=":soy/My.addOn.tpl.board.config.myConfigurationPage" />
       </web-panel>
   </atlassian-plugin>
   

   For more details about the app descriptor, check the Configuring the app descriptor file page.

5. In custom-board-tool-section.properties that we referenced from descriptor, add the following:

   1
   2
   my.configuration.page.label=My Configuration Page
   

Step 2. Add code to render the web panel

The following example shows how to render the web panel using Soy templates.

The configuration-board.soy file is placed in the src/main/resources/soy/ directory. You could use Velocity templates instead, if you wish.

Note that two context parameters are available in the template for you to use: $board.id and $board.type.

You can see the mentioned parameters in the following example:

1
2
{namespace My.addOn.tpl.board.config}

/**
    Custom configuration page.
    @param board
*/
{template .myConfigurationPage}
    My first config page for board: {$board.id} with type: {$board.type}.
{/template}

Congratulations! You've just built a board configuration page for your Jira Software P2 app.

Next steps

• If you look for somewhere to store configuration information, make use of the board properties.
• Your app can define custom project permissions  or global permissions. This may be useful if you want to limit access to your app's board configuration page.
• Learn about Adding menu items to Jira.
• Learn about Web panel module.