What you'll learn
- field plugin types for UI and API
- which plugins are required and which are optional
This guide should help you understand how to create Headless CMS field plugins and how to use them in the API and the UI. By going through this guide you can see how to create at least two plugins for your field - UI plugin and API plugin. There are extra API field type plugins that can help you with indexing (Elasticsearch) and storage of the field.
Also, in this guide, we assume that you know how Webiny plugins work.
There are a few plugins types that you need to have in mind when creating a new field. For the UI part of the application, there are
CmsEditorFieldRendererPlugin. For the API part of the application, there are
CmsModelFieldToElasticSearchPlugin. It is required only to have
CmsModelFieldToGraphQLPlugin to make the field work.
Plugins of this type are defining the field for the UI part of the application. Here is a simple example of the plugin:
This example adds a
largeText type field to the UI which can be set to accept multiple values.
Plugins of this type are used to render a field in the create or update entry form in the UI side of the application.
A simple example of the renderer meant to render a
largeText type field when set to allow multiple values.
You also must create a renderer for a field type
largeText when not set to allow multiple values.
Plugins of this type define GraphQL part for a field type in the API side of the application. A simple example of the plugin:
Note that there can be differences in management and read definitions. That is because of a case that administration is working with data directly and the user on the read side expects a resolved field.
When you created
CmsModelFieldToGraphQLPlugin plugin types, your field is ready to be used. Just import them in the application.
Plugins of this type define transformations that are run on the field of a type before saving into Elasticsearch. A kinda, simple example of the plugin:
Be aware that you must return top-level entry properties, for example,
rawValues, merged with existing ones. Otherwise, you lose data. You can check the richTextIndexing plugin for more reference.
toIndex method, you can get the original entry (
originalEntry), the one that was prepared for storage (
storageEntry), and the one that is inserted into the Elasticsearch (
toIndexEntry). You should not change them, but you can.
fromIndex method, you always get an entry (
entry) that has possibly been modified by some previous Elasticsearch plugin.
Plugins of this type are like the
CmsModelFieldToElasticSearchPlugin plugin type, they just handle to and from storage transformations.
A simple example to store field as compressed value:
You can check the plugin for storing
string packed with
jsonpack library as another example.