Client-side Extensions Developer

Client-side Extensions Developer

Extension Factories
Extension API
Extension Points

Rate this page:

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.

In order to use the schemas, it's necessary to install and configure the @atlassian/clientside-extensions-schema webpack loader.

Follow the How to setup CSE schema-loader guide to do so.

Schema definition

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

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

Context schema

Schemas can also used to define the shape of a valid context object to be shared with extensions. They are useful in order to prevent breaking changes caused by unexpected changes in the context provided:

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

type ContextSchema {
    # schema definition
}

Available graphql syntax

The following parts of the graphql syntax are available to define schemas:

SyntaxDescription
scalarUsed for simple values or primitives.
typeUsed to describe more complex key/value shapes, similar to an `Object` in javascript.
enumEnumeration of predefined values.
union Used as an `or` to allow e.g. a key within an input to have multiple possible correct values. A union can consist of `type`, `enum`, `scalars`, or another `union`.
! A `!` behind a type makes it required.
[] Surrounding a type with square brackets (`[]`) means an array of that type is expected.

Provided scalars

The following scalars can be used in any schema and are provided by the schema package:

NameDescriptionExample
BooleanRepresents true or false.false
DateA javascript Date object.new Date()
FunctionRepresents any javascript function.function () { }
NumberRepresents a numeric value. Can be an integer or floating point.3.14
ModalOnAction The value should be a callback function expecting to receive the Modal extension API function () { }
PanelOnAction The value should be a callback function expecting to receive the Panel extension API function () { }
PromiseA javascript Promise object.Promise.resolve()
RegExpA regexp pattern, that can be used for matching against text./foo.+bar/
StringThe String type represents textual data."foo"
AsyncPanelExtensionThe value must be the constant "async-panel".N/A
ButtonExtensionThe value must be the constant "button".N/A
LinkExtensionThe value must be the constant "link".N/A
ModalExtensionThe value must be the constant "modal".N/A
PanelExtensionThe value must be the constant "panel".N/A
SectionExtensionThe value must be the constant "section".N/A

Provided types

The following predefined types are provided by the schema package:

Icon

An Icon object with a glyph that allows to customize its colors and CSS class.

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
type Icon {
    """
    Icon to render
    """
    glyph: IconGlyph!

    """
    Custom CSS class name passed to icon wrapper
    """
    className: String

    """
    String to use as the aria-label for the icon.
    Set to an empty string if you are rendering the icon with visible text to prevent accessibility label duplication.
    """
    label: String

    """
    Primary colour of the icons
    """
    primaryColor: String

    """
    Secondary colour of the two-color icons
    """
    secondaryColor: String
}

IconGlyph

The value must be either the name of the glyph or a functional React component returning an SVG glyph.

1
union IconGlyph = String | Function

Usage notes

1. Schema definition with an icon

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

    """
    Text to render on the button
    """
    label: String

    """
    Callback will be run when user clicks the button
    """
    onAction: Function

    """
    An icon to show on the button if provided
    """
    icon: Icon
}

2. Schema definition that supports modal extensions

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

    """
    Text to render on the button
    """
    label: String

    """
    The value should be a callback function expecting to receive the modal extension API
    """
    onAction: ModalOnAction
}

3. Context schema definition with custom type

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
31
32
"""
---
extensionPoint: example.extension-point
---
"""
type Schema {
    type: LinkExtension!

    label: String
}

"""
It's also possible to define custom types in graphql syntax
"""
type User {
    name: String

    age: Number

    lastLogin: Number

    isAdmin: Boolean
}

type ContextSchema {
    """
    Using custom type to define a property of context
    """
    user: User

    unreadMessages: Number
}

Rate this page: