OpenCms documentation
OpenCms documentation

Dependent fields

OpenCms allows fields in the content editor to be made dependent on other fields. You can listen to changes made in an editor field and then react to that change by adjusting values in other fields.

You may run into a scenario, where the value of one schema element is somehow related to the value of another schema element (or even of many other such elements). When content is edited in the content editor and the editor field that displays a schema element changes, it may be valuable to adjust the value displayed in another editor field.

An example is copyright information on images. Your content may allow to insert images and set copyright information on such images. If a picture is exchanged, the copyright information should be adjusted accordingly (possibly read from a property of the picture).

To configure dependent fields, you need to register an editor change handler to a schema element in the schema definition of a content type. Handlers are added under xsd:annotation/xsd:appinfo in a subnode <editorchangehandlers>. Here's an example:

Configuration of editor change handlers

<editorchangehandlers>
    <editorchangehandler 
        class="org.opencms.ade.contenteditor.CmsEditorChangeHandlerProperty" 
        scope="Image" configuration="Copyright|../CopyText" />
</editorchangehandlers>

Inside the node <editorchangehandlers> you can define different change handlers via the node <editorchangehandler> that has the following attributes.

class

The class that handles the dependency. By default, OpenCms provides CmsEditorChangeHandlerProperty as a concrete handler implementation, but you can write your own handlers.

scope

Define the editor fields that should be observed for changes. The fields have to be specified by an XPath, e.g., "Paragraphs*/Headline". The path can contain * as wildcard to observe all elements in a sequence. Moreover, the path can also explicitly addess one element in a series and all fields of subcontent. For example, "Paragraphs[2]" would cause observation for all fields in the second paragraph.

configuration

Configuration is handler specific, hence it depends on the class you specified in the class attribute. For example, the CmsEditorChangeHandlerProperty takes a property name and the path to the field that should be updated with the property, where the two are separated by |. The path can be given relative to the observed field or absolute.

By default, OpenCms provides CmsEditorChangeHandlerProperty as a concrete handler implementation.

org.opencms.ade.contenteditor.CmsEditorChangeHandlerProperty

If in some observed editor field a new VFS link is inserted, the handler reads a specified property of the resource it is linked to and places this property as the value into another editor field.

You are allowed to write your own editor change handlers. They have to implement the interface I_CmsXmlContentEditorChangeHandler located in the package org.opencms.xml.content. To simplify implementing new such handlers, the class A_CmsXmlContentEditorChangeHandler from the package org.opencms.ade.contenteditor can be used as base class.

The dependent select widget allows to have the selectable values dependent on a sequence of other value provided in the content.