Controlling Entry Editor appearance with editor interfaces
An editor interface represents the look and feel of the Entry Editor in the Web App. They are tightly coupled to a content type and define which widgets are rendered in both content fields and the sidebar.
For example, the following content type describes a typical blog post data structure. It has a title, a body, and a category that can be either "General", "iOS" or "Android".
{
"fields": [
{ "id": "title", "name": "Title", "type": "Symbol" },
{ "id": "body", "name": "Body", "type": "Text" },
{
"id": "category", "name": "Category", "type": "Symbol",
"validations": [{ "in": ["General", "iOS", "Android"] }]
}
]
}
An editor interface could, for example, define that the title
field should be rendered as an input field (the widget ID is singleLine
and it comes from a builtin
widget the Web App provides). It could then define that the body
should be a normal text area (the widget id is multipleLine
), and that the category
should be rendered as a dropdown field (the widget id is dropdown
).
The editor interface would look like this:
{
"controls": [
{
"fieldId": "title",
"widgetNamespace": "builtin",
"widgetId": "singleLine"
},
{
"fieldId": "body",
"widgetNamespace": "builtin",
"widgetId": "multipleLine"
},
{
"fieldId": "category",
"widgetNamespace": "builtin",
"widgetId": "dropdown"
}
]
}
There are sets of compatible builtin
widgets per content type field type:
Widget ID | Applicable field types | Description |
---|---|---|
assetLinkEditor | Asset | Search, attach, and preview an asset. |
assetLinksEditor | Asset (array) | Search, attach, reorder, and preview multiple assets. |
assetGalleryEditor | Asset (array) | Search, attach, reorder, and preview multiple assets in a gallery layout |
boolean | Boolean | Radio buttons with customizable labels. |
datePicker | Date | Select date, time, and timezon. |
entryLinkEditor | Entry | Search and attach another entry. |
entryLinksEditor | Entry (array) | Search and attach multiple entries. |
entryCardEditor | Entry | Search, attach, and preview another entry. |
entryCardsEditor | Entry (array) | Search, attach and preview multiple entries. |
numberEditor | Integer, Number | A simple input for numbers. |
rating | Integer, Number | Uses stars to select a number. |
locationEditor | Location | A map to select or find coordinates from an address. |
objectEditor | Object | A code editor for JSON |
urlEditor | Symbol | A text input that also shows a preview of the given URL. |
slugEditor | Symbol | Automatically generates a slug and validates its uniqueness across entries. |
listInput | Symbol (array) | Text input that splits values on , and stores them as an array. |
checkbox | Symbol (array) | A group of checkboxes. One for each value from the in validation on the content type field |
tagEditor | Symbol (array) | A text input to add a string to the list. Shows the items as tags and allows to remove them. |
multipleLine | Text | A simple <textarea> input |
markdown | Text | A full-fledged markdown editor |
singleLine | Text, Symbol | A simple text input field |
dropdown | Text, Symbol, Integer, Number | A <input type="select"> element. It uses the values from an in validation on the content type field as options. |
radio | Text, Symbol, Integer, Number | A group of radio buttons. One for each value from the in validation on the content type field |
Settings
You can pass custom settings to a control that change the behavior or presentation of a widget.
The entry for a field of type Boolean
, for example, would look like this.
{
"fieldId": "isFeatured",
"widgetNamespace": "builtin",
"widgetId": "boolean",
"settings": {
"helpText": "Feature this post on the homepage?",
"trueLabel": "yes",
"falseLabel": "no",
}
}
If present, the settings
object of a control must be an object. All widgets accept the helpText
setting and use it to render extra information with the widget. Other settings are widget specific.
Widget ID | Setting name | Description |
---|---|---|
boolean | trueLabel |
Shows this text next to the radio button that sets this value to true . Defaults to “Yes”. |
boolean | falseLabel |
Shows this text next to the radio button that sets this value to false . Defaults to “No”. |
rating | stars |
Number of stars to select from. Defaults to 5. |
datePicker | format |
One of “dateonly”, “time”, “timeZ” (default). Specifies whether to show the clock and/or timezone inputs. |
datePicker | ampm |
Specifies which type of clock to use. Must be one of the stringss “12” or “24” (default). |
UI Extensions
Editor interfaces can be used to assign a custom UI Extension to a field. To do so, use the extension
namespace and the ID of your extension as the widget ID:
{
"controls": [
{
"fieldId": "title",
"widgetNamespace": "extension",
"widgetId": "mycustominput",
"settings": {
"devMode": true
}
}
]
}
Definining a control like that will render the custom extension as a field input. Values provided in settings
will be passed as instance parameters to your extension.
Sidebar
By default the Web App renderes a set of predefined widgets (like "Status" or "Preview") in the entry editor sidebar. Using editor interface it's possible to alter the default sidebar, by hiding and rearranging builtin widgets and adding completely custom UI Extensions.
{
"sidebar": [
{
"widgetNamespace": "builtin-sidebar",
"widgetId": "content-preview-widget"
},
{
"widgetNamespace": "extension",
"widgetId": "mycustompublishbutton",
"settings": {
"devMode": true
}
}
]
}
Sidebar items are rendered in exactly the same order as they are defined in the sidebar
property. The sidebar above will render two widgets, first of them being the builtin preview widget and the other one being a custom UI Extension, with a parameter provided.
Builtin sidebar widgets (widgets in the builtin-sidebar
namespace) have the following IDs:
- Status (publish button):
publication-widget
- Entry-level versioning:
versions-widget
- Content preview:
content-preview-widget
- Translations (locale selection):
translation-widget
- Incoming links:
incoming-links-widget
- Online editing users:
users-widget
Next steps
- Learn about customizing the sidebar
- Model relationships between content with links
- Add images to your content
Not what you’re looking for? Try our FAQ.