Customize Folder Fields

Overview

Developers can extend the GraphQL schema and the Admin app’s user interface by adding custom fields to Folders. Since our Headless CMS manages Folders, introducing a new field is as simple as defining it on the Folder model.

Once the field is defined in the model, it will automatically appear in the GraphQL schema under the extensions field. Additionally, this new field will be available in the user interface for creating and editing Folders, alongside default fields like title, slug, and parentId.

Custom fields in the GraphQL schema

(click to enlarge)

Custom fields in the Admin app

(click to enlarge)

Add a Field

To add a new field, use the createCmsFolderModelModifier plugin factory, provided by the @webiny/api-headless-cms-aco package.

In this example, we add two fields: carMake and year. You can add as many fields as you like. The field definition is identical to that of the Headless CMS model field, and all the same rules and options apply. To learn more about programmatic model and field definition, visit Define Content Models via Code.

Once the code shown above is applied, you need to deploy your API. Make sure to use the --env value that corresponds to your development environment.

This plugin is specifically designed to add fields to folders related to CMS content models. It includes an optional modelIds property (string[]), allowing you to target specific models.

In GraphQL, this plugin prefixes field IDs with cms_ by default. If the modelIds property is specified, the field ID is prefixed with cms_${modelId}_.

After the deployment is done, your new fields should be visible in the GraphQL schema, and the UI, as demonstrated in the Overview section of this article.

Customizing Field Rendering

To control how and when a specific field is rendered, you can configure a field decorator. Field decorators are higher-order components that let you intercept a component and apply custom logic to its rendering process.

Example: Conditionally Rendering a Field

The following example demonstrates how to create a field decorator that applies a custom renderer to a specific field when a folder is being edited. When the specified conditions are met, the custom renderer is applied to that field.

Understanding the Implementation

• useForm Hook: This hook provides access to the current form inside the New/Edit Folder dialog. By leveraging useForm, you can dynamically control field visibility and behavior based on the form properties.
• ExtensionFieldDecorator: This decorator ensures the field is only rendered when specific conditions are met. In this case, the field is hidden if an existing folder is being edited.
• ContentEntryListConfig: This component acts as a wrapper, enabling access to configuration utilities for the Headless CMS List view. It must be mounted as a parent of other config components to ensure the configurations are applied correctly.

Applying Custom Logic

Using this approach, you can:

• Conditionally display or hide fields based on folder or form properties.
• Swap field renderers dynamically to fit different use cases.
• Implement field-level access control by checking user permissions.

Once you run your Admin app and navigate to the desired Content Model, edit an existing folder to see the custom renderer in action. While this example hides the field, you can extend it to include more advanced field customizations.

Custom renderer is applied to 'carMake' field

(click to enlarge)