Client-side Extensions Developer

Client-side Extensions Developer

Extension API

About

Top level API to manipulate re-render calls and cleanup for extensions.

updateAttributes()

Updates the specified attributes with a new set of values.

Signature

1
2
3
4
5
type AttributeUpdatePayload = ExtensionAttributes | (previousAttributes: ExtensionAttributes) => ExtensionAttributes;

interface ExtensionAPI {
    updateAttributes: (payload: AttributeUpdatePayload) => void;
}

Arguments

NameTypeDescription
payload*AttributeUpdatePayload

Setting an object
Setting an object with the attributes that want to be changed and their new values.

Setting an callback
Setting a callback to receive the previos attributes as a parameter, and return an object with the atributes that want to be changed and their new values.

* required

Usage

Setting an object

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

import { someOperation } from './some-operation';

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default ButtonExtension.factory((extensionAPI, context) => {
    return {
        label: 'My Button',
        onAction: () => {
            extensionAPI.updateAttributes({ isLoading: true });

            someOperation().then(res => {
                if (!res) {
                    return extensionAPI.updateAttributes({ isLoading: false, isDisabled: true });
                }

                return extensionAPI.updateAttributes({ isLoading: false });
            });
        },
    };
});

Setting a callback

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

import { initialize } from './some-operation';

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default ButtonExtension.factory((extensionAPI, context) => {
    initialize(context).then(res => {
        extensionAPI.updateAttributes(prevAtributes => ({
            isLoading: false,
            isDisabled: prevAtributes.isDisabled || res.active,
        }));
    });

    return {
        label: 'My Button',
        isDisabled: !context || !context.id,
        isLoading: true,
        onAction: () => {
            // ... some action
        },
    };
});

onCleanup()

Allows to execute a clean up callback when the extension is about to be removed from the screen.

Signature

1
2
3
4
5
type ExtensionCleanupCallback = () => void;

interface ExtensionAPI {
    onCleanup: (callback: ExtensionCleanupCallback) => void;
}

Arguments

NameTypeDescription
callback*ExtensionCleanupCallback Callback to be executed before removing the extension from the screen.

* required

Usage

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

import { likeService } from './like-service';

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default ButtonExtension.factory((extensionAPI, context) => {
    const likeSubscription = likeService.getLikes(context).subscribe(res => {
        extensionAPI.updateAttributes({
            isLoading: false,
            label: res.liked ? `Liked by you and ${res.likes} others.` : 'Like this button',
        });
    });

    const likeHandler = () => {
        // handle like...
    };

    extensionAPI.onCleanup(() => {
        likeSubscription.unsubscribe();
    });

    return {
        label: 'Like this button',
        isLoading: true,
        onAction: likeHandler,
    };
});