Registering and using extensions

Extensions can be registered, making it easier to use the same extensions in multiple schemas, supply snippets for common parameters and edit the extension's URL. On this page we'll show you how to register an extension, specify installation parameters, add snippets and add an extension in the schema editor.

Registering extensions

To register an extension, go the development home page and click the extensions icon, or choose "Extensions" from the Development menu.

Note that users must have the developer persona in order to have permission to register and manage extensions.

The extensions section is available on the developer home page
The extensions section is available on the developer home page

A list of your registered extensions will be displayed, or if no extensions have been registered you'll see a message as shown below. Click the "Register extension" button.

The register extension window with no extensions registered on this hub
The register extension window with no extensions registered on this hub

In the registration window, add a label and name. The label is used to identify the extension in the Add extension menu in the schema editor. The name will be used as the value of the "name" field in the ui:extension section of a property that uses the extension.

  "type": "number",
  "ui:extension": {
    "name": "simple-slider",
    ...

Next you need to add the extension URL and a short description that will be used to provide information when adding the extension to a content type or slot schema. The initial height of the frame within which the extension is displayed defaults to 200 pixels, but you can change this value if you wish.

When all this information is added, click "Save" and the extension will be registered on the hub and available to use with the schema editor.

To register an extension you must add a label, name, its URL. You can also add a description.
To register an extension you must add a label, name, its URL. You can also add a description.

Installation parameters

In the installation parameters section you can enter values for API keys and other information that you want to apply to an extension each time it's used and don't want to specify in the schema. This is particularly useful if your extension accesses a 3rd party service that requires authorisation.

Installation params are sent to an extension each time it is used.
Installation params are sent to an extension each time it is used.

Installation params are different to the params that are specified in a schema (and that you usually include in snippets). In the example of a code editor you might want installation params to include display settings that are applied each time the extension is used, while schema params could include settings that vary according to the language.

Adding snippets

Adding one or more snippets makes it easier to add your extension to a property in the schema editor, as well as specifying common initial values for parameters. To add a snippet, click "Add Snippet", add a label and paste the JSON for the snippet into the window.

When you choose a snippet in the schema editor, it is used to add a property that uses the extension to the schema.

For the slider extension we've added two snippets with different values for the params.

Adding snippets makes it easier to add a property that uses this extension to the schema editor
Adding snippets makes it easier to add a property that uses this extension to the schema editor

An example snippet is shown below. Note that the extension name should match the name that the extension was registered with.

{
  "title": "transitiontime",
  "description": "Choose the transition time in seconds",
  "type": "number",
  "ui:extension": {
    "name": "simple-slider",
    "params": {
      "min": 0,
      "max": 10,
      "value": 5
    }
  },
  "minimum": 0,
  "maximum": 10
}

When you've finished adding your snippets, save your changes and click the Back button at the top of the window to return to the Extensions window. The extension you just added will be shown in the list.

To edit an existing extension, double-click its name in the list or choose "View" from its contextual menu.

The extensions window showing the slider extension that has just been registered.
The extensions window showing the slider extension that has just been registered.

Adding an extension in the schema editor

There are two ways of adding a registered extension to a schema property using the schema editor. The first and easiest approach is to use one of the snippets we set up when we registered the schema.

If you have any extensions with snippets registered on your hub, then an "Add extension" menu is shown in the schema editor. In here you'll find all the snippets for all the extensions you've registered.

For this example we'll choose "Standard params" which will add the snippet shown above.

To add a property that uses an extension, simply choose one of its snippets from the Add extension menu.
To add a property that uses an extension, simply choose one of its snippets from the Add extension menu.

A new property is added to the schema editor, including your chosen snippet. This includes a default property name and the title, description, property type and params from the snippet. A preview of the property is shown in the window on the right hand side and we can see the slider extension set up with the params we provided.

A property that uses the slider extension is added to the schema and a preview of the property is shown.
A property that uses the slider extension is added to the schema and a preview of the property is shown.

Another way of adding an extension to a property is to use the schema editor's auto complete suggestions. If you add the "ui:extension" keyword and then add "name" within this, pressing control-space will bring up a list of registered extensions from which to choose. In the example shown below we're adding the slider.

You can also choose from the list of registered extensions by using the suggestions feature in the schema editor.
You can also choose from the list of registered extensions by using the suggestions feature in the schema editor.

If you wanted to specify params you'd need to add them to the properties as shown below.

"transitiontime": {
  "title": "transitiontime",
  "description": "Choose the transition time in seconds",
  "type": "number",
  "ui:extension": {
    "name": "simple-slider",
    "params": {
    "min": 0,
    "max": 10,
    "value": 5
        }
    },
  "minimum": 0,
  "maximum": 10
}

Extensions overview

Sample extension

results matching ""

    No results matching ""