Widget parameters
Understanding parameters
It's important to achieve separation of the code that forms your custom widget (App, UI Extension) and configuration that is used by it. This way it can be shared, reused and reconfigured without any code changes. Good examples are:
- default values
- project, category or entity identifiers when loading data from external APIs
- Slack channel name to post messages to
- content types to process (e.g. for publishing content trees)
- kinds of validation to apply
- and many more...
There are two types of configuration parameters that can be set up:
- Installation parameters that are set during installation in a space environment and which can be modified in subsequent configuration updates. Their values are available across all usages of the widget in the space environment.
- Instance parameters that are set when a space member with access to the Content Model assigns a widget to a location. Values provided are available only in the specific location and content type where they were entered.
Parameter definition
Parameter definition is an object constructed as described in the table below.
| Property | Type and value | Is required? | Remarks |
|---|---|---|---|
id |
String | yes | Can contain only letters, numbers and underscores |
name |
String | yes | Human readable name of the parameter |
description |
String | no | Further explanation of the purpose of the parameter |
type |
String, one of Symbol, Enum, Number, Boolean |
yes | Enum parameters hold a predefined list of Symbols |
required |
Boolean | no, defaults to false |
Whether the parameter value needs to be provided |
default |
Should match type |
no | Default value to use for the parameter. For Enums it has to be defined on the options list |
options |
|
yes |
|
labels |
|
no | Used for rendering a form. All labels are optional and have sensible defaults in English |
Parameter definition for Apps
For Apps, installation parameters are a free-form object, with a limit of 16kB, and don't have to be defined.
Up to 8 instance paramters can be defined as a part the AppDefinition entity:
{
"name": "My parametrized editor app",
"src": "https://myeditor.contentful.com",
"locations": [{"location": "entry-editor"}],
"parameters": {
"instance": [
{
"id": "helpText",
"type": "Symbol",
"name": "Help text",
"description": "Help text for a user to help them understand the editor"
},
{
"id": "theme",
"type": "Enum",
"name": "Theme",
"options": [{"light": "Solarized light"}, {"dark": "Solarized dark"}],
"default": "light",
"required": true
}
]
}
}Parameter definition for UI Extensions
Up to 8 instance and 8 installation parameters can be defined as a part of the Extension entity:
{
"extension": {
"name": "My parametrized object editor",
"fieldTypes": [{type: "Object"}],
"srcdoc": "<!DOCTYPE html>...",
"parameters": {
"installation": [
{
"id": "devMode",
"type": "Boolean",
"name": "Run in development mode"
},
{
"id": "retries",
"type": "Number",
"name": "Number of retries for API calls",
"required": true,
"default": 3
}
],
"instance": [
{
"id": "helpText",
"type": "Symbol",
"name": "Help text",
"description": "Help text for a user to help them understand the editor"
},
{
"id": "theme",
"type": "Enum",
"name": "Theme",
"options": [{"light": "Solarized light"}, {"dark": "Solarized dark"}],
"default": "light",
"required": true
}
]
}
}
}Setting and reading parameter values
Instance parameters are set in the Editor Interface entity. Installation parameters are provided as a top-level parameters property of the AppInstallation or Extension entities:
{
"parameters": {
"devMode": true,
"retries": 10
}
}Values, for both instance and installation parameters, can be read with the SDK:
init(sdk => {
console.log(sdk.parameters.instance)
console.log(sdk.parameters.installation)
})Note that both instance and installation are guaranteed to be an empty object if values were not provided.