Plugin SDK > Working with form values

Working with form values

Inside of Sidebar panels and Field extensions you have access to ctx.formValues, which contains the complete internal form state for the record that the current user is editing. With that, you can access its work-in-progress changes, and react to them.

The structure of ctx.formValues is heavily dependent on the fields of its model. In fact, the keys of this object are the model's field IDs:

1
{
2
  "title": "Foo bar",
3
  "cover_image": {
4
    "upload_id": "32943530"
5
    "alt": null,
6
    "title": null,
7
    "focal_point": null,
8
    "custom_data": {},
9
  },
10
  "author": "39832254",
11
  "seo": {
12
    "image": "16229550",
13
    "title": "Hugo",
14
    "description": "With Hugo, you can build amazing static projects",
15
    "twitter_card": "summary"
16
  },
17
}

If you want to change the value of some field, you can use the ctx.setFieldValue method:

await ctx.setFieldValue('title', 'new value');

Most of the field values you'll find are 100% identical to their respective Content Management API formats (see the section "Field type values"), even tough there are a couple of important exceptions we'll cover below.

Localized fields

If a field is localized, the format of ctx.formValues will slightly change, similarly to what happens on the Content Management API (see the section "Localized fields"):

{
  "title": {
    "en": "Foo bar",
    "it": "Antani"
  }
}

In this case, to change the field value in English, you need to pass the complete field path to ctx.setFieldValue:

await ctx.setFieldValue('title.en', 'new value');

Modular Content fields

As you know, modular content fields contain blocks, which are complex structures composed of multiple inner fields. If you inspect the value of a modular content field from ctx.formValues, you'll see something like this:

1
[
2
  {
3
    "itemId": "39830695",
4
    "itemTypeId": "810886",
5
    "social": "twitter",
6
    "url": "https://twitter.com/datocms",
7
  },
8
  {
9
    "itemId": "39830696",
10
    "itemTypeId": "810886",
11
    "social": "linkedin",
12
    "url": "https://www.linkedin.com/company/35537033"
13
  }
14
]

Every block contains the itemId (ID of the block) and itemTypeId (ID of the block model) attributes, while all the other attributes depend on the actual fields of the block model.

You can edit the value of a Modular Content field just like any other field. Following the example above, you could ie. reorder the existing blocks by social using the ctx.setFieldValue method:

const currentValue = ctx.formValues['my_modular_content'];

await ctx.setFieldValue(
  'my_modular_content',
  currentValue.sort((a, b) => a.social.localeCompare(b.social),
);

But you can also remove some blocks:

await ctx.setFieldValue(
  'my_modular_content',
  currentValue.filter(block => block.social !== 'linkedin'),
);

Or even add new blocks to the field:

1
await ctx.setFieldValue(
2
  'my_modular_content',
3
  [
4
    ...currentValue,
5
    {
6
      "itemTypeId": "810886",
7
      "social": "twitter",
8
      "url": "https://twitter.com/datocms",
9
    },
10
  ],
11
);

Pay attention to the missing itemId attribute here: when the record will be eventually saved, a new itemId will be generated by the DatoCMS API.

Avoid creating Editor field extensions for Modular Content fields!

While it's perfectly fine — and as we just saw, quite straightforward — to develop Addon field extensions for Modular Content fields, overriding the regular editor DatoCMS offers for this field type is generally not a good idea, as you'll need to handle the rendering and update of all the fields and blocks it contains. Not an easy task.

Field extensions on block fields

If a Field Extension is installed on a field belonging to a block, nothing really changes. You can get the value of the specific field of the block using ctx.fieldPath:

import get from 'lodash-es/get';

// ctx.fieldPath for a block field will be something
// like "my_modular_content.1.title"
get(ctx.formValues, ctx.fieldPath);

Structured Text fields

If you inspect the value of a Structured Text field from ctx.formValues, you'll see something like this:

1
{
2
  "my_structured_text_field": [
3
    {
4
      "type": "paragraph",
5
      "children": [
6
        {
7
          "text": "Meet "
8
        },
9
        {
10
          "text": "the best way",
11
          "highlight": true
12
        },
13
        {
14
          "text": " to manage content with Hugo"
15
        }
16
      ]
17
    }
18
  ]
19
}

Even with this tiny one-paragraph example, you'll notice that this format is quite different from the dast format that both CMA and CDA offers:

There's no root node: the value is directly an array of root children;
Nodes of type span have no type attribute, the value attribute is called text, and marks are applied as boolean keys directly on the node itself.

To offer a comparison, this would be the dast version of the same content:

1
{
2
  "my_structured_text_field": {
3
    "schema": "dast",
4
    "document": {
5
      "type": "root",
6
      "children": [
7
        {
8
          "type": "paragraph",
9
          "children": [
10
            {
11
              "type": "span",
12
              "value": "Meet "
13
            },
14
            {
15
              "type": "span",
16
              "marks": [
17
                "highlight"
18
              ],
19
              "value": "the best way"
20
            },
21
            {
22
              "type": "span",
23
              "value": " to manage content with Hugo"
24
            }
25
          ]
26
        }
27
      ]
28
    }
29
  }
30
}

Why is that? Because to power Structured Text fields, under the hood, the DatoCMS application uses the (awesome) Slate Editor library. Its internal representation format is somewhat different from dast, and continuously converting back-and-forth from the two formats on every key stroke was infeasible from a performance point of view.

So, how can you overcome this constraint?

If your plugin just needs to read Structured Text fields, without ever changing their value, you can use the slateToDast function exposed by the datocms-structured-text-slate-utils package to convert the internal Slate format into regular dast, and then do your reading on its result:

1
import { slateToDast } from 'datocms-structured-text-slate-utils';
2
import groupBy from 'lodash-es/groupBy';
3

4
const allFieldsByItemTypeId = groupBy(
5
  Object.values(ctx.fields), field => field.relationships.item_type.data.id
6
);
7

8
const dast = slateToDast(
9
  ctx.formValues['my_structured_text_field'],
10
  allFieldsByItemTypeId,
11
);
12

13
// result will be something like:
14
//
15
// {
16
//    schema: 'dast',
17
//    document: { type: 'root', children: [...] },
18
//  }

If you want to read AND write the content of a Structured Text field, then the datocms-structured-text-slate-utils package offers complete Typescript types and type guards for the Slate format, so you know what you can expect to read and write in there.

In this example, we're building a function that removes every link present in the content:

1
import { Node, isLink, isNonTextNode, NonTextNode } from 'datocms-structured-text-slate-utils';
2
import clone from 'clone-deep';
3

4
function visit(
5
  tree: Node | Node[],
6
  callback: (node: Node, index: number, parents: Node[]) => void,
7
) {
8
  const all = (nodes: Node[], parents: Node[]) =>
9
    nodes.forEach((node, index) => one(node, index, parents));
10

11
  const one = (node: Node, index: number, parents: Node[]) => {
12
    if ('children' in node) {
13
      all(node.children, [node, ...parents]);
14
    }
15
    callback(node, index, parents);
16
  };
17

18
  if (Array.isArray(tree)) {
19
    all(tree, []);
20
  } else {
21
    one(tree, 0, []);
22
  }
23
}
24

25
function removeLinks(slateValue: Node[]) {
26
  const value = clone(slateValue);
27

28
  visit(value, (node, index, parents) => {
29
    if (!isNonTextNode(node) || !isLink(node)) {
30
      return;
31
    }
32

33
    const parent = parents[0] as NonTextNode;
34
    parent.children.splice(index, 1, ...node.children);
35
  });
36

37
  return value;
38
}
39

40
ctx.setFieldValue(
41
  'my_structured_text_field',
42
  removeLinks(ctx.formValues['my_structured_text_field'] as Node[]),
43
);

Structured text fields can contain both references to other records via its itemLink and inlineItem nodes, and blocks via its block nodes. The Slate representation for them is similar to the following:

1
[
2
  {
3
    "type": "paragraph",
4
    "children": [
5
      {
6
        "text": "This is a "
7
      },
8
      {
9
        "type": "itemLink",
10
        "item": "78722383",
11
        "itemTypeId": "810907",
12
        "children": [
13
          {
14
            "text": "link to a record"
15
          }
16
        ]
17
      },
18
      {
19
        "text": " and this is an inline record: "
20
      },
21
      {
22
        "type": "inlineItem",
23
        "item": "69045807",
24
        "itemTypeId": "810907",
25
        "children": [{ "text": "" }]
26
      }
27
    ]
28
  },
29
  {
30
    "type": "paragraph",
31
    "children": [
32
      {
33
        "text": "This is a block:"
34
      }
35
    ]
36
  },
37
  {
38
    "type": "block",
39
    "id": "87031498",
40
    "blockModelId": "810933",
41
    "children": [{ "text": "" }],
42
    "title": "Foobar"
43
  }
44
]

As you can see:

Both itemLink and inlineItem nodes have item and itemTypeId attributes that point to the referenced record;
Both inlineItem and block nodes need to have a children attribute always containing an empty span;
Blocks have the blockModelId attribute containing to the ID of the block model and the id attribute with the ID of the block, while all the other attributes depend on the actual fields of the block model itself.

You can create/remove/change these nodes like any other one by keeping their formats correct. In this example, we're adding a new block node at the end of the content:

1
ctx.setFieldValue(
2
  'my_structured_text_field',
3
  [
4
    ...ctx.formValues['my_structured_text_field'],
5
    {
6
      type: 'block',
7
      key: `${new Date().getTime()}`,
8
      blockModelId: '810933',
9
      title: 'Foobar',
10
      children: [{ text: '' }],
11
    },
12
  ]
13
);

Pay attention to the key attribute here: to create new block nodes, you need to fill it with an unique string. When the record will be eventually saved, a new ID will be generated by the DatoCMS API, the id attribute will appear in the node, and the key attribute will be removed.

Avoid creating Editor field extensions for Structured Text fields!

While it's perfectly fine to develop Addon field extensions for Structured Text fields, overriding the regular editor DatoCMS offers for this field type is generally not a good idea, as it requires a lot of effort to re-create a convincing editing experience.

Did this doc help you?

Need help?

Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.