Custom Sidebar Applications
On May 13th, 2024, Storyblok started gradually rolling out a new design for its Visual Editor. Therefore, the Visual Editor product screenshots depicted in this resource may not match what you encounter in the Storyblok App. For more information and a detailed reference, please consult this FAQ on the new Visual Editor design.
Custom sidebar applications are accessible from the space level and work outside the Visual Editor. Thus, they are well-suited for functionality that needs to be embedded within Storyblok but will not interact with the Visual Editor. Plugins not assisting in content editing should typically be created as custom sidebar applications. One example of a custom sidebar application is the Broken Links Checker, which scans the entire space for broken links:
)
Broken Link Checker App
Section titled Create a Custom Sidebar Application Create a Custom Sidebar Application
To create a custom sidebar application plugin, follow one of the previous guides on Getting Started. At the Partner Portal, go to Extensions {1} and click + New extension {2}. When asked which type, select Sidebar {3}.
)
Create a new extension
When you completed one of the previous guides, Getting Started, and got the starter running, enter one of your spaces and go to Apps {1}. Select your plugin name, for example, My first plugin {2}.
)
Select an installed custom sidebar application
An admin needs to approve the first time the tool is opened.
)
Admin's approval page
That should redirect you back to your plugin:
)
Selected plugin view
Section titled Integrate with the Management API Integrate with the Management API
Server-side code is able to send requests to the Management API. To do this, read the accessToken and spaceId from the http.IncomingMessage:
const { query } = req
const sessionStore = sessionCookieStore(authHandlerParams)({ req, res })
const { accessToken, region, spaceId } = await sessionStore.get(query)
Note that @storyblok/app-extension-auth, which is included in all starters, appends the storyId and spaceId as query parameters whenever a page is loaded (in req.query). These are used to read the accessToken and region from the session store.
Using these values, you can perform requests with the Management API; for example:
new StoryblokClient({
oauthToken: `Bearer ${accessToken}`,
region,
})
.get(`spaces/${spaceId.toString(10)}/stories`, {
sort_by: 'updated_at:desc',
})
All starter projects include a similar example.
Section titled Space level settings Space level settings
There is an Enable settings on space levels toggle {1} in the Extension details {2} at the Partner Portal.
)
Enable settings on space level toggle
This setting is only available for the Custom Sidebar Application and Tool plugin. To retrieve settings inside the Custom Sidebar Application and Tool plugin, use the OAuth credentials for your plugins. You can find them in our OAuth 2.0 API guide for more details about OAuth credentials.
Once your Custom Sidebar Application and Tool plugin have obtained the OAuth credentials, you can send a request to retrieve the settings to the following endpoint.
curl --location 'https://mapi.storyblok.com/v1/spaces/{{space_id}}/app_provisions/{{app_id}}' \
--header 'Authorization: Bearer {{oauth_token}}'
The space level settings are only for non-sensitive data. Credentials such as secrets and passwords should not be stored. If you still want to store them, you must implement your way of storing them in an external database. (i.e. Supabase, etc)
For more details about app_provisions endpoint, please read our Management API documentation.