Extension Factory

About

An extension factory is a set of provided helper utilities to create extensions.

They will set the type of the extensions automatically, and provide type definitions for your attribute provider if you're using TypeScript.

Signature

1
type factory = (api: ExtensionAPI, context: Context<{}>) => ExtensionAttributes;

Parameters

NameTypeDescription
extensionAPIExtensionAPIExtension API that provides methods to render and clean up the extension.
contextobjectAn object with information that products share with extensions to share important information about the screen where they are rendered.

Custom types and attributes

There is a set of default attributes that all products support, but they can also add custom attributes or extension types to extend their UI in custom ways.

Check the documentation of each product's extension point for more details.

A link extension allows to render a link on the screen and navigate to another page when clicked by a user.

Supported attributes

NameTypeDescription
label*stringText to be used as the label of the link.
url*stringDefines where the link should redirect the user to.
isHiddenbooleanIf true, the link won't be rendered. Keep in mind that the code of the factory will still be executed.

* required

Usage

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

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default LinkExtension.factory((extensionAPI, context) => ({
    label: 'Go to DAC',
    url: 'https://developer.atlassian.com/',
}));

Button

A button extension allows to render a button on the screen and execute an action when its clicked by a user.

Supported attributes

NameTypeDescription
label*stringText to be used as the label of the button.
onAction*function

signature: () => void

Method to bind as the click handler of the button.

isDisabledbooleanIf true, sets the button as disabled.
isLoadingbooleanIf true, renders the button in loading state.
isHiddenbooleanIf true, the button won't be rendered. Keep in mind that the code of the factory will still be executed.

* required

Usage

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

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default ButtonExtension.factory((extensionAPI, context) => {
    return {
        label: 'My Button',
        onAction: () => {
            // execute some action when clicked
        },
        // ... set isDisabled or isLoading if needed
    };
});

Panel

A panel extension allows the creation of custom HTML content in a container provided by the plugin system.

Supported attributes

NameTypeDescription
label*stringOptionally rendered by the product to describe the panel content. e.g. it may be the label of a tab in a list of tabs, or the text for a header above the panel HTML.
onAction*function

signature: (panelAPI) => void

Method to be called when the product is ready to render the panel. The plugin system will provide an API with lifecycles to render/clean up any current content into a provided container.

Refer to Panel API documentation for more info.

isHiddenbooleanIf true, the panel won't be rendered. Keep in mind that the code of the factory will still be executed.

* required

Usage

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

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default PanelExtension.factory(() => {
    return {
        label: 'JS Panel',
        onAction: panelApi => {
            panelApi
                .onMount(container => {
                    // use the container to render your content in it
                })
                .onUnmount(container => {
                    // run your clean up code. e.g. stop listening to events, unmount your component from the container.
                });
        },
    };
});

A modal extension renders a button that opens a modal, and allows to specify a custom HTML content to the body of it. It also provides a set of APIs to interact with this modal.

Supported attributes

NameTypeDescription
label*stringText to be used as the label of the link.
onAction*function

signature: (modalAPI) => void

Method to be called when the product is ready to render the Modal. The plugin system will provide an API with methods to modify the title, content and actions of the modal.

Refer to Modal API documentation for more info.

isDisabledbooleanIf true, sets the button that triggers the modal as disabled.
isLoadingbooleanIf true, renders the button that triggers the modal in loading state.
isHiddenbooleanIf true, the button that triggers the modal won't be rendered. Keep in mind that the code of the factory will still be executed.

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

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default ModalExtension.factory((extensionAPI, context) => {
    return {
        label: 'Open Modal',
        onAction(modalAPI) {
            modalAPI.setTitle('A cool modal with JS');

            modalAPI.onMount((container, modalOptions) => {
                // use the container to render your content in it...
                // use the modalOptions to interact with the modal after opened...
            });

            modalAPI.onUnmount(() => {
                // run your cleanup code here...
            });
        },
    };
});