Client-side Extensions Developer

Client-side Extensions Developer

Extension Factories

Rate this page:

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.

Using a callback
A callback function that will receive the previous value of attributes as a parameter, and should return an object with new attributes.

* 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 });
            });
        },
    };
});

Using a callback

The new value of attributes can be computed based on the previous value of attributes. To do that, you can pass a callback function to the updateAttributes. The function will receive the previous set of attributes, and it needs to return a new set of attributes.

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(prevAttributes => ({
            isLoading: false,
            isDisabled: prevAttributes.isDisabled || res.active,
        }));
    });

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

The attributes returned by the callback will get automatically merged with the previous attributes.

Example

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
export default ButtonExtension.factory((extensionAPI, context) => {
    fetchRequest().then(response => {
        extensionAPI.updateAttributes(() => ({
            isDisabled: !response.active,
            isLoading: false,
        }));

        // After calling the `updateAttributes` with a callback the new attributes
        // set will look like this:
        //
        // {
        //   label: 'My Button',
        //   isDisabled: true || false,
        //   isLoading: false,
        //   onAction: () => { ... },
        // }
    });

    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,
    };
});

Rate this page: