A sidebar panel is nothing more than an iframe, inside of which the plugin developer can render what they prefer, while also having the possibility to:
access a series of information relating to the record that's being edited, the project in which the plugin is installed or the logged-in user;
make calls to DatoCMS to produce various effects and interact with the main application (changing form values, navigating to other pages, triggering notifications, opening modals, etc.);
Implementing a simple sidebar panel Let's say we want to create a sidebar panel that will show a link pointing to the website page related to the record we're editing. The first step is to implement the itemFormSidebarPanels
hook, to declare our intent to add the panel to the sidebar:
import { connect , IntentCtx } from 'datocms-plugin-sdk' ;
connect ( {
itemFormSidebarPanels ( model : ModelBlock , ctx : IntentCtx ) {
return [
{
id : 'goToWebsite' ,
label : 'Go to website' ,
startOpen : true ,
} ,
] ;
} ,
} ) ;
The code above will add a panel to every record in our project... but maybe not every record in DatoCMS has a specific page in the final website, right?
It might be better to add some settings to our plugin to let the final user declare the set of models that have permalinks, and the relative URL structure enforced on the frontend:
itemFormSidebarPanels ( model : ModelBlock , ctx : IntentCtx ) {
const { permalinksByModel } = ctx . plugin . attributes . parameters ;
}
if ( ! permalinksByModel [ model . attributes . api_key ] ) {
return [ ] ;
}
}
Rendering the panel The final step is to actually render the panel itself by implementing the renderItemFormSidebarPanel
hook.
Inside of this hook we initialize React and render a custom component called GoToWebsiteItemFormSidebarPanel
, passing down as a prop the second ctx
argument, which provides a series of information and methods for interacting with the main application:
import React from 'react' ;
import ReactDOM from 'react-dom' ;
import { connect , RenderItemFormSidebarPanelCtx } from 'datocms-plugin-sdk' ;
connect ( {
renderItemFormSidebarPanel (
sidebarPanelId ,
ctx : RenderItemFormSidebarPanelCtx ,
) {
ReactDOM . render (
< React.StrictMode >
< GoToWebsiteItemFormSidebarPanel ctx = { ctx } />
</ React.StrictMode > ,
document . getElementById ( 'root' ) ,
) ;
} ,
} ) ;
A plugin might render different panels, so we can use the sidebarPanelId
argument to know which one we are requested to render, and write a specific React component for each of them.
import { Canvas } from 'datocms-react-ui' ;
type PropTypes = {
ctx : RenderItemFormSidebarPanelCtx ;
} ;
function GoToWebsiteItemFormSidebarPanel ( { ctx } : PropTypes ) {
return (
< Canvas ctx = { ctx } >
Hello from the sidebar !
</ Canvas >
) ;
}
It is important to wrap the content inside the Canvas
component, so that the iframe will continuously auto-adjust its size based on the content we're rendering, and to give our app the look and feel of the DatoCMS web app.
All we need to do now is to actually render the link to the website, reading from ctx.formValues
the slug value and generating the final frontend URL:
import { ButtonLink } from 'datocms-react-ui' ;
function GoToWebsiteItemFormSidebarPanel ( { ctx } : PropTypes ) {
if ( ctx . itemStatus === 'new' ) {
return < div > Please save the record first ! </ div > ;
}
const { permalinksByModel } = ctx . plugin . attributes . parameters ;
const permalinkStructure = permalinksByModel [ ctx . itemType . attributes . api_key ] ;
const url = permalinkStructure . replace ( ':slug' , ctx . formValues . slug ) ;
return (
< Canvas ctx = { ctx } >
< ButtonLink href = { url } fullWidth >
View it on the website !
</ ButtonLink >
</ Canvas >
) ;
}
itemFormSidebarPanels
Use this function to declare new sidebar panels to be shown when the user
edits records of a particular model.
Return value The function must return an array of objects with the following structure:
Show structureProperties available in context The following information and methods are available:
ctx.currentRole The role for the current DatoCMS user.
ctx.currentUser The current DatoCMS user. It can either be the owner or one of the
collaborators (regular or SSO).
ctx.currentUserAccessToken The access token to perform API calls on behalf of the current user. Only
available if currentUserAccessToken additional permission is granted.
ctx.environment The ID of the current environment.
ctx.itemTypes All the models of the current DatoCMS project, indexed by ID.
ctx.plugin The current plugin.
ctx.site The current DatoCMS project.
ctx.ui UI preferences of the current user (right now, only the preferred locale is
available).
renderItemFormSidebarPanel
This function will be called when the plugin needs to render a sidebar
panel (see the itemFormSidebarPanels
function).
Properties available in context The following information and methods are available:
ctx.account The account that is the project owner.
ctx.blocksAnalysis Current number of blocks present in form state.
ctx.currentRole The role for the current DatoCMS user.
ctx.currentUser The current DatoCMS user. It can either be the owner or one of the
collaborators (regular or SSO).
ctx.currentUserAccessToken The access token to perform API calls on behalf of the current user. Only
available if currentUserAccessToken additional permission is granted.
ctx.environment The ID of the current environment.
ctx.fields All the fields currently loaded for the current DatoCMS project, indexed by
ID. It will always contain the current model fields and all the fields of
the blocks it might contain via Modular Content/Structured Text fields. If
some fields you need are not present, use the loadItemTypeFields function
to load them.
ctx.fieldsets All the fieldsets currently loaded for the current DatoCMS project, indexed
by ID. It will always contain the current model fields and all the fields
of the blocks it might contain via Modular Content/Structured Text fields.
If some fields you need are not present, use the loadItemTypeFieldsets
function to load them.
ctx.formValues The complete internal form state.
ctx.isFormDirty Whether the form has some non-persisted changes or not.
ctx.isSubmitting Whether the form is currently submitting itself or not.
ctx.item If an already persisted record is being edited, returns the full record
entity.
ctx.itemStatus The current status of the record being edited.
ctx.itemType The model for the record being edited.
ctx.itemTypes All the models of the current DatoCMS project, indexed by ID.
ctx.locale The currently active locale for the record.
ctx.owner The account that is the project owner.
ctx.parameters The arbitrary parameters of the panel declared in the
itemFormSidebarPanels function.
ctx.plugin The current plugin.
ctx.sidebarPaneId The ID of the sidebar panel that needs to be rendered.
ctx.site The current DatoCMS project.
ctx.ssoUsers All the SSO users currently loaded for the current DatoCMS project, indexed
by ID. It will always contain the current user. If some users you need are
not present, use the loadSsoUsers function to load them.
ctx.theme An object containing the theme colors for the current DatoCMS project.
ctx.ui UI preferences of the current user (right now, only the preferred locale is
available).
ctx.users All the regular users currently loaded for the current DatoCMS project,
indexed by ID. It will always contain the current user. If some users you
need are not present, use the loadUsers function to load them.
Methods available in context The following information and methods are available:
ctx.alert() Triggers an "error" toast displaying the selected message.
ctx.createNewItem() Opens a dialog for creating a new record. It returns a promise resolved
with the newly created record or null if the user closes the dialog
without creating anything.
ctx.customToast() Triggers a custom toast displaying the selected message (and optionally a
CTA).
ctx.disableField() Disables/re-enables a specific field in the form.
ctx.editItem() Opens a dialog for editing an existing record. It returns a promise
resolved with the edited record, or null if the user closes the dialog
without persisting any change.
ctx.editUpload() Opens a dialog for editing a Media Area asset. It returns a promise
resolved with:
The updated asset, if the user persists some changes to the asset itself
null, if the user closes the dialog without persisting any change
An asset structure with an additional deleted property set to true, if
the user deletes the asset.
ctx.editUploadMetadata() Opens a dialog for editing a "single asset" field structure. It returns a
promise resolved with the updated structure, or null if the user closes
the dialog without persisting any change.
ctx.loadFieldsUsingPlugin() Loads all the fields in the project that are currently using the plugin for
one of its manual field extensions.
ctx.loadItemTypeFields() Loads all the fields for a specific model (or block). Fields will be
returned and will also be available in the the fields property.
ctx.loadItemTypeFieldsets() Loads all the fieldsets for a specific model (or block). Fieldsets will be
returned and will also be available in the the fieldsets property.
ctx.loadSsoUsers() Loads all SSO users. Users will be returned and will also be available in
the the ssoUsers property.
ctx.loadUsers() Loads all regular users. Users will be returned and will also be available
in the the users property.
ctx.navigateTo() Moves the user to another URL internal to the backend.
ctx.notice() Triggers a "success" toast displaying the selected message.
ctx.openConfirm() Opens a UI-consistent confirmation dialog. Returns a promise resolved with
the value of the choice made by the user.
ctx.openModal() Opens a custom modal. Returns a promise resolved with what the modal itself
returns calling the resolve() function.
ctx.saveCurrentItem() Triggers a submit form for current record.
ctx.scrollToField() Smoothly navigates to a specific field in the form. If the field is
localized it will switch language tab and then navigate to the chosen
field.
ctx.selectItem() Opens a dialog for selecting one (or multiple) record(s) from a list of
existing records of type itemTypeId. It returns a promise resolved with
the selected record(s), or null if the user closes the dialog without
choosing any record.
ctx.selectUpload() Opens a dialog for selecting one (or multiple) existing asset(s). It
returns a promise resolved with the selected asset(s), or null if the
user closes the dialog without selecting any upload.
ctx.setFieldValue() Changes a specific path of the formValues object.
ctx.startAutoResizer() Listens for DOM changes and automatically calls setHeight when it detects
a change. If you're using datocms-react-ui package, the ``
component already takes care of calling this method for you.
ctx.stopAutoResizer() Stops resizing the iframe automatically.
ctx.toggleField() Hides/shows a specific field in the form.
ctx.updateFieldAppearance() Performs changes in the appearance of a field. You can install/remove a
manual field extension, or tweak their parameters. If multiple changes are
passed, they will be applied sequencially.
Always check ctx.currentRole.meta.finalpermissions.canedit_schema
before calling this, as the user might not have the permission to perform
the operation.
ctx.updateHeight() Triggers a change in the size of the iframe. If you don't explicitely pass
a newHeight it will be automatically calculated using the iframe content
at the moment.
ctx.updatePluginParameters() Updates the plugin parameters.
Always check ctx.currentRole.meta.finalpermissions.canedit_schema
before calling this, as the user might not have the permission to perform
the operation.
We use cookies to enhance the user experience. Do you consent their use in accordance with
our cookie policy ?
I consent I decline