Rate this page:

Extension Points

This is a guide for CSE version v2.x and upwards.

For the v1.x version, visit the extension point v1 deprecated reference guide.

Extension points allow to consume extensions registered for a given extension point name.

An extension point consist primarily of a schema to define what attributes are supported, and using the provided react hooks and components to get the extensions, share context with their factories, and validate the resulting attributes against the schema.

Schemas

A schema defines the attributes and types expected from an extension to work correctly on a given extension point. They are created using a .graphql file and graphql-style syntax.

At minimum, a schema definition needs to have the name of the extension point and a type named Schema.

schema.cse.graphql

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    """
    Extension type
    """
    type: LinkExtension!

    """
    Label of the link
    """
    label: string!
}

Refer to the schema reference to learn more about schemas.

schema-loader

In order to use schemas, you'll need to install the @atlassian/clientside-extensions-schema webpack loader.

From there, you will be able to import the hooks and components directly from the schema as follow:

schema.cse.graphql

1
2
3
4
5
6
7
8
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    # schema definition
}

extension-point.tsx

1
2
3
import { useExtensions } from './schema.cse.graphql';

// Use the hooks and components resulting from importing the schema as you need

Follow the How to setup CSE schema-loader to learn how to install and configure the loader.

Hooks and Components

CSE provides a set of react hooks and components to consume the extensions registered for a given extension point. These hooks and components will receive an optional context, and validate the resulting attributes against the provided schema.

You can make use of them by importing the schema directly, and the loader will make them available after building the code:

schema.cse.graphql

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    """
    Extension type
    """
    type: LinkExtension!

    """
    Label of the link
    """
    label: string!

    """
    URL of the link
    """
    url: string!
}

extension-point.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import React from "react";
import { useExtensions } from "./schema.cse.graphql";

const ExampleExtensionPoint = ({ context }) => {
    const extensions = useExtensions(context);

    return (
        <>
            {extensions.map(({attributes}) => <a href={attributes.url}>{attributes.label}</a>}
        </>
    )
}

export default ExampleExtensionPoint;

Refer to the hooks and components reference for more details.

Extension Handlers

Client-side Extensions comes with a set of default extension types, each requiring their own API to work correctly.

Some of them are very simple, but others require a large API that can be difficult to provide on your own, so CSE provides default handlers that help you render extensions with Atlaskit components.

Refer to the extension handlers reference to learn how to use them.

Rate this page: