Customizing Content Editor forms

You can customize the Content Editor interface with JSON overrides. This topic shows you how override sections, field sets, and fields.

Section overrides

This section shows how to define static forms, how Jahia applies inheritance to sections, and provides an example of applying section overrides.

Defining static forms in Jahia modules

You can override the static definition of the forms and field sets by adding JSON files in the META-INF/jahia-content-editor-forms folder of your Jahia module, and then in the forms or fieldsets subdirectory. The files should have meaningful names and to ensure consistency between your definitions and your overrides. We recommend replacing the colon (:) between the namespace and the content type with an underscore. For example, the override of the qant:myFields  node type should be named qant_myFields.json.

Here's an example of a JSON static form definition:

{
  "nodeType": "qant:myFields",
  "priority": 1.0,
  "sections": [
    {
      "name": "layout"
    }
  ]
}

With this definition, when you create or edit a node of the type  qant:myFields, a form with a section named layout displays. 

Other examples can be found in our Content Editor test folder.

Checking proper registration of static forms

If you want to check if your form or field set definitions are properly deployed, check the Jahia logs for lines that look like this:

2022-12-12 15:43:48,490: INFO  [StaticDefinitionsRegistry] - Successfully loaded static fieldSets for name jmix:description from bundle://132.0:0/META-INF/jahia-content-editor-forms/fieldsets/jmix_description_move_section.json
2022-12-12 15:43:48,501: INFO  [StaticDefinitionsRegistry] - Successfully loaded static form for name jnt:category from bundle://138.0:0/META-INF/jahia-content-editor-forms/forms/jnt_category.json

Checking form generation

It can be helpful to know how to query a form generation to validate it is generated as expected. This can be done using the GraphQL API directly with the following query:

{
  forms {
    editForm(
      uiLocale: "en"
      locale: "en"
      uuidOrPath: "/sites/digitall/home/area-main"
    ) {
      sections {
        name
        displayName
        fieldSets {
          name
          displayName
          fields {
            name
            selectorType
            i18n
            readOnly
            multiple
            mandatory
            valueConstraints {
              displayValue
              value {
                type
                string
              }
              properties {
                name
                value
              }
            }
            defaultValues {
              type
              string
            }
          }
        }
      }
    }
  }
}

This will produce the JSON for the form for the specified node type, resulting from the merging of CND generation and all the associated static field set and form definitions.

How sections are inherited

By default, you can redefine all properties available in the JSON override:

• hasPreview
  Enables or disables preview
• sections
  The list of sections to display in the form

Jahia applies inheritance in the following way:

• Jahia first gets form definitions for all superTypes, in the inverse inheritance order.
• Jahia then gets form definitions for all mixins set on the node, in no specific order.
• If two forms definitions are on the same nodeType, the priority is used. A higher priority value will mean this will be the most important and override all others.
• Jahia merges all forms definitions in that order and any properties (hasPreview and sections) are overridden.
• If two forms definitions share the same nodeType and priority, one is ignored.

Example of section overrides and inheritance

You can use JSON overrides to define the section and preview behavior for a form. This example shows how to perform section and preview overrides of the jnt:contentcontent definition and how to disable preview for the qant:myFieldsRequired content type.

With form overrides, you can define the sections and preview behavior for a nodetype such as jnt:content.

[qant:myFieldsRequired] > jnt:content, qamix:qaContent, jmix:editorialContent
  - sharedSmallText (string) mandatory
  - smallText (string) i18n mandatory

First, provide a JSON form definition for jnt:content that:

• Displays sections content and metadata only
• Sets preview to true

The JSON override (added to /your_module/src/main/resources/META-INF/jahia-content-editor-forms/forms/jnt_content.json) is:

{
 "nodeType": "jnt:content",
 "priority": 1.0,
 "hasPreview": true,
 "sections": [
   {
     "name": "content",
     "labelKey": "label.engineTab.content",
     "requiredPermission": "viewContentTab"
   },
   {
     "name": "metadata",
     "labelKey": "label.engineTab.metadata",
     "requiredPermission": "viewMetadataTab"
   }
 ]
}

This creates a global rule and JSON override for jnt:content that is the default structure for all jnt:content and every node type that inherits from jnt:content.

But you would like to disable the preview for the qant:myFieldsRequired content type. You can override only hasPreview in a separate JSON override for qant:myFieldsRequired because, at the end, JSON overrides are merged together.

Here is the additional JSON override (added to /your_module/src/main/resources/META-INF/jahia-content-editor-forms/forms/qant_myFieldsRequired.json) to override qant:myFieldsRequired.

{
 "nodeType": "qant:myFieldsRequired",
 "priority": 1.0,
 "hasPreview": false
}

This way, only qant:myFieldsRequired will have preview disabled and all other jnt:content will have the preview enabled.

Section label keys

You may have noticed the labelKey setting for a section. This values contains a resource bundle key that will be looked up based on the format of its value. If it doesn't contain the @ character it will be looked up in the Jahia global server resource bundle that should not be modified by user. This could however be useful to re-use system keys (such as in the above examples). If you want to specify your own keys in your own module, you must use the following syntax:

basename@key

where the basename will be the name of the resource bundle (the base name of the file that will be located in the src/main/resources/resources directory in the site template module) and the key will be the key inside the file. Here's an example:

mySiteTemplate@myLabel

will look for the myLabel key inside the src/main/resources/resources/mySiteTemplate_*.properties file in the site template module. If it cannot be found, it will try to look it up in the main Jahia system resource bundle.

Field set overrides

Field set overrides allow you to add a new field set or edit fields within an existing field set. This sections explains how you can manipulate fields in field sets or sections. The next section shows you how to manipulate fields.

Structure of field set overrides

Field set overrides are JSON files that are stored in the following directory:

/your_module/src/main/resources/META-INF/jahia-content-editor-forms/fieldsets

The JSON file has the following format:

{
 "name": "jmix:myType",
 "fields": ...
  ...
  }

The Form builder builds forms from the definition. Then, for each inherited type the builder merges the current form with the overrides that match each type, according to their priority.

For example, for page content the Form builder:

• Reads the definition of jnt:page and the overrides of jnt:page ordered by priority.
• Gets inherited types of jnt:page and merges overrides for each.
• Gets types applied to the node (mixins) and merges overrides for each.
• Gets types that extend jnt:page (mixins with the extend attribute set to jnt:page) and merges overrides for each.

Field set properties

The following properties define a field set:

• name (string)
  Defines the nodetype on which the field set override applies
• displayName (string)
  Sets the display name for the field set. Internationalization is not supported in JSON, but if generated from  CND it will use the module's resource bundle
• description (string)
  Sets a description for the field set. Internationalization is not supported in JSON, but if generated from  CND it will use the module's resource bundle
• rank (decimal)
  Sets the position of the field set in the form. The default value is 0.0.
• priority (decimal)
  Defines the priority between field set of the same type. The default value is 1.0.
• removed (boolean) If true, the field set is removed from the generated form. The default value is false.
• dynamic (boolean)
  If true, the field set is dynamic. Not overridable yet. The default value is false.
• activated (boolean)
  if true, the field set is enabled for a dynamic field set. Not overridable yet. The default value is false.
• displayed (boolean)
  If false, the field set is part of the generated form, but is not displayed . Not overridable yet. The default value is true.
• readOnly (boolean)
  If true, the field set is marked as read only. Not overridable yet. The default value is false.
• fields (array)
  Array of fields that compose the field set.

Field overrides

The section describes field overrides, lists field properties that you can override, and provides examples of field overrides.

Field override basics

JSON overrides can override existing fields or add new fields. You can define field overrides in the fields section of field set override. The override applies to the node type defined by the name property of the field set.

{
 "name": "jmix:myType",
 "fields": [
   {
     "name": "fieldName",
     "mandatory": false,
     ...
   }
}

Field properties

Here the properties that can be overridden or used to create a field:

• name (string)
  To override an existing property, it must match the property name. Mandatory.
• displayName (string)
  Value displayed in the form. Internationalization is not supported in JSON, but if generated from  CND it will use the module's resource bundle
• description (string)
  Description of the field. Internationalization is not supported in JSON, but if generated from  CND it will use the module's resource bundle
• errorMessage (string)
  Error message that displays when field validation fails.
• selectorType (string)
  Defines the selector type (input) use for the field.
• readOnly (boolean)
  If true the field is set as read only. The default value is false.
• mandatory (boolean)
  If true the field is marked as mandatory. The default value is false.
• valueConstraints (array)
  Array of constraints applied on the field.
• defaultValues (array)
  Array of default values.
• removed (boolean)
  If true, the field will be removed from the form. The default value is false.
• target (object)
  This field defines the target where to display the field. Used to move a field to another location than its default one (see Moving fields).

Known limitations

Extensions are global to the platform. There is no need to enable the module on a site.

Currently only the direct properties of a type can have their fields overridden. It is not possible to override a field brought by a mixin on a specific type.

The properties multiple and I18n can not be overridden by JSON definition. As the definition does not allow to have multiple values or internationalized values, there will be an error when you will try to save the data in the JCR.

Moving fields

Field has a target property that allows you to move fields. You move fields by defining the section, field set, and ranking.

Field target structure

You can move a field to a given target, The target format is:

• sectionName
  Name of the section that displays the field
• fieldSetName
  Name of the field set that displays the field. Only if sectionName is filled.
• rank (decimal)
  Defines the rank of the field within the fields of the field set. A value of 0.0 ranks the field at the top and higher values rank the field lower. The default value is 0.

Moving a field in the same field set

The following override moves the template name field above the other fields in a page.

{
 "name": "jnt:page",
 "priority": 1.1,
 "fields": [
   {
     "name": "j:templateName",
     "target": {
       "rank": -1
     }
   }]
}