Custom Sidebars

How to write your own sidebar plugin
Custom sidebar plugins are enabling developers to add custom UI extensions to the sidebar of a single content item or a list of content items.
Technically speaking a UI editor lives in a sandboxed iframe, which interacts with the web application through a small SDK using messaging. You cannot directly interact with other elements of the Management UI.
Configure the URL to the sidebar plugin
You can configure the sidebar plugin for each schema individually. Each schema has two URLs, where the first URL points to the sidebar plugin for the content list and the second URL points to the sidebar plugin for single content items. You can only configure one of them or both. Of course you can also point both settings to the same URL.
How to configure the sidebar plugin
Write a sidebar plugin
The following code snippet shows a very simple sidecar 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 new instance of the SquidexPlugin class. This instance is responsible to communicate via the Management UI via messaging:
1.
First it sends a readymessage to the Management UI to tell it that it is available now and ready for communication. It also sends the height of plugin to the Management UI.
2.
When the Management UI receives the readymessage it sends an initmessage back with the context object, that contains information like the name of the api and the user profile. You should subscribe to the initmessage and then initialize your sidebar plugin.
3.
When the sidebar plugin is used for a single content item, the full content item is also send to the plugin and resend, whenever it is changed. You can get the current content item by subscribing with the onContentChanged method. Intermediate updates are not send to the editor, only after you have saved your changes.
4.
Furthermore the plugin 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 automatically. Therefore the plugin has to notify the Management UI whenever the size has been changed.
1
<!DOCTYPE html>
2
<html>
3
​
4
<head>
5
    <meta charset="utf-8">
6
​
7
    <script src="https://cloud.squidex.io/scripts/editor-sdk.js"></script>
8
</head>
9
​
10
<body>
11
    <textarea name="content" id="content"></textarea>
12
    <textarea name="context" id="context"></textarea>
13
​
14
    <script>
15
        var contentElement = document.getElementById('content');
16
        var contextElement = document.getElementById('context');
17
​
18
        // When the field is instantiated it notifies the UI that 
19
        // it has been loaded.
20
        var plugin = new SquidexPlugin();
21
​
22
        // Init is called once with a context that contains 
23
        // the app name, schema name and authentication information.
24
        plugin.onInit(function (context) {
25
            contextElement.innerHTML = JSON.stringify(context, null, 2);
26
        });
27
​
28
        // The content is only available when it is used as a sidebar plugin for single content items.
29
        plugin.onContentChanged(function (content) {
30
            contentElement.innerHTML = JSON.stringify(content, null, 2);
31
        });
32
    </script>
33
</body>
34
​
35
</html>
Copied!
API
The SquidexPlugin class is the entry point to your custom sidebar.
Create a new instance when your plugin is initialized.
Methods
Name
Description
plugin.getContext()
Gets the current context information. More about that later.
plugin.clean()
Cleanup the plugin. Usually it is not needed to call this method.
plugin.onInit(callback)
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.
plugin.onContentChanged(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.
plugin.navigate(url)
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.
Context
The context object contains application information, such as the username and access token.
Example:
1
{
2
  "user": {
3
    "user": {
4
      "id_token": "TOKEN",
5
      "session_state": "TOKEN",
6
      "access_token": "TOKEN", // Access Token
7
      "token_type": "Bearer",  // Access Token Type
8
      "scope": "openid profile email squidex-profile role permissions squidex-api",
9
      "profile": {
10
        "s_hash": "Wn3eHEjfi65aLx-KioJ53g",
11
        "sid": "-S7htcpBlnhNKfBXLhl1rg",
12
        "sub": "5dc32104ebc77a363cca0e0c", // User Id
13
        "auth_time": 1573240790,
14
        "idp": "Google",
15
        "amr": [
16
          "external"
17
        ],
18
        "urn:squidex:name": "USERNAME",
19
        "urn:squidex:picture": "URL",
20
        "urn:squidex:permissions": "squidex.admin.*",
21
        "email": "[email protected]",
22
        "email_verified": false
23
      },
24
      "expires_at": 1573405262
25
    }
26
  },
27
  "apiUrl": "http://localhost:5000/api",
28
  "schemaName:" "my-schema",
29
  "schemaId": "213...",
30
  "appName": "my-app"
31
}
Copied!
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.
Example plugins
Squidex contains a few example plugins that can help you to understand the flow, for example:
​https://cloud.squidex.io/scripts/sidebar-context.html: Demonstrates the structure of the context object by displaying the JSON representation in a text field.
​https://cloud.squidex.io/scripts/sidebar-content.html: Demonstrates the structure of the content object by displaying the JSON representation in a text field.
More examples
Also, we have a more examples that you can use in your apps.
1. Algolia Search
Reference: https://cloud.squidex.io/scripts/sidebar-search.html​
This example demonstrates how to build a custom search for your content using Algolia.
Custom Editors
Preview Content
Last modified 10mo ago
Copy link
Contents
How to write your own sidebar plugin
Configure the URL to the sidebar plugin
Write a sidebar plugin