Field settings

The structure of a content type and its behaviour are specified in an XSD. Field settings allow to adjust the behavior of a single editor field.

Configuration syntax

The field settings configuration syntax has the following structure:

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

The <PropertyName> element is used to reference a content element definition by name.

Example

The following example illustrates the usage of field settings:

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

This is the editor UI resulting from the example configuration above:

Available options

The following table explains the available options. All of them expect the <PropertyName> element. All other elements are optional, but have to occur in the order listed below. All options except <Mapping> can be used once only.
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 names 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, listgeocoords Shortcuts for some specialized search setting configurations.

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.