Adding a link item in the pull request overview panel

This tutorial will show how you can add some custom UI elements into the pull request overview. Given an example "personal TODO" plugin, we'll be adding a count of TODOs for a pull request near the JIRA issue and build counts.

The full source for this tutorial is available on Bitbucket as atlassian/bitbucket-example-pull-request-ui-plugin.

Discovering web fragment locations

The first step is to figure out where the available spots are to place your web fragment. This can be done by appending ?web.items&web.panels&web.sections to any URL to display the locations. Visit the Web Fragments documentation for more information.

The one we want for this tutorial is bitbucket.pull-request.related-entities. You'll notice that it accepts Client Web Panels. That means two things:

• As a panel location, it allows you to add arbitrary HTML to the page in that location.
• As a client panel location, it will render your HTML in the user's browser, rather than on the server.

You'll also see that a pull-request object is provided to you to help you do your rendering.

Plugin descriptor - atlassian-plugin.xml

Great, so we know what we're doing! Let's get started then creating a Client Web Panel.

Here is the atlassian-plugin.xml for our panel:

1
<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.name}" plugins-version="2">
2
    <plugin-info>
3
        <description>${project.description}</description>
4
        <version>${project.version}</version>
5
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
6
    </plugin-info>
7
    
8
    <client-resource key="pr-overview-resources" name="Pull Request Overview Resources">
9
        <directory location="/css/" />
10
        <directory location="/js/" />
11
        <directory location="/soy/" />
12
        
13
        <dependency>com.atlassian.auiplugin:ajs</dependency>
14
        <dependency>com.atlassian.bitbucket.server.bitbucket-web-api:pull-request-web-panels</dependency>
15
    </client-resource>
16
 
17
    <client-web-panel name="PR TODOs link" key="pr-overview-todo-panel" location="bitbucket.pull-request.related-entities" weight="2000">
18
        <client-context-provider>MyCompany.TODO.getTODOStats</client-context-provider>
19
        <resource name="view" type="soy" location="com.atlassian.bitbucket.server.bitbucket-example-pull-request-plugin:pr-overview-resources/com.mycompany.todo.prOverviewPanel" />
20
        <dependency>com.atlassian.bitbucket.server.bitbucket-example-pull-request-plugin:pr-overview-resources</dependency>
21
    </client-web-panel>
22
 
23
</atlassian-plugin>
 
 

You might notice some bits like ${project.artifactId} in this file. These are variables that are being populated automatically from values in our pom.xml file so that we can be certain the pom and plugin are in sync. The only variables you need to be concerned with for this tutorial are:

• ${project.groupId} == "com.atlassian.bitbucket.server"
• ${project.artifactId} == "bitbucket-example-pull-request-plugin"

These two are joined to generate the plugin's key - "com.atlassian.bitbucket.server.bitbucket-example-pull-request-plugin"

The plugin elements:

• The <plugin-info /> describes the plugin as a whole.
• The <client-resource /> describes the JS, LESS/CSS, and client-side Soy templates we'll need for our Client Web Panel. This particular resource encapsulates a JS file and a Soy file. You can learn more by checking out the Web Resource Plugin Module.
• The <client-web-panel /> is the most interesting part for us. Let's dissect it.

client-web-panel

<client-web-panel name="PR TODOs link" key="pr-overview-todo-panel" location="bitbucket.pull-request.related-entities" weight="2000">
 
 

This line gives a human name of "PR TODOs link" to our panel, and is known for programmatic purposes as pr-overview-todo-panel. The location attribute specifies where the panel will be placed, and we've set it to the location "bitbucket.pull-request.related-entities" that we found earlier.

<dependency>com.atlassian.bitbucket.server.bitbucket-example-pull-request-plugin:pr-overview-resources</dependency>
 
 

This line says that whenever the pr-overview-todo-panel is shown, also include the resources in our "pr-overview-resources" <client-resource />

<client-context-provider>MyCompany.TODO.getTODOStats</client-context-provider>
 
 

This line references some JavaScript functions that will be used when rendering your web panel. The <client-context-provider/> will transform incoming data into the shape your template needs. This function is defined in a JavaScript file in the <client-resource/> dependency, and we'll look at it later.

<resource name="view" type="soy" location="com.atlassian.bitbucket.server.bitbucket-example-pull-request-plugin:pr-overview-resources/com.mycompany.todo.prOverviewPanel" />
 
 

Every Client Web Panel requires a view template that produces the HTML. Here we specify a <resource /> with the name "view". We specify that our resource is a Soy (Closure Templates) template with type="soy".

Then we provide the location of the Soy template. You can see we're referencing our <client-resource /> element via its fully qualified name (plugin key; colon; module key) in the location property: com.atlassian.bitbucket.server.bitbucket-example-pull-request-plugin:pr-overview-resources. The second half of the location parameter is the name of the Soy template to use within that resource. Let's write that template now.

The Soy template (Closure Template) - pull-request-overview.soy

1
{namespace com.mycompany.todo}
2
 
3
/**
4
 * @param count The count of TODOs in this PR.
5
 */
6
{template .prOverviewPanel}
7
    {call bitbucket.feature.pullRequest.relatedEntitiesWebPanel}
8
        {param linkText: $count == 1 ? 'TODO' : 'TODOs' /}
9
        {param linkHref: '#' /}
10
        {param iconClass: 'todo-icon' /}
11
        {param count: $count /}
12
        {param extraClasses: 'mycompany-todos-link'  /}
13
    {/call}
14
{/template}
 
 

This Soy file defines the prOverviewPanel template in the com.mycompany.todo namespace. This template takes in a single parameter count, and is very simple - it calls a Bitbucket Server template that will create the standard markup for the location we want. Most locations won't have a standard template like this and you will simply generate your own HTML. Read more about Soy at Closure Templates. Your Bitbucket Server version may not always be on the latest version of Closure Templates, so you'll find the most accurate documentation in the Internet Archive.

The JavaScript - pull-request-overview.js

1
(function($) {
2
    // Set up our namespace
3
    window.MyCompany = window.MyCompany || {};
4
    MyCompany.TODO = MyCompany.TODO || {};
5
 
6
    var storage = {
7
        getTODOs : function(pullRequestJson) {
8
            // ...
9
            return [];
10
        },
11
        putTODOs : function(pullRequestJson, todos) {
12
            // put(storageKey(pullRequestJson), JSON.stringify(todos));
13
        }
14
    };
15
 
16
    /**
17
     * The client-condition function takes in the context
18
     * before it is transformed by the client-context-provider.
19
     * If it returns a truthy value, the panel will be displayed.
20
     */
21
    function hasAnyTODOs(context) {
22
        var todos = storage.getTODOs(context['pullRequest']);
23
        return todos.length;
24
    }
25
 
26
    /**
27
     * The client-context-provider function takes in context and transforms
28
     * it to match the shape our template requires.
29
     */
30
    function getTODOStats(context) {
31
        var todos = storage.getTODOs(context['pullRequest']);
32
        return {
33
            count : todos.length
34
        };
35
    }
36
 
37
    /* Expose the client-context-provider function */
38
    MyCompany.TODO.getTODOStats = getTODOStats;
39
 
40
    /* use a live event to handle the link being clicked. */
41
    $(document).on('click', '.mycompany-todos-link', function(e) {
42
        e.preventDefault();
43
 
44
        // open a dialog to show the TODO details.
45
    });
46
}(AJS.$));
 
 

This file defines the implementation for our <client-context-provider/> by creating the globally accessible JavaScript function that we reference in our XML: MyCompany.TODO.getTODOStats.

It also adds a live event listener to the document for any clicks on our ".mycompany-todos-link".

It uses localStorage to hold the user's TODOs.