Plugin SDK > Config screen

Quite often, a plugin needs to offer a set of configuration options to the user who installs it.

DatoCMS offers every plugin a configuration screen and a read-write object that can be used to store such settings. It is a free-form object, with no restrictions in the format. Plugins can store what they want in it, and retrieve its value anytime they need in any hook.

As the configuration parameters are completely arbitrary, it is up to the plugin itself to show the user a form through which they can be changed.

The hook provided for this purpose is called renderConfigScreen, and it will be called by DatoCMS when the user visits the details page of the installed plugin:

Implementing a simple configuration form

To give a very simple example, let's say our plugin wants to provide the end user with a simple boolean flag called debugMode. If this flag is enabled, then the plugin will display a series of debug messages in the console as it works.

The first step is to implement the renderConfigScreen hook, which will simply initialize React by rendering a custom component called ConfigScreen:

import React from 'react';
import ReactDOM from 'react-dom';
import { connect, RenderConfigScreenCtx } from 'datocms-plugin-sdk';
connect({
  renderConfigScreen(ctx: RenderConfigScreenCtx) {
    ReactDOM.render(
      <React.StrictMode>
        <ConfigScreen ctx={ctx} />
      </React.StrictMode>,
      document.getElementById('root'),
    );
  },
});

The hook, in its ctx argument, provides a series of information and methods for interacting with the main application, and for now we'll just pass the whole object to the component, in the form of a React prop:

import { Canvas } from 'datocms-react-ui';
type PropTypes = {
  ctx: RenderConfigScreenCtx;
};
function ConfigScreen({ ctx }: PropTypes) {
  return (
    <Canvas ctx={ctx}>
      Hello from the config screen!
    </Canvas>
  );
}

It is now time to setup our form:

import { Canvas, SwitchField } from 'datocms-react-ui';
// configuration object starts as an empty object
type FreshInstallationParameters = {};
// this is how we want to save our settings
type ValidParameters = { devMode: boolean };
// parameters can be either empty or filled in
type Parameters = FreshInstallationParameters | ValidParameters;
export default function ConfigScreen({ ctx }: PropTypes) {
  const parameters = ctx.plugin.attributes.parameters as Parameters;
  return (
    <Canvas ctx={ctx}>
      <SwitchField
        id="01"
        name="development"
        label="Enable development mode?"
        hint="Log debug information in console"
        value={parameters.devMode}
        onChange={(newValue) => {
          ctx.updatePluginParameters({ devMode: newValue });
          ctx.notice('Settings updated successfully!');
        }}
      />
    </Canvas>
  );
}

The important things to notice are that:

• we can access the currently saved configuration object through ctx.plugin.attributes.parameters

• we can call ctx.updatePluginParameters() to save a new configuration object.

Once saved, settings are always available as ctx.plugin.attributes.parameters in any of the other hooks, so that your plugin can have different behaviours based on them.

Using a form management library

If you have more complex settings, feel free to use one of the many form management libraries available for React to avoid code repetition.

We recommend react-final-form, as it works well and is quite lightweight (~8kb). Here's a more complete example using it:

import { RenderConfigScreenCtx } from 'datocms-plugin-sdk';
import {
  Button,
  Canvas,
  SwitchField,
  TextField,
  Form,
  FieldGroup,
} from 'datocms-react-ui';
import { Form as FormHandler, Field } from 'react-final-form';
type PropTypes = {
  ctx: RenderConfigScreenCtx;
};
type FirstInstallationParameters = {};
type ValidParameters = { devMode: boolean; title: string };
type Parameters = FirstInstallationParameters | ValidParameters;
export default function ConfigScreen({ ctx }: PropTypes) {
  return (
    <Canvas ctx={ctx}>
      <FormHandler<Parameters>
        initialValues={ctx.plugin.attributes.parameters}
        validate={(values) => {
          const errors: Record<string, string> = {};
          if (!values.title) {
            errors.title = 'This field is required!';
          }
          return errors;
        }}
        onSubmit={async (values) => {
          await ctx.updatePluginParameters(values);
          ctx.notice('Settings updated successfully!');
        }}
      >
        {({ handleSubmit, submitting, dirty }) => (
          <Form onSubmit={handleSubmit}>
            <FieldGroup>
              <Field name="title">
                {({ input, meta: { error } }) => (
                  <TextField
                    id="title"
                    label="Title"
                    hint="Title to show"
                    placeholder="Your title"
                    required
                    error={error}
                    {...input}
                  />
                )}
              </Field>
              <Field name="devMode">
                {({ input, meta: { error } }) => (
                  <SwitchField
                    id="devMode"
                    label="Enable development mode?"
                    hint="Log debug information in console"
                    error={error}
                    {...input}
                  />
                )}
              </Field>
            </FieldGroup>
            <Button
              type="submit"
              fullWidth
              buttonSize="l"
              buttonType="primary"
              disabled={submitting || !dirty}
            >
              Save settings
            </Button>
          </Form>
        )}
      </FormHandler>
    </Canvas>
  );
}

This will be the final result:

Function Reference