Web UI APIs

There are a few APIs that allow you to integrate with Bitbucket Data Center's UI in stable and supported ways.

Decorators

Decorators allow you to style your own Servlet HTML output to look and behave like Bitbucket pages. There is more detail available on the Plugin Decorators page, or you can follow a tutorial for decorating the user account or decorating the user profile.

Web Fragments

Web fragments allow you to define content that should be shown on existing Bitbucket Data Center pages. There is more detail available on the Web Fragment and Client Web Fragment pages. Client Web Fragments will be progressively deprecated over time and replaced by Client-side Extensions.

Client-side Extensions

Client-side Extensions is a set of APIs for adding content to the page that will gradually replace Client Web Fragments. You can get started by using the Bitbucket Data Center Client-side Extension template

Web Contexts

You can include your own UI assets (JavaScript, CSS, LESS, Soy, etc) onto any Bitbucket Data Center page by choosing an appropriate context for it. A list of available contexts can be found on the Web Resource Contexts page.

UI Components - JavaScript, Soy, and LESS

Bitbucket Data Center, like all Atlassian products, supports AUI components. These allow you to build UI components that look and behave like the rest of Bitbucket Data Center. Note that the stability of AUI components marked "experimental" is not guaranteed between minor versions of Bitbucket Data Center.

Bitbucket Data Center also exposes some of its own components for you to use.

  • JavaScript API - utilities you can use in your own JavaScript code.
  • Soy API - currently a single template. We will expand this API in future releases.

Note that any unmentioned JS, Soy, or LESS components are not considered stable API and may change in any version. Do not use them if you require your plugin to work across upgrades of Bitbucket Data Center.

Web resources

Bitbucket Data Center exposes a number of web resources as part of its web API. These resources are intended for you to use as a dependency when you require certain functionality provided by Bitbucket Data Center in web resource modules that you create in your app. While there is the possibility that these resources have already been loaded by Bitbucket Data Center, it is best practice to depend on any resources you use explicitly in order to ensure your app continues to function if the dependencies loaded by Bitbucket Data Center change in future.

AMD

If you create your app's JavaScript using AMD, or are going to be consuming any AMD modules from Bitbucket Data Center's JavaScript API or AUI, then you must depend on the AMD module to ensure that Bitbucket Data Center's AMD loader is present on the page.

Dependency
1
2
<dependency>com.atlassian.bitbucket.server.bitbucket-web-api:amd</dependency>

AUI

If you are using AUI in your app then you should depend on the aui module in the Bitbucket Data Center web API in order to ensure that dependencies AUI requires from Bitbucket Data Center are correctly loaded before AUI.

Note that this dependency only includes the AUI core, any modules marked as "Experimental" in the AUI documentation will still need explicit dependencies.

By including the aui and amd dependencies AUI will be available in your JavaScript as an AMD module called aui.

Dependency
1
2
<dependency>com.atlassian.bitbucket.server.bitbucket-web-api:aui</dependency>
Usage in JavaScript

(Note this assumes you have a dependency on the AMD web resource as well as AUI)

1
2
define('my-plugin/module', [
    'aui'
], function (
    AJS // In Bitbucket Data Center we refer to the AUI AMD module as `AJS` (Atlassian JS) for historical reasons.
        // You are not required to do this in your app.
) {
    AJS.$(document).onReady(function () {    
        AJS.messages.generic({
            title: 'Hello, world!',
            body: '<p>This is a great message.</p>'
        });
    });
});

Client-side Soy Templates

If you use your own client-side Soy templates in your app then you need to depend on the client-soy resource in order to ensure that dependencies required by the JavaScript compiled Soy templates are loaded before you call your templates.

Dependency
1
2
<dependency>com.atlassian.bitbucket.server.bitbucket-web-api:client-soy</dependency>

jQuery

If your app uses jQuery then you should depend on the jQuery resource to ensure that it is loaded and available prior to your app's code executing. Currently depending on jQuery will provide jQuery via AMD, however this is an implementation detail and so you should also ensure you include the AMD dependency if your own code is using AMD. The exposed module name is called jquery.

Dependency
1
2
<dependency>com.atlassian.bitbucket.server.bitbucket-web-api:jquery</dependency>
Usage in JavaScript

(Note this assumes you have a dependency on the AMD web resource as well as jQuery)

1
2
define('my-plugin/module', [
    'jquery'
], function (
    $
) {
    $(document).onReady(function () {
        console.log('Hello, world!');
    }
});

Rate this page: