Dependent editor fields

The value of one editor field or even the widget configuration can depend on the values of other editor fields. The dependencies are defined in the XSD defining the content. We show an example for dependent fields: We change a field's value dependent on the value of another field.

Related links

1 The result

Edit the content, change the picture and see what happens to the value of CopyText.

 
Copyright notice: copyleft
 

2 Example resources and the interesting spots

The dependency between the field values is configured in the XSD that defines the content type.

/system/modules/com.alkacon.opencms.documentation/schemas/demo/documentation-demo-dependent-fields.xsd
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	elementFormDefault="qualified">

	<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd" />

	<xsd:element name="DocumentationDemoArticleDependentFields" type="OpenCmsDocumentationDemoArticleDependentFields" />

	<xsd:complexType name="OpenCmsDocumentationDemoArticleDependentFields">
		<xsd:sequence>
			<xsd:element name="DocumentationDemoArticleDependentField" type="OpenCmsDocumentationDemoArticleDependentField"
				minOccurs="0" maxOccurs="unbounded" />
		</xsd:sequence>
	</xsd:complexType>

	<xsd:complexType name="OpenCmsDocumentationDemoArticleDependentField">
		<xsd:sequence>
			<xsd:element name="Image" type="OpenCmsVfsFile" />
			<xsd:element name="CopyText" type="OpenCmsString" />
		</xsd:sequence>
		<xsd:attribute name="language" type="OpenCmsLocale" use="required" />
	</xsd:complexType>

	<xsd:annotation>
		<xsd:appinfo>
			<layouts>
				<layout element="Image" widget="ImageGalleryWidget" />
			</layouts>
			<editorchangehandlers>
				<editorchangehandler 
					class="org.opencms.ade.contenteditor.CmsEditorChangeHandlerProperty" 
					scope="Image" configuration="Copyright|../CopyText" />
			</editorchangehandlers>
		</xsd:appinfo>
	</xsd:annotation>
</xsd:schema>

The interesting spot is the node <editorchangehandlers>. Here the dependencies are defined. Each sub-node <editorchangehandler> has three attributes:

Attributes of <editorchangehandler>
class

The class that handles the dependency. By default, OpenCms provides CmsEditorChangeHandlerProperty as concrete handler implementation, but you can write 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 explictely addess one element in a series and all fields of a 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.

In the example, we use the CmsEditorChangeHandlerProperty to observe the Image editor field and copy the Copytext property of the resource given as value of the Image field to the field CopyText. Whenever the value of Image changes, the value of CopyText will be updated.

Notice the following pecularities:

  • You can alter the CopyText value in the content editor and your alteration will be stored. Only if you change the Image value, your altered value will be replaced.
  • Altering the CopyText will not update the Copyright property of the image. If you want that: define a mapping from CopyText the the Copyright property.