OpenCms Documentation

Field settings

 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 11.0.0 Valid for OpenCms: 11.0.0

The structure of a content of specific type and its behaviour are specified in an XSD. Field settings, introduced in OpenCms 11, allow to adjust the behavior of a single editor field in one place. They unify the configuration syntax with the one for element settings in formatter configurations. They provide simpler syntax for some configuration options and enhance reusability of configurations.

Here we describe the syntax of field settings and briefly describe the different options. Most of the options are configurable in the former feature-centered configuration syntax. For details of the features, we link to the respective other topics.

Field settings configuration syntax

The structure for the configuration of the editor fields using field settings in a XSD is as follows:

...
    <FieldSettings>
           <Setting>
                <PropertyName>FieldName</PropertyName>
                <Option1>...<Option1>
                <Option2>...<Option2>
                ...
           </Setting>
           <Setting>
                ...
           </Setting>
           ... 
    </FieldSettings>
...

The field name is given in the <PropertyName> element. The other possible options (indicated by the placeholders Option1, Option2...) are listed in the chart below the following example.

Example for Field settings

This example illustrates the clarity of the new annotation. So you have all the configurations of an editor field together in one place written in a <Setting>-node. The <FieldSettings>-node is inserted in the <xsd:appinfo>-node.

...	
		<xsd:sequence>
			<xsd:element name="Headline" type="OpenCmsString" />
			<xsd:element name="Selection" type="OpenCmsString" />
			<xsd:element name="Teaser" type="OpenCmsString"/>
			<xsd:element name="Text" type="OpenCmsHtml" />
			...
		</xsd:sequence>
	</xsd:complexType>

	<xsd:annotation>
		<xsd:appinfo>
                        ...
			<FieldSettings>
				<Setting>
					<PropertyName>Headline</PropertyName>
					<DisplayName>%(key.label.Headline)</DisplayName>
					<RuleRegex>.+</RuleRegex>
					<RuleType>Error</RuleType>
					<Error>%(key.error.notempty)</Error>
				</Setting>
				<Setting>
					<PropertyName>Selection</PropertyName>
					<DisplayName>%(key.label.Selection)</DisplayName>
					<Description>%(key.help.Selection)</Description>
					<Widget>SelectorWidget</Widget>
					<WidgetConfig>Option 1|Option 2|Option 3*</WidgetConfig>
					<Display>singleline</Display>
				</Setting>
				<Setting>
					<PropertyName>Teaser</PropertyName>
					<Description>%(key.help.Teaser)</Description>
					<Widget>TextareaWidget</Widget>
					<WidgetConfig>4</WidgetConfig>
					<Display>column</Display>
				</Setting>
				<Setting>
					<PropertyName>Text</PropertyName>
					<Widget>HtmlWidget</Widget>
					<Default>%(key.default.Text)</Default>
					<WidgetConfig>height:400px,link,anchor,source,formatselect</WidgetConfig> 
					<Display>column</Display>
				</Setting>
			</FieldSettings>
		</xsd:appinfo>
	</xsd:annotation>
...

The following screenshot shows the content editor of the XSD above.

Fig. [FieldSettingsAnnotation_ContentEditor]: Content Editor

Options of the field settings

The following table explains the available options. All of them except <PropertyName> are optional, but have to occur in the order listed below. All options except <Mapping> can be used only once.

PropertyName

The name of the content field. This element is required.

DisplayName

The user-readable name of the field, which is displayed next to the field in the editor.

Description

The user-readable help text for the field. This is used for tooltips.

Widget

The widget to use for the field. Widget name are defined in the opencms-vfs.xml configuration file. For further information see widget configuration.

Default

The default value for the field.

DefaultResolveMacros

Boolean value that controls whether macros int the <Default> configuration option will be expanded when the default value is being filled in. See also defaults with macros. Default ist true.

WidgetConfig

The configuration string for the widget. For further information see widget configuration.

RuleRegex

The regular expression used to validate the field.

RuleType

Can be error or warning. This determines whether failure to vaidate the field using the given RuleRegex should be displayed as an error or warning.

Error

The error or warning message to display when validation using the given RuleRegex fails.

Relation

Used to specify the relation type for file-valued fields. This element can contain two sub-elements:

  • Type Specifies the relation type, weak or strong
  • Invalidate Boolean value that specifies how an invalid link in the field should be handled. The value true means that the field will be removed, the value parent means that the nested content containing the field will be removed.
Search

Used to specify how this field should be treated during indexing. This option does not have the full flexibility of the <searchsettings> configuration. Possible values are

  • true The field should be included in the content fields of the indexed document. This is default.
  • false The field should not be included in the content fields of the indexed document.
  • listdate, listorder, listtitle Shortcuts for some specialized search setting configurations. See src/org/opencms/xml/content/simple-searchsetting-configs.st in the opencms-core project for the standard search setting configuration.

This option covers most use cases, but not all the options available via the <searchsettings> configuration. For more details about this options and the <searchsettings> node, see here.

Visibility

Simple option for setting the visibility for this field. When this is used, the content handler is used as the visibility handler for this field and the content of this element is passed as a parameter. Here you can see how to hide schema elements in the content editor.

FieldVisibilitiy

More flexible version of Visibiity that also allows giving a custom visibility handler class name. Sub-elements  are:

  • Class The class name of the visibility handler.
  • Params The parameters for the visibility handler.

Here you can see how to hide schema elements in the content editor.

Mapping

Allows the value of the field to be mapped to something else like properties or the URL name. This element can be used multiple times to define different mappings for the same field. This element contains two sub-elements:

  • MapTo The target of the mapping. The most important values are:
  • property:PropName the field value will be mapped to the PropName property.
  • urlName the field value will be used as the URL name for generating detail page links to the content.
  • galleryName the field value should be used as the title for displaying search results in the gallery dialog.
  • UseDefault Boolean value. If true, the default value for this field should be mapped to the given target if the field does not exist.

See also Mappings.

NestedFormatter

Boolean value that indicates that the field contains the references to the nested formatters used by this content element.

Display

Display style for the field in the content editor. Possible values are column, wide, singleline and none.

Synchronization

Boolean value that indicates whether changes to this field should be synchronized to other locales when editing the content. Read more about synchronization. Default is false.

Advantages of the field settings notation

Fieldsettings

  • allow to explicitly specify message keys for the localization of editor fields and the help texts (via<DisplayName> and <Description>). Hence, you can share the same localizations in various schemas, which was formerly not possible.Which has also the advantage that you can use the same schema type names in several XSDs without getting into conflicts concerning localization.
  • unify the configuration syntax for editor fields and element settings in formatter configurations
  • group the configuration options in an easily reusable way.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.