Annotations

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

Supported annotations

* required

Deprecated annotations

The following annotations should no longer be used

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

1
2
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.

* required for PageExtension

Keywords

Usage notes

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

1
2
import { LinkExtension } from '@atlassian/clientside-extensions';

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

2. Specify a weight

1
2
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
/**
 * @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
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 evaluated on the server and are implemented in Java. They are used for determining if the extension should be downloaded and rendered by the client. For compatibility reasons, the condition class needs to implement both com.atlassian.plugin.web.Condition and com.atlassian.webresource.spi.condition.UrlReadingCondition interfaces, and both implementations should yield the same result.

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

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

1
2
public class RandomCondition implements Condition, UrlReadingCondition {
    // Condition implementation
    @Override
    public void init(Map<String, String> map) {
    }

    @Override
    public boolean shouldDisplay(Map<String, Object> map) {
        // ...
    }

    // UrlReadingCondition implementation
    @Override
    public void addToUrl(UrlBuilder urlBuilder) {
        // ...
    }

    /**
     * Needs to be the same result as {@link #shouldDisplay(Map)}
     */
    @Override
    public boolean shouldDisplay(QueryParams queryParams) {
        // ...
    }
}

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
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
{
    "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
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
{
    "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"
                }
            ]
        }
    ]
}