Extensions
Extensions provide you with a way of customising the content editing experience and including features not found in the standard content editing form. You might want to retrieve data from your product catalogue, include a clickable map of store locations, provide an enhanced rich text editor or add support for controls such as sliders.
Extensions are simple web applications that are used to render a property within the content editing form, replacing the standard rendering for a particular type of control. For example, instead of entering a value in an edit text box, you can provide the user with a slider to choose the value they want. Extensions can be used with both content type and slot type schemas.
To develop an extension you'll use the Dynamic Content Extensions SDK. The SDK is available on GitHub.
On this page we'll cover the key concepts of UI extensions and explain how extensions are used within content type and slot type schemas.
See the registering extensions page for more details of how to register an extension and add snippets to make it easier to add that extension to a property in the schema editor. On the sample extension page we'll walk you through a simple UI extension to implement a slider and introduce some of the key features of the SDK.
On this page
Introducing extensions
We'll expand on each of the features of UI extensions in more detail, but here are some of the key features:
Key features
- Extensions are web apps that are rendered in the content editing form and used with simple and complex property types in content type and slot type schemas.
- Web apps that implement extensions can be hosted anywhere that can serve the web app over https. If the extension cannot be loaded, the standard property type is used instead.
- Extensions can be registered on a hub, so you can register the extension once and use it anywhere. When an extension is registered you specify the extension URL, a name to be used to refer to the extension in a schema, installation parameters (such as API keys) and one or more snippets that makes it easy to add your extension to a property in the schema editor.
- Extensions can be used with any property type and multiple properties in the same schema can use extensions.
- The Dynamic Content extensions SDK is used to develop extensions and supports development in JavaScript and TypeScript, so you can use libraries such as React.
- More information about using the SDK can be found on the sample extension page.
- To ensure a consistent user experience, you should ensure that your extension follows the Extensions Style Guide
Extension example
An example extension is shown in the image below. This is a map extension that allows the user to add a set of markers, useful for a store list, for example.
When you create a content type schema with a property that uses an extension, the extension renders in the form preview, as with the standard control types.
A content editing form for a content item that uses the map extension is shown below. The user would choose what values they want to enter and save the form as normal.
Extensions can also allow the user to add media, content links and content references. In the map control you might want to choose store images to use instead of markers, for example.
If, when the user opens a previously saved content item, the map extensions cannot be loaded, then the markers they saved will be shown as standard controls. A message will be displayed to tell the user that the extension could not be loaded (as highlighted in the image below).
Adding an extension to a schema property
To specify that a property in a content type or slot type schema uses a UI extension, include the ui:extension keyword in the property definition. The transitiontime property shown below is a number that uses an extension that is registered with the name "simple-slider". When Dynamic Content renders this property in the content editing form, the extension will be used to render the property instead of the standard number control.
"transitiontime": {
"title": "Transition time",
"description": "Choose the transition time in seconds",
"type": "number",
"ui:extension": {
"name": "simple-slider",
},
"minimum": 0,
"maximum": 20
}
Specifying the extension URL
If you haven't registered an extension, then rather than referring to the extension by name in the schema, you can use its URL.
"type": "object",
"properties": {
"transitiontime": {
"title": "Transition time",
"description": "Choose the transition time in seconds",
"type": "number",
"ui:extension": {
"url": "https://amp-product.s3-eu-west-1.amazonaws.com/doc-examples/slider/index.html",
"params": {
"min": 0,
"max": 20,
"value": 6
}
},
"minimum": 0,
"maximum": 20
}
}
However, we recommend registering extensions, as explained on the registering extensions page, since it makes them easier to manage and reuse in multiple schemas.
Parameters
In the slider example we're using the params keyword to send three parameters to the extension: min, max and value. If these parameters aren't supplied then the extension will set default values.
"ui:extension": {
"name": "simple-slider",
"params": {
"min": 0,
"max": 20,
"value": 6
}
}
As explained in adding snippets, when you register an extension you can set up snippets that might include different params for each instance of the extension. In the case of the slider we have snippets set up with different min and max values.
See the sample extension page for details of how you can read the params sent from the schema to an extension.
Property types
Extensions can be included in both simple property types, such as string and number, and complex property types, such as arrays. For the slider extension the property type is number and when we update the value it must be a valid for that type.
The map extension is used with an array of markers. Expand the section below to see an example of an array property that uses this extension, in this case registered as "map-extension".
"form": {
"title": "form",
"type": "object",
"ui:extension": {
"name": "map-extension",
"params": {
"theme": "light",
"zoom": 5,
"startPosition": [54, 0]
}
},
"properties": {
"markers": {
"title": "Markers",
"description": "description",
"type": "array",
"items": {
"type": "object",
"properties": {
"position": {
"title": "title",
"description": "description",
"type": "array",
"maxItems": 2,
"minItems": 2,
"defaultValue": [51.505, -0.09],
"items": {
"type": "number"
}
},
"description": {
"title": "title",
"description": "description",
"type": "string",
"maxLength": 100
},
"media": {
"title": "title",
"description": "description",
"allOf": [
{
"$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
}
]
}
}
}
}
}
}
If there is a problem communicating between Dynamic Content and the web app, the default property will be used instead, if it's supported. If the default type is not supported, an error will be displayed. For the simple slider, a standard edit control will be used instead of our custom slider.
Creating and editing content
The extension is rendered in the content editing window and the user can interact with it in the same way as other elements. In this example we are using the slider to set the transition time between a set of images.
In your extension code you need to ensure that when the user saves the content, the next time the content item is opened and your extension is rendered, it reads in the saved value.
The sample slider extension shows how to read a previously saved value and update it when the user changes the value of the property.
What an extension can do
Extensions can be very simple, such as the slider or provide more advanced functionality. Features you can access from within an extension using the features of the SDK include:
- The ability to read parameters specified in the content type schema
- Getting and setting the field values- the data entered by the user in this extension. For a map extension it would be getting and setting a list of location markers, for the slider it would be a single number.
- Allow the user to choose content and media. You can include content and media links, so the user could choose product imagery within your extension, for example.
- Access visualization settings
- Access the full content type schema
- Because the extension is a web app, it can also make calls to 3rd party services, so you could retrieve your own product data, for example.