Customizing Content Editor forms

February 2, 2022

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

Note: For examples of overrides, see Examples of content definition JSON overrides. For information on Content Editor interface elements and layout, see Understanding Content Editor forms 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 fieldsets 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.

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.
  • 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.
Note: Section inheritance is intentionally similar to the JCR definition of node type inheritance to bring consistency and extensibility to the content editing UI.

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.

Fieldset overrides

Fieldset overrides allow you to add a new fieldset or edit fields within an existing fieldset. This sections explains how you can manipulate fields in fieldsets or sections. The next section shows you how to manipulate fields.

Structure of fieldset overrides

Fieldset 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.

Fieldset properties

The following properties define a fieldset:

  • name (string)
    Defines the nodetype on which the fieldset override applies
  • displayName (string)
    Sets the display name for the fieldset. Internationalization is not supported. Not used in our current forms.
  • description (string)
    Sets a description for the fieldset. Internationalization is not supported. Not used in our current forms.
  • rank (decimal)
    Sets the position of the fieldset in the form. The default value is 0.0.
  • priority (decimal)
    Defines the priority between fieldset of the same type. The default value is 1.0.
  • removed (boolean) If true, the fieldset is removed from the generated form. The default value is false.
  • dynamic (boolean)
    If true, the fieldset is dynamic. Not overridable yet. The default value is false.
  • activated (boolean)
    if true, the fieldset is enabled for a dynamic fieldset. Not overridable yet. The default value is false.
  • displayed (boolean)
    If false, the fieldset is part of the generated form, but is not displayed . Not overridable yet. The default value is true.
  • readOnly (boolean)
    If true, the fieldset is marked as read only. Not overridable yet. The default value is false.
  • fields (array)
    Array of fields that compose the fieldset.

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 fieldset override. The override applies to the node type defined by the name property of the fieldset.

{
 "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.
  • description (string)
    Description of the field. Internationalization is not supported.
  • 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, fieldset, 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 fieldset that displays the field. Only if sectionName is filled.
  • rank (decimal)
    Defines the rank of the field within the fields of the fieldset. A value of 0.0 ranks the field at the top and higher values rank the field lower. The default value is 0.
Warning: If there is already an json override on a field that you want to move to another section, it's necessary to specify the target fieldset name of the field. For example in content editor the nt:base fieldset already have an override with the system name, so if you want to move the system name in another place than the option section, you will have to specify the new section name and the new fieldset name

Moving a field in the same fieldset

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
     }
   }]
}

 

moving-field-in-fieldset.png