In the manualFieldExtensions()
hook, we can pass the configurable: true
option to declare that we want to present a config screen to the user when they're installing the extension on a field:
import { connect , Field , IntentCtx } from 'datocms-plugin-sdk' ;
connect ( {
manualFieldExtensions ( ctx : IntentCtx ) {
return [
{
id : 'starRating' ,
name : 'Star rating' ,
type : 'editor' ,
fieldTypes : [ 'integer' ] ,
configurable : true ,
} ,
] ;
} ,
} ) ;
To continue our example, let's take our "Star rating" editor and say we want to offer end-users the ability, on a per-field basis, to specify the maximum number of stars that can be selected and the color of the stars.
Just like global plugin settings, these per-field configuration parameters are completely arbitrary , so it is up to the plugin itself to show the user a form through which they can be changed.
Don't use form management libraries! Unlike the global config screen, where we manage the form ourselves, here we are "guests" inside the field edit form . That is, the submit button in the modal triggers the saving not only of our settings, but also of all the other field configurations, which we do not control.
The SDK, in this location, provides a set of very simple primitives to integrate with the form managed by the DatoCMS application, including validations. The use of React form management libraries is not suitable in this hook, as most of them are designed to "control" the form.
The hook provided to render the config screen is renderManualFieldExtensionConfigScreen
, and it will be called by DatoCMS when the user adds the extension on a particular field.
Inside the hook we simply initialize React and a custom component called StarRatingConfigScreen
. The argument ctx
provides a series of information and methods for interacting with the main application, and for now all we just pass the whole object to the component, in the form of a React prop:
import React from 'react' ;
import ReactDOM from 'react-dom' ;
import {
connect ,
RenderManualFieldExtensionConfigScreenCtx ,
} from 'datocms-plugin-sdk' ;
connect ( {
renderManualFieldExtensionConfigScreen (
fieldExtensionId : string ,
ctx : RenderManualFieldExtensionConfigScreenCtx ,
) {
ReactDOM . render (
< React . StrictMode >
< StarRatingConfigScreen ctx = { ctx } / >
< / React . StrictMode > ,
document . getElementById ( 'root' ) ,
) ;
} ,
} ) ;
This is how our full component looks like:
import { RenderManualFieldExtensionConfigScreenCtx } from 'datocms-plugin-sdk' ;
import { Canvas , Form , TextField } from 'datocms-react-ui' ;
import { CSSProperties , useCallback , useState } from 'react' ;
type PropTypes = {
ctx : RenderManualFieldExtensionConfigScreenCtx ;
} ;
type Parameters = {
maxRating : number ;
starsColor : NonNullable < CSSProperties [ 'color' ] > ;
} ;
function StarRatingConfigScreen ( { ctx } : PropTypes ) {
const [ formValues , setFormValues ] = useState < Partial < Parameters >> (
ctx . parameters ,
) ;
const update = useCallback ( ( field , value ) => {
const newParameters = { ... formValues , [ field ] : value } ;
setFormValues ( newParameters ) ;
ctx . setParameters ( newParameters ) ;
} , [ formValues , setFormValues , ctx . setParameters ] ) ;
return (
< Canvas ctx = { ctx } >
< Form >
< TextField
id = "maxRating"
name = "maxRating"
label = "Maximum rating"
required
value = { formValues . maxRating }
onChange = { update . bind ( null , 'maxRating' ) }
/ >
< TextField
id = "starsColor"
name = "starsColor"
label = "Stars color"
required
value = { formValues . starsColor }
onChange = { update . bind ( null , 'starsColor' ) }
/ >
< / Form >
< / Canvas >
) ;
}
Here's how it works:
we use ctx.parameters
as the initial value for our internal state formValues
;
as the user changes values for the inputs, we're use ctx.setParameters()
to propagate the change to the main DatoCMS application (as well as updating our internal state).
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.
Enforcing validations on configuration options Users might insert invalid values for the options we present. We can implement another hook called validateManualFieldExtensionParameters
to enforce some validations on them:
const isValidCSSColor = ( strColor : string ) => {
const s = new Option ( ) . style ;
s . color = strColor ;
return s . color !== '' ;
} ;
connect ( {
validateManualFieldExtensionParameters (
fieldExtensionId : string ,
parameters : Record < string , any > ,
) {
const errors : Record < string , string > = { } ;
if (
isNaN ( parseInt ( parameters . maxRating ) ) ||
parameters . maxRating < 2 ||
parameters . maxRating > 10
) {
errors . maxRating = 'Rating must be between 2 and 10!' ;
}
if ( ! parameters . starsColor || ! isValidCSSColor ( parameters . starsColor ) ) {
errors . starsColor = 'Invalid CSS color!' ;
}
return errors ;
} ,
} ) ;
Inside our component, we can access those errors and present them below the input fields:
function StarRatingParametersForm ( { ctx } : PropTypes ) {
const errors = ctx . errors as Partial < Record < string , string >> ;
return (
< Canvas ctx = { ctx } >
< TextField
id = "maxRating"
error = { errors . maxRating }
/ >
< TextField
id = "starsColor"
error = { errors . starsColor }
/ >
< / Canvas >
) ;
}
This is the final result:
Now that we have some settings, we can access them in the renderFieldExtension
hook through the ctx.parameters
object, and use them to configure the star rating component:
import ReactStars from 'react-rating-stars-component' ;
function StarRatingEditor ( { ctx } : PropTypes ) {
return (
< ReactStars
count = { ctx . parameters . maxRating }
activeColor = { ctx . parameters . starsColor }
/ >
) ;
}
manualFieldExtensions
Use this function to declare new field extensions that users will be able
to install manually in some field.
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).
renderManualFieldExtensionConfigScreen
This function will be called when the plugin needs to render the
configuration form for installing a field extension inside a particular
field.
Properties available in context The following information and methods are available:
ctx.account The account that is the project owner.
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.errors The current validation errors for the parameters (you can set them
implementing the validateManualFieldExtensionParameters function).
ctx.fieldExtensionId The ID of the field extension for which we need to render the parameters
form.
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.itemType The model for the field being edited.
ctx.itemTypes All the models of the current DatoCMS project, indexed by ID.
ctx.owner The account that is the project owner.
ctx.parameters The current value of the parameters (you can change the value with the
setParameters function).
ctx.pendingField The field entity that is being edited in the form.
ctx.plugin The current plugin.
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.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.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.setParameters() Sets a new value for the parameters.
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.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.
validateManualFieldExtensionParameters
This function will be called each time the configuration object changes. It
must return an object containing possible validation errors.