Client-side Extensions Developer
Client-side Extensions Developer

Rate this page:

Annotations

The provided webpack plugin uses annotations in comments to gather information about the extension, and generate the XML for you.

Supported annotations

NameTypeDescription
@clientside-extension *-Indicates that the next function is an extension factory to be consumed by the webpack plugin.
@extension-point *stringDefines the location where the extension will be rendered.
@weightnumber

Determines the order in which the extension appears respect to others in the same location.

Extensions are displayed top to bottom or left to right in order of ascending weight.

@conditionstring | Conditions

Defines one or multiple conditions that must be satisfied for the extension to be displayed.

The conditions are evaluated on the server, and created with Java.

If one of the conditions is not met, the code of the extension won't be loaded in the client.

For more information about the conditions please refer to the examples of Web items documentation.

* required

Deprecated annotations

The following annotations should no longer be used

NameTypeDeprecated sincePlanned removal
@labelstring2.03.0
@linkstring2.03.0

Instead of specifying the following as annotations it is recommended to provide these as attributes at runtime:

1
2
3
4
5
6
7
8
9
10
11
12
13
import { LinkExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @weight 100
 */
export default LinkExtension.factory(api => {
    return {
        label: 'My Link-Extension',
        url: '/my-link-extension',
    };
});

Supported PageExtension annotations

The list of additional annotation that can be used with PageExtension. Refer to the PageExtension API to read more details about the supported annotations.

NameTypeDescription
@page-url *string

Defines an url of the web page. The page will be accessible at this url prefixed with /plugins/servlet/<<page-url>>

Example: Using @page-url /labels will register the page at /plugins/servlet/labels URL.

@page-title *stringDefines a title of the web page. The value can be either a raw string or a property key than will be translated.
@page-decoratorstring

A custom page decorator. The default value is atl.general. To read more about page decorators refer to the documentation.

List of built-in decorators supported by all products:

  • atl.admin
  • atl.general
  • atl.popup
  • atl.userprofile
@page-data-providerstring

A page data provider Java class. Page data providers can be used to provide a custom set of a server-side data into your browser page extension.

To read more about the page data providers check the usage section.

Example: @page-data-provider com.example.plugin.MyDataProvider

* required for PageExtension

Keywords

NameDescription
$keyWhen present in any annotation, $key will be replaced with the extension key generated by the CSE webpack plugin.

Usage notes

1. Define a client-side extension, and the extension location to be rendered in

1
2
3
4
5
6
7
import { LinkExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 */
export default LinkExtension.factory(/*...*/);

2. Specify a weight

1
2
3
4
5
6
7
8
import { LinkExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @weight 100
 */
export default LinkExtension.factory(/*...*/);

3. Using the page-* annotations

The page-* annotations can be used to create a custom web and render a navigation link in the product UI.

1
2
3
4
5
6
7
8
9
10
/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @page-url /my-admin-page
 * @page-title "My admin page"
 * @page-decorator atl.admin
 */
export default PageExtension.factory(container => {
    container.innerHTML = '<div>Very secure page!</div>';
});

Refer to the PageExtension API to read more details about the supported annotations.

4. Using $key keyword

For those cases where you need to know the value of the extension key and use it in the annotations, you can make use of the $key keyword. CSE webpack plugin will replace it with the actual value of the key that the plugin generates for your extension.

1
2
3
4
5
6
7
8
9
10
11
import { PageExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @page-url /my-admin-page?q=$key
 * @page-title "My admin page"
 */
export default PageExtension.factory(container => {
    container.innerHTML = '<div>Very secure page!</div>';
});

5. Define a condition

The @condition annotation allows you to define one or multiple conditions that must be satisfied for the extension to be displayed. These conditions are a web-resource conditions evaluated in the server, and created with Java.

For more information about the condition's usage please refer to the examples of Web items documentation and check the documentation of conditionMap option from atlassian-webresource-webpack-plugin.

1
2
3
4
5
6
7
8
import { LinkExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @condition class com.atlassian.cse.demo.RandomCondition
 */
export default LinkExtension.factory(/*...*/);

6. Define a condition with parameters

To add parameters to the conditions you can use multiple @condition annotations. These parameters will be passed in to the condition's init() method as a map of string key/value pairs.

The first part of @condition annotation is a property path, and the second part is the property value.

1
2
3
4
5
6
7
8
9
10
11
12
import { LinkExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @condition class com.atlassian.cse.demo.RandomCondition
 * @condition params.0.attributes.name permission
 * @condition params.0.value admin
 * @condition params.1.attributes.name location
 * @condition params.1.value menu
 */
export default LinkExtension.factory(/*...*/);

These @condition annotations will result in creating a condition map object that is matching the shape of conditionMap option from atlassian-webresource-webpack-plugin:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
    "class": "com.atlassian.cse.demo.RandomCondition",
    "params": [
        {
            "attributes": {
                "name": "permission"
            },
            "value": "admin"
        },
        {
            "attributes": {
                "name": "location"
            },
            "value": "menu"
        }
    ]
}

7. Defining multiple conditions

You can make use of AND / OR keywords to combine multiple conditions for your extension as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { LinkExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point example.extension.point
 * @condition type AND
 * @condition conditions.0.type OR
 * @condition conditions.0.conditions.0.class com.atlassian.cse.demo.RandomCondition
 * @condition conditions.0.conditions.0.invert true
 * @condition conditions.0.conditions.0.params.0.attributes.name permission
 * @condition conditions.0.conditions.0.params.0.value admin
 * @condition conditions.0.conditions.1.class com.atlassian.cse.demo.SuperCondition
 * @condition conditions.0.conditions.1.invert true
 * @condition conditions.0.conditions.1.params.0.attributes.name permission
 * @condition conditions.0.conditions.1.params.0.value project
 * @condition conditions.1.class com.atlassian.cse.demo.PerfecCondition
 * @condition conditions.1.params.0.attributes.name permission
 * @condition conditions.1.params.0.value admin
 */
export default LinkExtension.factory(/*...*/);

These @condition annotations will result in creating a condition map object that is matching the shape of conditionMap option from atlassian-webresource-webpack-plugin:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
    "type": "AND",
    "conditions": [
        {
            "type": "OR",
            "conditions": [
                {
                    "class": "com.atlassian.cse.demo.RandomCondition",
                    "invert": true,
                    "params": [
                        {
                            "attributes": {
                                "name": "permission"
                            },
                            "value": "admin"
                        }
                    ]
                },
                {
                    "class": "com.atlassian.cse.demo.SuperCondition",
                    "invert": true,
                    "params": [
                        {
                            "attributes": {
                                "name": "permission"
                            },
                            "value": "project"
                        }
                    ]
                }
            ]
        },
        {
            "class": "com.atlassian.cse.demo.PerfectCondition",
            "params": [
                {
                    "attributes": {
                        "name": "permission"
                    },
                    "value": "admin"
                }
            ]
        }
    ]
}

Rate this page: