Plugin SDK > Config screen

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:

1
import React from 'react';
2
import ReactDOM from 'react-dom';
3
import { connect, RenderConfigScreenCtx } from 'datocms-plugin-sdk';
4

5
connect({
6
  renderConfigScreen(ctx: RenderConfigScreenCtx) {
7
    ReactDOM.render(
8
      <React.StrictMode>
9
        <ConfigScreen ctx={ctx} />
10
      </React.StrictMode>,
11
      document.getElementById('root'),
12
    );
13
  },
14
});

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:

1
import { Canvas } from 'datocms-react-ui';
2

3
type PropTypes = {
4
  ctx: RenderConfigScreenCtx;
5
};
6

7
function ConfigScreen({ ctx }: PropTypes) {
8
  return (
9
    <Canvas ctx={ctx}>
10
      Hello from the config screen!
11
    </Canvas>
12
  );
13
}

Always use the 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.

It is now time to setup our form:

1
import { Canvas, SwitchField } from 'datocms-react-ui';
2

3
// configuration object starts as an empty object
4
type FreshInstallationParameters = {};
5

6
// this is how we want to save our settings
7
type ValidParameters = { devMode: boolean };
8

9
// parameters can be either empty or filled in
10
type Parameters = FreshInstallationParameters | ValidParameters;
11

12
export default function ConfigScreen({ ctx }: PropTypes) {
13
  const parameters = ctx.plugin.attributes.parameters as Parameters;
14

15
  return (
16
    <Canvas ctx={ctx}>
17
      <SwitchField
18
        id="01"
19
        name="development"
20
        label="Enable development mode?"
21
        hint="Log debug information in console"
22
        value={parameters.devMode}
23
        onChange={(newValue) => {
24
          ctx.updatePluginParameters({ devMode: newValue });
25
          ctx.notice('Settings updated successfully!');
26
        }}
27
      />
28
    </Canvas>
29
  );
30
}

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:

1
import { RenderConfigScreenCtx } from 'datocms-plugin-sdk';
2
import {
3
  Button,
4
  Canvas,
5
  SwitchField,
6
  TextField,
7
  Form,
8
  FieldGroup,
9
} from 'datocms-react-ui';
10
import { Form as FormHandler, Field } from 'react-final-form';
11

12
type PropTypes = {
13
  ctx: RenderConfigScreenCtx;
14
};
15

16
type FirstInstallationParameters = {};
17
type ValidParameters = { devMode: boolean; title: string };
18
type Parameters = FirstInstallationParameters | ValidParameters;
19

20
export default function ConfigScreen({ ctx }: PropTypes) {
21
  return (
22
    <Canvas ctx={ctx}>
23
      <FormHandler<Parameters>
24
        initialValues={ctx.plugin.attributes.parameters}
25
        validate={(values) => {
26
          const errors: Record<string, string> = {};
27

28
          if (!values.title) {
29
            errors.title = 'This field is required!';
30
          }
31
          return errors;
32
        }}
33
        onSubmit={async (values) => {
34
          await ctx.updatePluginParameters(values);
35
          ctx.notice('Settings updated successfully!');
36
        }}
37
      >
38
        {({ handleSubmit, submitting, dirty }) => (
39
          <Form onSubmit={handleSubmit}>
40
            <FieldGroup>
41
              <Field name="title">
42
                {({ input, meta: { error } }) => (
43
                  <TextField
44
                    id="title"
45
                    label="Title"
46
                    hint="Title to show"
47
                    placeholder="Your title"
48
                    required
49
                    error={error}
50
                    {...input}
51
                  />
52
                )}
53
              </Field>
54
              <Field name="devMode">
55
                {({ input, meta: { error } }) => (
56
                  <SwitchField
57
                    id="devMode"
58
                    label="Enable development mode?"
59
                    hint="Log debug information in console"
60
                    error={error}
61
                    {...input}
62
                  />
63
                )}
64
              </Field>
65
            </FieldGroup>
66
            <Button
67
              type="submit"
68
              fullWidth
69
              buttonSize="l"
70
              buttonType="primary"
71
              disabled={submitting || !dirty}
72
            >
73
              Save settings
74
            </Button>
75
          </Form>
76
        )}
77
      </FormHandler>
78
    </Canvas>
79
  );
80
}

This will be the final result:

`renderConfigScreen(ctx)`

This function will be called when the plugin needs to render the plugin's configuration form.

Context object

The following properties and methods are available in the ctx argument:

Every hook available in the Plugin SDK shares the same minumum set of properties and methods.

Information about the current user using the CMS.

The current DatoCMS user. It can either be the owner or one of the collaborators (regular or SSO).