Rate this page:
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.
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
}
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
}
graphql
syntaxThe following parts of the graphql
syntax are available to define schemas:
Syntax | Description |
---|---|
scalar | Used for simple values or primitives. |
type | Used to describe more complex key/value shapes, similar to an `Object` in javascript. |
enum | Enumeration 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. |
The following scalars can be used in any schema and are provided by the schema package:
Name | Description | Example |
Boolean | Represents true or false . | false |
Date | A javascript Date object. | new Date() |
Function | Represents any javascript function. | function () { } |
Number | Represents 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 () { } |
Promise | A javascript Promise object. | Promise.resolve() |
RegExp | A regexp pattern, that can be used for matching against text. | /foo.+bar/ |
String | The String type represents textual data. | "foo" |
AsyncPanelExtension | The value must be the constant "async-panel". | N/A |
ButtonExtension | The value must be the constant "button". | N/A |
LinkExtension | The value must be the constant "link". | N/A |
ModalExtension | The value must be the constant "modal". | N/A |
PanelExtension | The value must be the constant "panel". | N/A |
SectionExtension | The value must be the constant "section". | N/A |
The following predefined types are provided by the schema package:
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
}
The value must be either the name of the glyph or a functional React component returning an SVG glyph.
1
union IconGlyph = String | Function
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
}
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
}
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: