Sorry, no results found for "".

In this page

"Field addon" field extensions

How to hook field extensions to a field

Rendering the field extension

Adding user-defined settings into the mix

Reference Table: Field Types & Internal Names

Side note: ctx updates and React useEffect

Hooks

overrideFieldExtensions()

renderFieldExtension()

Plugin SDK > Field extensions

Field extensions

By creating what we call 'field extensions', plugins can change the way in which the fields of a record are presented to the final editor, going beyond the appearance configurations that DatoCMS offers by default.

There are different types of field extensions that can be created, depending on requirements:

"Field editor" extensions

They operate on top of a particular field, replacing the default field editor that DatoCMS provides with custom code:

The use cases are varied, and many examples are already on our marketplace, ready to be installed on your project:

The Shopify product plugin can be hooked into string fields and completely changes the interface to allow you to browse the products in your Shopify store, then save the ID of the selected product in the string field itself;
The Hidden field plugin simply hides a specific field from the editor's eyes, while the Conditional fields plugin shows/hides a number of fields when you toggle a particular checkbox field.

Field editors as sidebar panels

It is also possible to move editor extensions to the right-hand sidebar, giving it the appearance of a collapsible panel. The difference between this mode and a sidebar panel is that this controls a specific field of the record and can use it as a "storage unit" to save internal information, while a sidebar panel is not associated with any particular field.

As an example, the Sidebar notes plugin uses this mode to turn a JSON field into a kind of notepad where you can add virtual post-it notes.

"Field addon" field extensions

As the name suggests, addons do not change the way a field is edited, but they add functionality, or provide additional information, directly below the field editor. While only one editor can be set up for each field, it is possible to have several addons per field, each providing its own different functionality:

As examples of use, Yandex Translate adds a button below your localisable text/string fields to automatically translate its content from one locale to another, while Sanitize HTML allows you to clean up the HTML code present in a text field according to various preferences.

Two sides of the same coin

Editors and addons are both field extensions, so they have access to exactly the same methods and information. The difference between the two is simply semantics: editors are for editing the field, while addons offer extra functionality.

How to hook field extensions to a field

The SDK provides an overrideFieldExtensions hook that can be implemented to declare the intention to take part in the rendering of any field within the form, either by setting its editor, or by adding some addons, or both.

In this example, we are forcing the use of a custom starRating editor for all integer fields that have an ID of rating:

1
import { connect, Field, FieldIntentCtx } from 'datocms-plugin-sdk';
2

3
connect({
4
  overrideFieldExtensions(field: Field, ctx: FieldIntentCtx) {
5
    if (
6
      field.attributes.field_type === 'integer' &&
7
      field.attributes.api_key === 'rating'
8
    ) {
9
      return {
10
        editor: { id: 'starRating' },
11
      };
12
    }
13
  },
14
});

Similarly, we can also add an addon extension called loremIpsumGenerator below all the text fields:

overrideFieldExtensions(field: Field, ctx: FieldIntentCtx) {
  if (field.attributes.field_type === 'text') {
    return {
      addons: [
        { id: 'loremIpsumGenerator' },
      ],
    };
  }
}

Rendering the field extension

At this point, we need to actually render the field extensions by implementing the renderFieldExtension hook.

Inside of this hook we can implement a simple "router" that will present a different React component depending on the field extension that we've requested to render inside the iframe.

We also make sure to pass down as a prop the second ctx argument, which provides a series of information and methods for interacting with the main application:

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

5
function render(component: React.ReactNode) {
6
  ReactDOM.render(
7
    <React.StrictMode>{component}</React.StrictMode>,
8
    document.getElementById('root'),
9
  );
10
}
11

12
connect({
13
  renderFieldExtension(fieldExtensionId: string, ctx: RenderFieldExtensionCtx) {
14
    switch (fieldExtensionId) {
15
      case 'starRating':
16
        return render(<StarRatingEditor ctx={ctx} />);
17
      case 'loremIpsumGenerator':
18
        return render(<LoremIpsumGenerator ctx={ctx} />);
19
    }
20
  },
21
});

The implementation of the Lorem Ipsum component is pretty straightforward: we simply use the ctx.setFieldValue function to change the value of the field into a randomly generated string:

1
import { Canvas, Button } from 'datocms-react-ui';
2
import { loremIpsum } from 'lorem-ipsum';
3

4
type PropTypes = {
5
  ctx: RenderFieldExtensionCtx;
6
};
7

8
function LoremIpsumGenerator({ ctx }: PropTypes) {
9
  const insertLoremIpsum = () => {
10
    ctx.setFieldValue(ctx.fieldPath, loremIpsum({ format: 'plain' }));
11
  };
12

13
  return (
14
    <Canvas ctx={ctx}>
15
      <Button type="button" onClick={insertLoremIpsum} buttonSize="xxs">
16
        Add lorem ipsum
17
      </Button>
18
    </Canvas>
19
  );
20
}

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.

The Star Rating component is quite similar. We get the current field value from ctx.formValues and the disabled state from ctx.disabled. When the user interacts with the component and changes its value, we call ctx.setFieldValue to propagate the change to the main DatoCMS application:

1
import ReactStars from 'react-rating-stars-component';
2
import get from 'lodash/get';
3
import { Canvas } from 'datocms-react-ui';
4
import { RenderFieldExtensionCtx } from 'datocms-plugin-sdk';
5

6
type PropTypes = {
7
  ctx: RenderFieldExtensionCtx;
8
};
9

10
function StarRatingEditor({ ctx }: PropTypes) {
11
  const currentValue = get(ctx.formValues, ctx.fieldPath);
12
  const handleChange = (newValue: number) => {
13
    ctx.setFieldValue(ctx.fieldPath, newValue);
14
  };
15
  return (
16
    <Canvas ctx={ctx}>
17
      <ReactStars
18
        size={32}
19
        isHalf={false}
20
        edit={!ctx.disabled}
21
        value={currentValue || 0}
22
        onChange={handleChange}
23
      />
24
    </Canvas>
25
  );
26
}

Here's the final result:

Adding user-defined settings into the mix

You might have noticed that our plugin is currently hardcoding some choices, namely:

the rules that decide when to apply both our "star rating" and "lorem ipsum" extensions;
the maximum number of stars to show;
the length of the "lorem ipsum" text we're generating;

If we want, we could make these settings configurable by the user, either by implementing some global plugin settings, or by transforming our field extensions into "manual" extensions.

When to use one strategy or the other is completely up to you, and each has its own advantages/disadvanges.

Manual field extensions are, well, manually hooked by the end-user on each field, and for each installation different configuration options can be specified. Given that our star rating extension will most likely be used in a few specific places rather than in all integer fields of the project, manual fields might be the best choice.
On the other hand, our Lorem Ipsum generator may be convenient in all text fields, so requiring the end user to manually install it everywhere would be unnecessarily tedious. In this case, the choice to force the addon on all fields with the overrideFieldExtensions hook is probably the right one.

In the next section we're going to take a much more detailed look at manual field extensions, and we're going to convert our star rating editor into a manual extension.

Reference Table: Field Types & Internal Names

This table lists the internal names of different DatoCMS field types. It is useful for limiting your field extensions only to specific field types. If you're using TypeScript, you can also get this from the type FieldAttributes['field_type'] exported from our CMA client.

For more details on the different DatoCMS field types, please see the CMA documentation on Fields.

Field Type	Internal Name (for `attributes.field_type`)
Single-line string	`string`
Multi-line text	`text`
Boolean	`boolean`
Integer	`integer`
Float	`float`
Date	`date`
Date & Time	`date_time`
Color	`color`
JSON	`json`
Location	`lat_lon`
SEO and Social	`seo`
Slug	`slug`
External Video	`video`
Single Asset	`file`
Asset Gallery	`gallery`
Single Link (to another record)	`link`
Multiple Links (to other records)	`links`
Modular Content	`rich_text`
Single Block	`single_block`
Structured Text	`structured_text`

Side note: `ctx` updates and React useEffect

This section is only relevant if your plugin has useEffects triggered by context changes.

Because plugins live inside an iframe, record updates may sometimes cause the ctx (context) object to be recreated and passed through the iframe again, triggering a React useEffect unexpectedly even if the values appear the same. This is because useEffect compares objects by reference, not value equality. A re-created ctx object with the same values will still cause React to believe it's changed.

For example, if you update some field values in the CMS (outside your plugin), ctx.formValues will update as expected, because those values are different. However, React will also think ctx.fields has changed, even though its values remain the same.

Generally this shouldn't be a problem, but if you specifically need to make sure a useEffect only runs on actual value changes, we recommend a custom hook like useDeepCompareEffect().

`overrideFieldExtensions(field: Field, ctx)`

Use this function to automatically force one or more field extensions to a particular field.

Return value

The function must return: FieldExtensionOverride | undefined.

Context object

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

This hook exposes additional information and operations specific to the context in which it operates.

Plugin SDK > Field extensions

"Field editor" extensions

Field editors as sidebar panels

"Field addon" field extensions

How to hook field extensions to a field

Rendering the field extension

Adding user-defined settings into the mix

Reference Table: Field Types & Internal Names

Side note: ctx updates and React useEffect

overrideFieldExtensions(field: Field, ctx)

Return value

Context object

renderFieldExtension(fieldExtensionId: string, ctx)

Context object

Side note: `ctx` updates and React useEffect

`overrideFieldExtensions(field: Field, ctx)`

`renderFieldExtension(fieldExtensionId: string, ctx)`