Custom Sidebars
Build and Use Custom Sidebar Extensions to Support your Editorial Workflow
Last updated
Build and Use Custom Sidebar Extensions to Support your Editorial Workflow
Last updated
Custom sidebar plugins enable developers to add custom UI extensions to the sidebar of a single content item, or to a list of content items.
Below is an example of a custom sidebar extension for a search:
Technically speaking, a UI editor lives in a sandboxed iframe
, which interacts with the web application through a small SDK using messaging. The UI editor cannot directly interact with other elements of the Management UI.
You can configure the sidebar plugin for each schema individually. Each schema has two URLs, the first URL named Contents Sidebar Extension (notice Contents as plural) points to the sidebar plugin for the content list. The second URL, named Content Sidebar Extension (notice Content as singular) points to the sidebar plugin for single content items. You can only configure one of them or both. You can point both settings to the same URL.
The following code snippet shows a very simple sidebar plugin. It renders two TextArea elements and displays the current content item and the context as JSON strings.
You create a very simple HTML page and then you reference the editor SDK. In your custom script element, you create a new instance of the SquidexPlugin
class. This instance is responsible for communicating via the Management UI, through messaging:
First it sends a ready
message to the Management UI to state that it is available now and ready for communication. It also sends the height of plugin to the Management UI.
When the Management UI receives the ready
message, it sends an init
message back with the context object which contains information such as the name of the API and the user profile. You should subscribe to the init
message and then initialize your sidebar plugin.
When the sidebar plugin is used for a single content item, the full content item is also sent to the plugin and resent whenever it is changed. You can get the current content item by subscribing using the onContentChanged
method. Intermediate updates are not sent to the editor, they are only sent after you have saved your changes.
The plugin also has a timer running in the background that periodically measures the height of the plugin. The problem is that when you use iframes
, you have to give them a fixed height. You cannot make them resize them, automatically. Therefore the plugin has to notify the Management UI whenever the size changes.
The SquidexPlugin
class is the entry point to your custom sidebar.
Create a new instance when your plugin is initialized.
Name | Description |
---|---|
| Gets the current context information. More about that later. |
| Cleanup the plugin. Usually it is not needed to call this method. |
| Register a function that is invoked when the messaging communication with the management UI is established. After the callback is invoked you get retrieve values with the get methods. The context object will be passed to the callback. |
| Register a function that is invoked whenever the the current content item is changed. This callback is never triggered when your sidebar plugin is used for single content items. |
| Navigates the Management UI to a new URL. Because the plugin is integrated as an iframe, you cannot use normal links as it would only change the URL within the iframe and not the URL of the Management UI. |
The context object contains application information, such as the username and access token.
Example:
You can use apiUrl
, access_token
and token_type
to retrieve additional information from the API, for example when you build a special editor to manage references or assets.
Squidex contains a few sample plugins that can help you to understand the flow, for example:
https://cloud.squidex.io/scripts/sidebar-context.html: This demonstrates the structure of the context object by displaying the JSON representation in a text field.
Here are some more examples that you can use in your Apps.
Reference: https://cloud.squidex.io/scripts/sidebar-search.html
This example demonstrates how to build a custom search for your content using Algolia.