The Form-based content editor and also the Inline content editor are based on widgets. For each input field in the editor, a special widget is configured that defines how a value can be set. The available widgets reach from check boxes and select boxes up to very advanced image selection or location picker widgets. Here you get an overview on the available widgets and learn how to configure them.
OpenCms chooses for each content element a suitable widget. The choice is made dependent on the element's type.
But it is also possible to replace the default widget or configure this widget by adding a <layouts> node under xsd:annotation/xsd:appinfo in a content type's schema definition, and for each element where widget or widget behavior should change, a <layout> sub-node. Here is an example:
<layouts>
<layout element="..." widget="..." configuration="..." />
</layouts>OpenCmsDateTime it won’t be handled as this type. The data type of an element defined in the XSD is responsible for the internal handling of the values. The usage of data types increases the data quality which affects not only content retrieval and performance but also the overall data integrity e.g. keeping internal links intact.In the following sections you will find code snippets showing how to use and configure the distributed widgets. If a specific data type makes sense for the usage of a special widget the code snippets will contain the <xsd:element>- node, otherwise the examples only show the widgets configuration made in the <layout>-node assuming that the corresponding element uses OpenCmsString as type attribute.
The String widget provides a simple text input field to enter plain text that is stored as a String value internally.
This widget does not need any configuration and can be defined as follows:
<xsd:element name="Input" type="OpenCmsString" />The Boolean widget provides a checkbox and stores a Boolean value internally.
This widget does not need any configuration and can be defined as follows:
<xsd:element name="Checkbox" type="OpenCmsBoolean" />The display widget only shows a value without the possibility of modification. The value this widget displays is configured as an attribute inside its layout node:
A possible configuration could look like:
<layout element="Display" widget="DisplayWidget"
configuration="Value that is simply displayed and not editable." />The selector widget provides a drop down with a set of options.
The layout for this widget could look like:
<layout element="Selector" widget="SelectorWidget"
configuration="Option 1|Option 2*|Option 3|Option 4" />Read the section on configuration of select widgets to get more information.
The text area widget provides a HTML text area input field that can be scrolled if the text is too large to be displayed completely. The field can also be resized within the editor.
In the configuration parameter you can define the count of rows the text area displays when it’s opened initially. If no configuration is set, the default of fife rows is taken.
<layout element="Textarea" widget="TextareaWidget" configuration="3" />The radio button widget provides a group of radio buttons for single value selection.
The configuration could look like:
<layout element="RadioSelect" widget="RadioSelectWidget"
configuration="Option 1|Option 2*|Option 3|Option 4" />For more information on the configuration, look up the section on the configuration of select widgets.
The multi-select widget provides a group of check boxes to select one or more value.
The configuration could look like:
<layout element="MultiSelect" widget="MultiSelectWidget"
configuration="Option 1|Option 2*|Option 3|Option 4*" />For more information on the configuration, look up the section on the configuration of select widgets.
A combo widget offers a pre-defined set of select options with the ability for individual text input.
The configuration could look like:
<layout element="Combobox" widget="ComboWidget"
configuration="Value 1|Value 2| Value 3" />For more information on the configuration, look up the section on the configuration of select widgets.
This special combo box widget provides a list of all resource types configured for OpenCms.
This widget does not need a configuration string. The layout node should look like:
<layout element="TypeCombo" widget="TypeComboWidget" />The Html widget makes use of TinyMCE which has been extended for a lot of special CMS features.
The widget is used as default for all elements of type OpenCmsHtml and its default configuration is specified in the opencms-vfs.xml. Special configuration is possible for each element. The configuration attribute in the layout must contain the activated options as a comma separated String value:
<layout element="Text" widget="HtmlWidget"
configuration="height:400px,link,anchor,source,downloadgallery,formatselect"/>Here, you get information about the spellchecker used in the widget and it's configuration.
The localization widget provides a standard HTML form input field for overwriting localized values of a resource bundle. The resource bundle is configured with the widget configuration attribute. An optional key name to look up in the bundle can be given, too, in case it is different from the element name: key=mykey.
The locale to get the value for can be configured, by adding a configuration directive: locale=en.
<layout element="Localization" widget="LocalizationWidget"
configuration="org.opencms.workplace.messages|key=mykey|locale=en" />To use the stored localization values and have the values of the resource bundles as fallback, use the CmsXmlMessages object.
With the color picker widget you can comfortably choose a color.
This widget does not need any configuration, just use the element type OpenCmsColor.
<xsd:element name="Color" type="OpenCmsColor" />The date picker widget provides a convenient way of specifying dates.
This widget does not need any configuration, just use the type OpenCmsDateTime.
<xsd:element name="Calendar" type="OpenCmsDateTime" />Optionally, it is possible to hide the time selector by setting a fixed time, given in format 'HH:mm'.
<layout element="Calendar" widget="datetime" configuration='{fixedTime: "22:31"}' />The serial date widget provides a convenient way to specify a series of dates.
The widget is automatically chosen for elements of type OpenCmsSerialDate.
<xsd:element name="Dates" type="OpenCmsSerialDate" />Using the type OpenCmsSerialDate causes special indexing/search behavior for contents of the type: Each instance of the date series can be found separately. See the topic on event series for more information.
If you do not want special indexing behavior, you can also configure the widget for type OpenCmsString:
<layout element="Dates" widget="serialdate" configuration="" />%(currentdate).The category widget provides a category selection in a comfortable way.
The category widget is automatically assigned to elements of the type OpenCmsCategory and OpenCmsDynamicCategory which will enable storage of multiple selections.
OpenCmsVfsFile with the category widget, but then you won’t be able to make a multi selection.<xsd:element name="Category" type="OpenCmsDynamicCategory" />Note the differences between the types OpenCmsCategory and OpenCmsDynamicCategory:
OpenCmsCategory are physically stored in the XML content and can differ between the different language versions. For each sibling of the edited resource the categories of the sibling's locale (or the best fitting locale) are assigned to the sibling on saveThe assignment takes only place if the CategoryWidget is explicitely configured..OpenCmsDynamicCategory are not stored in the XML content at all. They refer directly to the categories assigned to the edited resource and are synchronized for all language versions automatically.When configuring the CategoryWidget, various options are available:
Configure the starting category by setting category=category/path/. Only the configured category and categories below that main category are displayed.
Configure the starting category via a property by setting property=property-name. The property is read from the edited content (or it's parent folders) and the value of the property is used as (category path of) starting category. Only the starting category and categories below that main category are displayed.
Here's an example configuration:
<layout element="Category" widget="CategoryWidget" configuration="category=location/|onlyleafs=false"/>The group widget is a special select box that offers a list of groups within OpenCms.
The widget must be chosen via a layout node. It has no extra configuration attribute.
<layout element="Group" widget="GroupWidget" />With the multi group widget you can select multiple groups at once.
The widget can be chosen by the following layout node.
<layout element="GroupMulti" widget="GroupMultiSelectorWidget" />To map the selected group to a permission to set, use the following mapping configuration:
<mapping element="MultiGroup" mapto="permission:GROUP:+r+v|GROUP.ALL_OTHERS:|GROUP.Projectmanagers:+r+v+w+c" />This means that the +r+v permission is written for the principal GROUP on the resource. Additionally two permissions are written as default: for ALL_OTHERS, no allowed permission is set, for Projectmanagers, +r+v+w+c is set.
The VFS file widget provides a selection of a file in the VFS. It either can be typed in directly or be chosen via a dialog. This dialog will come up by pushing the button on the right side of the input field.
The widget is automatically chosen when the widget-element's type is set to OpenCmsVfsFile:
<xsd:element name="VfsFile" type="OpenCmsVfsFile" />Optionally the widget can be configured as follows.
<layout element="VfsFile" widget="VfsFileWidget" configuration="startsite=/sites/default/|hidesiteselector" />The option is new in OpenCms 9.5.1. Use it for links to whole galleries, e.g., for a slide show. When the option is given, the file selector dialog opens in the galleries tab. Additionally it only shows the folder tab. The user can only select whole galleries or folders. It is not possible to select single files (or images).
Comma-separated list of resource types that are shown in the "Types" tab, i.e., you can add a search filter for. Types are specified by the type names, e.g., bs-blog,bs-text. It is still possible to find resources of other types, if you do not impose a type restriction at all. To restrict the selectable types, use the option selectabletypes.
The VFS image widget displays images and offers a couple of image-related functions such as resizing, cropping, etc.
The widget is automatically chosen for elements of type OpenCmsVfsImage.
{ scaleparams: 'q:70,r:2,c:CCCC00',
type: 'gallery',
startup: '/.galleries/samples/',
usedescription: true,
useformat: true,
formatnames: 'imageleft:Image left|imageright:Image right|imagetop:Image top',
formatvalues: ['150x?', '250x300', '?x250']
}
And then, the whole configuration looks for example as follows.
<layout element="VfsImage" widget="VfsImageWidget"
configuration="{ scaleparams: 'q:70,r:2,c:CCCC00',
type: 'gallery',
startup: '/.galleries/samples/',
usedescription: true,
useformat: true,
formatnames: 'imageleft:Image left|imageright:Image right|imagetop:Image top',
formatvalues: ['150x?', '250x300', '?x250']
}"
/>Optionally provide a class that implements a dynamic startup configuration and special format values. The value must be a fully qualified class name.
A list of format names to select, with pairs of selectable value and selectable text, e.g., value1:optiontext1|value2:optiontext2.
The format values corresponding to the formatnames list, can be dynamically generated by the dynamic configuration class or given here. The list of values should contain width and height information, with a ? as sign for dynamic size and with an x as separator for width and height. Example: ['200x?', '800x600'].
The scale parameters used as default. No width, height or crop information should be provided!
The startup folder for the selection dialog. It can be dynamically generated by the provided class, or explicitly given here. To allow the use of a dynamic startup folder, give dynamic as value here.
The startup folder type, can be gallery or category. The folder can be dynamically generated by the provided class, in that case, use dynamicas value.
For more information relevant for the widget, in particular information on the selection dialog, see the description of the image gallery widget.
The image gallery widget provides a way to browse image galleries, select an image, change its title and description, scale it, or look up image metadata. Furthermore, new images can be uploaded.
Via the icon 
you can upload a new image. The picture is added to either
repositoryfolder_imagegallery. This property is read from the currently edited resource. It can be inherited and thus it is preferable to set it on a folder.If neither repositoryfolder_imagegallery is set, nor an image gets replaced, the upload button is deactivated.
Via the icon 
, different functions can be accessed:
To use the image gallery widget, the editor element should have type OpenCmsVfsFile.
<xsd:element name="ImageGallery" type="OpenCmsVfsFile" />The configuration options for the image gallery widget are read from the configuration string of the widget. For nested XML schemas, the configuration string must be defined inside the nested content. The configuration string has to be formatted as a JSON object, with the following possible options:
Provide a class to configure the widget dynamically. The class must implement the interface I_CmsImageWidgetDynamicConfiguration.
The startup (gallery) folder, for the widget. Set the value to dynamic if it should be configured by class given via parameter class.
If set to true, content managers are allowed to scale and crop the chosen image for presentation in their content. How far images can be scaled is configured via the parameters formatnames and formatvalues.
Default: false.
Sequence of value-text pairs with different format options a content manager can select if useformat is set to true. If set, the parameter formatvalues has to be set to a list with the same length as the sequence.
The default values (with language dependent texts) are:
Example: value1:Text 1|value2:Text 2.
A list of “width x height”-values, e.g. ['200x?', '800x600'], where ? is used for a dynamic size. The format values correspond to the format names given via the parameter formatnames. Thus, the list length should match the length of the sequence given to formatnames.
Instead of giving the format values explicitely, they can be created dynamically by the class given via parameter class.
A possible layout configuration looks as follows.
<layout element="ImageGallery" widget="ImageGalleryWidget"
configuration="{ formatnames: 'portrait:Portrait|landscape:Landscape',
formatvalues: ['300x500','500x300'],
useformat: true,
startup: '/.galleries/samples/'}" />The download gallery widget provides a way to select VFS resources from galleries, or upload new resources into galleries.
The icons and provide similar functionality as in the image gallery widget, but in addition to image galleries, download galleries can also be browsed. To configure to which gallery files are uploaded, set the property repositoryfolder_downloadgallery. For more detailed information, see the description of the image gallery widget.
To use the download gallery widget, the editor element should have type OpenCmsVfsFile.
<xsd:element name="DownloadGallery" type="OpenCmsVfsFile" />The configuration options are read from the configuration string of the widget. For nested XML schemas the configuration string must be defined inside the nested content. The configuration string has to be formatted as a JSON object, with the following possible options:
Example configuration:
<layout element="DownloadGallery" widget="DownloadGalleryWidget"
configuration="{ gallerytypes: 'downloadgallery',
startup: '/.galleries/downloads/' }"
/>
The link gallery widget provides a selection of a file in the link gallery. This gallery will come up by pushing the button on the right side of the input field.
When using the link gallery widget, the best choice for the editor element's type is OpenCmsVarLink.
To use the link gallery widget, additionally a layout node has to be added, where the configuration attribute is optional.
<layout element="LinkGallery" widget="LinkGalleryWidget"
configuration="{ type: 'gallery',
startup: '/.galleries/links/' }"
/>The location picker widget allows to select a location via a map and to store information about the selected location and how it should be displayed in a map. The widget works for Google Maps, displays a Google Maps map in the widget and stores the data relevant to display a map using the Google Maps API. Be sure to meet the licence conditions when using Google Maps.
If a location is chosen, the widget looks as in the screenshot below:
The next screen shows the dialog that opens when you alter the location via the widget. The dialog's appearance depends on the widget's configuration. The dialog below is displayed for the default configuration that allows all values stored by the widget to be changed. To change the values, you can edit them manually. But for changing the address and the coordinates, you can also move the placemark in the map.
The location picker widget can be used for elements of type OpenCmsString. It is configured as shown in the example below.
<layout element="Map"
widget="LocationPickerWidget"
configuration='{"edit":["map", "address", "coords", "size", "zoom", "type", "mode"],
"apiKey": "your Google API key"}' />The configuration string's "edit"-option specifies which values should be editable via the widget. The example resembles the default "edit" configuration that allows all possible values to be edited. If a value should not be changed: just remove it from the list in the configuration string.
The "apiKey"-option is used to set a valid Google API key. If the option is not given, the key is read from the property google.apikey that has to be set on the path to the XML content the widget is used in.
For the widget, the default value is important. If no default value is set, the widget uses
{ "address": "London", "lat": 51.5001524, "lng": -0.1262362,
"height": 300, "width": 400, "mode": "", "type":"roadmap", "zoom": 8}If you set your own default, use exactly the format of the standard default value. Possible values for the different settings are:
Latitude coordinate of the location as used by Google Maps. Provided as a floating point number.
Longitude coordinate of the location as used by Google Maps. Provided as a floating point number.
Height of the map that can be used when rendering the map. Given as an integer value specifying the number of pixels.
Width of the map that can be used when rendering the map. Given as an integer value specifying the number of pixels.
The mode how the map should be rendered. Possible values are "static" or "dynamic". The value should be used to indicate if a static or a dynamic map is shown.
The default value reflects the structure of the strings that the location picker widget stores. To easily access the single values stored in the string the class CmsLocationPickerWidgetValue in the package org.opencms.widgets. To use the class in a JSP add the following lines to your JSP (possibly replacing content.value.Map by path to your content element storing map information):
<jsp:useBean id="map" class="org.opencms.widgets.CmsLocationPickerWidgetValue" />
<jsp:setProperty name="map" property="wrappedValue" value="${content.value.Map}" />The access restriction widget initially looks like a ordinary checkbox. Unlike the checkbox of the boolean widget, it does not store a boolean value into a content field but sets a user permission for the content: it sets a a group or a user as the "responsible user". The checkbox is visible for the "responsible user or group" only.
"Responsible user" is a concept for contents such as news articles that may only be visible to a specific group until they are published, even in the offline project, while they should be visible to everyone after publication.
<xsd:element name="Restricted" type="OpenCmsAccessRestriction" />Which group or user is stored must be defined with the widget configuration <WidgetConfig/>. It is recommended to configure strong synchronization for the access restriction type.
<Setting>
<PropertyName>Restricted</PropertyName>
<Widget>accessrestriction</Widget>
<WidgetConfig>{group: 'SpecialGroup'}</WidgetConfig>
<Synchronization>strong</Synchronization>
</Setting>The result is the same as if you would have added a new access control entry for the content, giving the "SpecialGroup" the "responsible" flag, with the permissions dialog.
The access restriction widget is a simplification in setting a permission directly in the content editor, which would otherwise be somewhat more complicated and only possible for certain users via the permissions dialog.
Since version 9.5.1, OpenCms features a dependent select widget. From it's appearance, the widget looks like the selector widget. The difference is, that the entries you can select, depend on the values of other editor fields. For example, you have a content listing a set of movies and an extra field to select your favorite movie out of the listed movies. The content's schema (XSD) could look as follows:
<!-- ... -->
<xsd:sequence>
<xsd:element name="Favorite" type="OpenCmsString" />
<xsd:element name="Movie" type="OpenCmsString" maxOccurs="20" />
</xsd:sequence>
<!-- ... -->
<layouts>
<layout element="Favorite" widget="DependentSelectWidget" configuration="Movie"/>
</layouts>
<!-- ... -->Then, the editor shows the following selection:
In the above example, the widget configuration is only the XPath to the nodes that contain the select options. If you have a sequence of nested contents that you want to select, you have two more options. E.g., if you have a nested content for the Movie node, containing an Id and a Title node, then you can configure the widget as follows:
<layout element="Movie" widget="DependentSelectWidget" configuration="Movie|Id|Title"/>The result is, that you see the Title shown in the select box and the Id is stored. That is, in comparism to the general select widget configuration, the Id is the value and the Title the option. You can also configure the widget as "Movie|Title". Then Title is value and option.
The Argument is the XPath to the sequence of content elements that should be observed to generate the options. The values of these elements are selectable via the widget. The values are used for the shown option and the stored value. This configuration should be used if the observed elements have no nested structure.
The first argument is the XPath to the sequence of content elements that should be observed to generate the options. The second argument is the XPath from the observed element sequence to a subelement that should be used as value to store and option to display when the observed element is chosen. This configuration is useful if the observed elements have a nested structure.
The first argument is the XPath to the sequence of content elements that should be observed to generate the options. The second argument is the XPath from the observed element sequence to a subelement that should be used as value to store when the observed element is chosen. The third value is an XPath from the observed element sequence to a subelement that should be used as display option when the observed element is chosen. This configuration is useful if the observed elements have a nested structure and the stored value should differ from the displayed option.
Since version 10.0 OpenCms features a display type select widget (DisplayTypeSelectWidget). It renders like a normal select widget, but the entries are automatically generated from all the formatters available in the current subsite and with "Use as display formatter" enabled.
The widget can be used for the configuration of generic list contents. With the widget, the formatters that should be used for a special resource type can be selected. See the demo of list creation for an example.
The widget is automatically configured for schema elements with type OpenCmsDisplayFormatter. An extra <layout> node is not necessary unless additional configuration for restricting the set of displayed formatters is required.
Here's the configuration of the widget for the element TypesToCollect - including all configuration options for the widget in the layout node and allowing a sequence of schema elements.
<!-- ... -->
<xsd:sequence>
<xsd:element name="TypesToCollect" type="OpenCmsDisplayFormatter" maxOccurs="unbounded" />
</xsd:sequence>
<!-- ... -->
<layouts>
<layout element="TypesToCollect" widget="DisplayTypeSelectWidget"
configuration="template.display.types|matchTypes" />
</layouts>
<!-- ... -->Here's how the widget renders if various display formatters are available:
The formatters shown in the widget can be reduced by two mechanisms, configured in the above example:
If the widget is used in a sequence of nodes, the option takes care of combining only "compatible" display formatters.
Once one display formatter is selected, only compatible display formatters are shown when selecting the second formatter. Compatible means to have the same "Display formatter type" set in the formatter configuration.
E.g., if you use the integrated list to collect, for example, events and blog entries in one list and both content types have two different display formatters, one with display formatter type "compact" (showing very little information) and one with display formatter type "elaborate" (showing much more information), you can't mix "compact" and "elaborate" formatters in the list.
This option is mainly useful if you have several websites with different templates on your OpenCms instance and different templates use different sets of display formatters.
If the option is provided, the property template.display.type is looked up recursively at the currently edited content and it's parent folders. If not found, it is looked up at the template JSP used at the place where the edited content is located. The property should contain a comma-separated list of container types. If the property is found and not empty, display formatters will be selectable only if they match to one of the containers of the given types. See the formatter configuration to see how matching containers are specified. If the property is not found, the matching conditions are simply ignored.
Since version 10.5 OpenCms features a data view widget. The widget basically displays a list of items where you can select, depending on the configuration, one or more. What items are shown in which way must be implemented by yourself in a class implementing org.opencms.widgets.dataview.I_CmsDataView.
Here's how you configure the widget:
<layout
element="Item"
widget="org.opencms.widgets.CmsDataViewWidget"
configuration="{class: 'my.Class', multiselect: true, preview: true, config: 'myconfig'}"
/>The Apollo template uses the widget for an imgur connection. See the module org.opencms.apollo.imgur for details.
If options are passed from XML content schema definitions as widget configuration options, the following syntax is used for defining the option values:
value='{text}' default='{true|false}' option='{text}'
help='{text}|{more option definitions}For example:
value='value1' default='true' option='option1' help='help1'|
value='value2' option='option2' help='help2'The elements default, option and help are all optional, while value is mandatory. There should be only one default option that is set true. If more than one is detected, only the first default found is actually used. If no option is given, the value of option defaults to the value of the given value. If no help is given, the default is null.
If you don't specify the value key, the value is assumed to start at the first position of an option definition. In this case the value does not need to be surrounded by the ' characters.
Example:
value='some value' default='true'could also be written as
some value default='true'Only if you use the short value definition as described above, a default value can be marked with a * at the end of the value definition.
Example:
value='some value' default='true'can also be written as
some value*Only if you use the short value definition as described above, you can also append the option to the value using a :. In this case no ' must surround the option. Please keep in mind that in this case the value itself can no longer contain a : char, since it would then be interpreted as a delimiter.
Example:
value='some value' option='some option'can also be written as
some value:some optionAny combinations of the above described shortcuts are allowed in the configuration option String. Here are some more examples of valid configuration option Strings:
1*|2|3|4|5|6|7
1 default='true'|2|3|4|5|6|7
value='1' default='true'|value='2'|value='3'
value='1'|2*|value='3'
1*:option text|2|3|4
1* option='option text' help='some'|2|3|4INFOlevel).