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 plugin, and generate the XML for you.

Supported annotations

NameTypeDescription
@clientside-extension*-Indicates that the next function is a plugin factory to be consumed by the webpack plugin.
@extension-point*stringDefines the location where the plugin will be rendered.
@labelstringDefines a label that's going to be used in the XML declaration of an extension.
@linkstringDefines a URL that's going to be used in the XML declaration of an extension.
@weightnumber

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

Plugins 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.

This conditions are just web-fragment conditions evaluated in the server, and created with Java.

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

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

* required

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 reff.plugins-example-location
 */
export default LinkExtension.pluginFactory(/*...*/);

2. Specify a weight

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

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 * @weight 100
 */
export default LinkExtension.pluginFactory(/*...*/);

3. Specify a label and link

Both @label and @link annotations are particularly useful in scenarios where you need that information to be available for server-side rendered. These annotations will also be converted into attributes when the extension gets rendered on the client.

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

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 * @label "My custom link"
 * @link "http://go.atlassian.com/clientside-extensions"
 */
export default PanelExtension.pluginFactory(/*...*/);

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
import { PanelExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 * @label "My extension"
 * @link "/custom-route?extension=$key"
 */
export default PanelExtension.pluginFactory(/*...*/);

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-fragment 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-webpack-webresouce-plugin.

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

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

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 reff.plugins-example-location
 * @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.pluginFactory(/*...*/);

These @condition annotations will result in creating a condition map object that is matching the shape of conditionMap option from atlassian-webpack-webresouce-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 reff.plugins-example-location
 * @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.pluginFactory(/*...*/);

These @condition annotations will result in creating a condition map object that is matching the shape of conditionMap option from atlassian-webpack-webresouce-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.PerfecCondition",
            "params": [
                {
                    "attributes": {
                        "name": "permission"
                    },
                    "value": "admin"
                }
            ]
        }
    ]
}

Rate this page: