Customizing Content Editor forms

  Written by The Jahia Team
   Estimated reading time:

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:allFields  node type should be named qant_allFields.json.

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

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

With this definition, when you create or edit a node of the type  qant:allFields, 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:allFieldsRequired content type.

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

[qant:allFieldsRequired] > 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:allFieldsRequired content type. You can override only hasPreview in a separate JSON override for qant:allFieldsRequired 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_allFieldsRequired.json) to override qant:allFieldsRequired.

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

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

Fieldset overrides

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

Fieldset overrides examples

The following examples show how to move and remove a fieldset.

Moving a fieldset

The following override moves the title fieldset to the top of the form:

{
 "name": "mix:title",
 "priority": 1.0,
 "rank": -1.0
}

The following override moves tags in the classification section:

{
 "name": "jmix:tagged",
 "priority": 1.0,
 "fields": [
   {
     "name": "j:tagList",
     "target": {
       "sectionName": "classification",
       "rank": 1
     }
   }
 ]
}

Removing a fieldset

The following override hides the fieldset cache:

{
 "name": "jmix:cache",
 "priority": 1.0,
 "removed": true
}

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.
  • I18n (boolean)
    If true the field is internationalized. The default value is false.
  • readOnly (boolean)
    If true the field is set as read only. The default value is false.
  • multiple (boolean)
    If true the field allows multiple values. 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 a fieldset).

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.

Field override examples

The following example show how to add a mandatory constraint, set a default value, change a selector, change constraint values, and remove a field.

Adding a mandatory constraint

You can add a mandatory constraint by setting the mandatory property of the field element to true.

The following override makes the description mandatory:

{
 "name": "jmix:description",
 "priority": 1.1,
 "fields": [
   {
     "name": "jcr:description",
     "mandatory": true
   }]
}

Setting a default value

You can set a default value for a field by setting the defaultValues array property of the field element to a couple of type or value elements. Multiple default values can be set for a multiple property. Note that default values provided by override are not localized.

The following override sets a default value for intro of an article type:

{
 "name": "jnt:article",
 "priority": 1.1,
 "fields": [
   {
     "name": "intro",
     "defaultValues": [{
       "type": "STRING",
       "value": "article value"
     }]
   }]
}

Changing a selector

This can be achieved by setting the selectorType property of the field element to chosen selector value. You can find more about custom selectors at Creating custom selector types for Content Editor.

The following override sets a custom selector for markDownText of markdownField type.

{
 "name": "eent:markdownField",
 "fields": [
   {
     "name": "markDownText",
     "selectorType": "Markdown"
   }
 ]
}

Changing constraint values

The following override changes constraint values.

{
 "name": "jmix:description",
 "priority": 1.1,
 "fields": [
   {
     "name": "jcr:description",
     "mandatory": false,
     "target": {
       "sectionName": "metadata",
       "rank": 0.0
     },
     "valueConstraints": [
       {
         "value": {
           "type": "String",
           "value": "^[A-Z]+.*"
         },
         "displayValue": "Must start with a capitalized letter"
       }
     ]
   }]
}

Removing a field

The following override removes the intro field from an article:

{
 "name": "jnt:article",
 "priority": 1.0,
 "fields": [
   {
     "name": "intro",
     "removed": true
   }]
}

Adding a new field

Note: This functionality is not fully supported yet and should only be used in a test environment.

You can add fields that are not in a JCR definition. 

A fieldset is composed of a:

  • name
  • priority
  • collection of field definitions

The following example shows how to add a fieldset which contains a simple field that is placed in mysection:

{
 "name": "nt:base",
 "rank": 1.0,
 "priority": 1.0,
 "dynamic": false,
 "removed": false,
 "activated": true,
 "fields": [
   {
     "name": "ce:systemName",
     "description": "",
     "requiredType": "STRING",
     "selectorType": "Text",
     "i18n": false,
     "readOnly": false,
     "multiple": false,
     "mandatory": true,
     "target": {
       "sectionName": "mysection",
       "rank": 0.0
     }
   }
 ]
}

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. Not supported yet.
  • 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.

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