Search the documentation
 Show GitHub edit links  Hide GitHub edit links
Documented since: 9.0 Latest revision for: 10.0 Valid for OpenCms: 10.5.3

The form-based 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 the value can be set. The available widgets reach from check 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 you configure the widgets.

Note that, if the provided widgets do not satisfy your needs, you can also write own widgets.

How to configure a widget?

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>

Available widgets

Widgets are used to create a suitable content editor for XML content. The widgets to be used are defined in the XSD (schema definition) of the content type. Compared to the old XML content editor some configuration parameters have been added, changed or removed. The following sections will describe each widget and its parameters with a short example.

The widget configuration only tells the content editor which GUI component to use for value selection – not the data type to use. E.g., you can select a date with the date picker, but if you don’t tell OpenCms to use the type 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.

String Widget

The String widget provides a simple text input field to enter plain text that is stored as a String value internally.

Fig. [String widget example]: Layout of the string widget

This widget does not need any configuration and can be defined as follows:

<xsd:element name="Input" type="OpenCmsString" />

Boolean widget

The Boolean widget provides a checkbox and stores a Boolean value internally.

Fig. [Boolean widget example]: Layout of the boolean widget

This widget does not need any configuration and can be defined as follows:

<xsd:element name="Checkbox" type="OpenCmsBoolean" />

Display widget

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:

Fig. [Display widget example]: Layout of the display widget

A possible configuration could look like:

<layout element="Display" widget="DisplayWidget" 
        configuration="Value that is simply displayed and not editable." />

Selector widget

The selector widget provides a drop down with a set of options.

Fig. [Selector widget example]: Layout of the selector widget

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.

Textarea widget

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.

Fig. [Textarea widget example]: Layout of the textarea widget

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" />

Radio-select widget

The radio button widget provides a group of radio buttons for single value selection.

Fig. [Radio-select widget example]: Layout of the radio-select widget

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.

Multi-select widget

The multi-select widget provides a group of check boxes to select one or more value.

Fig. [Multi-select widget example]: Layout of the multi-select widget

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.

Combo widget

A combo widget offers a pre-defined set of select options with the ability for individual text input.

Fig. [Combo widget example]: Layout of the combo widget

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.

Type-combo widget

This special combo box widget provides a list of all resource types configured for OpenCms.

Fig. [Type-combo widget example]: Layout of the type-combo widget

This widget does not need a configuration string. The layout node should look like:

<layout element="TypeCombo" widget="TypeComboWidget" />

Html widget

The Html widget makes use of TinyMCE which has been extended for a lot of special CMS features.

Fig. [Html widget example]: Layout of the Html widget

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.

Localization widget

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.

Fig. [Localization widget example]: Layout of the localization widget

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.

Color-picker widget

With the color picker widget you can comfortably choose a color.


The color-picker dialog shown in the picture appears if you click on the marked box with the color preview.
Fig. [Color-picker widget example]: Layout of the color-picker widget

This widget does not need any configuration, just use the element type OpenCmsColor.

<xsd:element name="Color" type="OpenCmsColor" />

Date-picker widget

The date picker widget provides a convenient way of specifying dates.


The date-picker dialog shown in the picture appears if you click on the line where the currently set date is shown.
Fig. [Date-picker widget example]: Layout of the date-picker widget

This widget does not need any configuration, just use the type OpenCmsDateTime.

<xsd:element name="Calendar" type="OpenCmsDateTime" />

Category widget

The category widget provides a category selection in a comfortable way.


To show the category selection dialog shown in the figure, click on the box where the currently chosen categories are shown.


Fig. [Category widget example]: Layout of the category widget

The category widget is automatically assigned to elements of the type OpenCmsCategory and OpenCmsDynamicCategory which will enable storage of multiple selections.

For legacy reasons it is still possible to layout elements of the type 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:

  • Values of 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..
  • Values of 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.
We recommend using the type OpenCmsDynamic category to avoid discrepancies between the categories stored in the content and the ones really assigned to the resource.

When configuring the CategoryWidget, various options are available:

Available configuration options
category

Configure the starting category by setting category=category/path/. Only the configured category and categories below that main category are displayed.

onlyleafs

If you configure onlyleafs=true,  Only leaf-categories can be selected.

property

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"/>

Group widget

The group widget is a special select box that offers a list of groups within OpenCms.


The dialog for group selection, shown in the figure, pops up when the folder icon at the widget's edit line is clicked. Select a group by clicking on it.


Fig. [Group widget example]: Layout of the group widget

The widget must be chosen via a layout node. It has no extra configuration attribute.

<layout element="Group" widget="GroupWidget" />

Multi-group selector widget

With the multi group widget you can select multiple groups at once.

Fig. [Multi-group selector widget example]: Layout of the multi-group selector widget

The widget can be chosen by the following layout node.

<layout element="GroupMulti" widget="GroupMultiSelectorWidget" />
Available configuration options
groupfilter

A regular expression to filter available groups

groups

A comma separated list of group names to show in the select box.

Please note, if this configuration option is used, groupfilter and includesubous are not considered anymore.

includesubous

A Boolean flag to indicate whether sub OUs should be scanned for groups to select.

oufqn

The fully qualified name of the OU to read the groups from.

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.

VFS file widget

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. A detail description of the popup can be found in TODO:LINK "GallerySelection".


Pushing the folder button on the right of the input field, the dialog shown in Figure [Resource selection dialog] appears.
Fig. [VFS file widget example]: Layout of the VFS file widget
Fig. [Resource selection dialog]: Dialog for selecting an OpenCms VFS resource

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" />
Available configuration options
excludefiles

Files are hidden in the popup tree.

galleryselect

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 (see Figure [vfsfile_galleryselect_dialog]). 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).

hidesiteselector

The site selector is hidden (default).

includefiles

Files are shown in the popup tree (default).

notprojectaware

Do not filter resources by project (default).

projectaware

Show only resources of the current project.

searchtypes

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.

selectabletypes

Comma-separated list of resource types you can select resources of, e.g., bs-blog, bs-text. If you specify this list, it is not possible to find and select content of other types.

showsiteselector

The site selector is shown.

startfolder

The folder the popup tree is opened with.

startsite

The site the popup tree is opened with.

Fig. [vfsfile_galleryselect_dialog]: File Selection dialog for the VfsFileWidget when the configuration option "galleryselect" is given.

VFS image widget

The VFS image widget displays images and offers a couple of image-related functions such as resizing, cropping, etc.

Fig. [VFS image widget example]: Layout of the VFS image widget

The  widget is automatically chosen for elements of type OpenCmsVfsImage.

<xsd:element name="VfsImage" type="OpenCmsVfsImage" />

Optionally, the widget can be configured. The configuration uses the JSON format.

A configuration string may look like:

{ 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']
	}" 
/>
Available configuration options
class

Optionally provide a class that implements a dynamic startup configuration and special format values. The value must be a fully qualified class name.

formatnames

A list of format names to select, with pairs of selectable value and selectable text, e.g., value1:optiontext1|value2:optiontext2.

formatvalues

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

scaleparams

The scale parameters used as default. No width, height or crop information should be provided!

startup

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.

type

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.

usedescription

Indicates whether the description input field for the image should be shown or not. (values: true or false)

useformat

Indicates whether the format select box for the image should be shown or not (values: true or false)

For more information relevant for the widget, in particular information on the selection dialog, see the description of the image gallery widget.

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.

Fig. [Image gallery widget example]: Layout of the image gallery widget

Via the icon  you can upload a new image. The picture is added to either

  • the gallery, the replaced image belongs to, or, if no picture is already present,
  • the gallery (folder) chosen via the property 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:

  • Adjust how the selected picture is shown (see Figure [Adjusting a selected image]). This is the default if an image was selected before.
  • Browse an image gallery (see Figure [Browse an image gallery]). This is the default if a default gallery is configured in the widget’s configuration and no image is already selected.
  • Select which image gallery to use (see Figure [Select an image gallery]). This is the default if no image is already selected and no default gallery is configured in the widget’s configuration.
Fig. [Adjusting a selected image]: Dialog for image adjustment
Fig. [Browse an image gallery]: Dialog for browsing image galleries
Fig. [Select an image gallery]: Dialog for selecting (image) galleries

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:

Available configuration options
class

Provide a class to configure the widget dynamically. The class must implement the interface I_CmsImageWidgetDynamicConfiguration.

startup

The startup (gallery) folder, for the widget. Set the value to dynamic if it should be configured by class given via parameter class.

useformat

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.

formatnames

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:

  • original: insert the complete picture in its original format
  • user: the user is free to crop the image and adjust the size
  • free: the user is free to crop, but not scale the image
  • small: the image, or the cropped part is scaled to 200px width
  • big: the image, or the cropped part is scaled to 500px width

Example: value1:Text 1|value2:Text 2.

formatvalues

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/'}" />

Download gallery widget

The download gallery widget provides a way to select VFS resources from galleries, or upload new resources into galleries.

Fig. [Download gallery widget example]: Layout of the download gallery widget

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:

Available configuration options
class

Provide a class to configure the widget dynamically. The class must implement the interface I_CmsImageWidgetDynamicConfiguration.

startup

The startup (gallery) folder, for the widget. Set the value to dynamic if it should be configured by class given via parameter class.

gallerytypes

Set which types of galleries are considered by the widget. Suitable types are downloadgallery and imagegallery. The value has to be a comma separated list.

Default:  imagegallery,downloadgallery

Example configuration:

<layout element="DownloadGallery" widget="DownloadGalleryWidget" 
        configuration="{ gallerytypes: 'downloadgallery', 
                         startup: '/.galleries/downloads/' }"
/>

Link gallery widget

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.

Fig. [Link gallery widget example]: Layout of the link gallery widget

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/' }"
/>
Configuration options for the link gallery widget
class

An optional class implementing dynamic startup configurations and format values.

startup

The startup folder, set to dynamic if you want to use the custom class.

type

Can be gallery or category, set to dynamic if you want to use the custom class.

Location picker widget

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 Figure [location_picker_widget].

Fig. [location_picker_widget]: The localization picker widget

Figure [location_picker_choose_location] 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.

Fig. [location_picker_choose_location]: Choosing a location via the location picker widget

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:

address

Any string value that you will use to describe the location

lat

Latitude coordinate of the location as used by Google Maps. Provided as a floating point number.

lng

Longitude coordinate of the location as used by Google Maps. Provided as a floating point number.

height

Height of the map that can be used when rendering the map. Given as an integer value specifying the number of pixels.

width

Width of the map that can be used when rendering the map. Given as an integer value specifying the number of pixels.

mode

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.

type

Type of the map that should be shown. Valid values are the types available for Google Maps, i.e., "roadmap", "satellite", "hybrid" or "terrain".

zoom

Specifies the zoom level that should be used to display the map. Valid values are the integers from 0 to 20.

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}" />

Dependent select widget

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:

Fig. [dependent_select_widget]: The dependent select widget (field "Favorite") in action - all given movies are listed in the 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.

Configuration options of the dependent select widget
{observed node sequence}

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.

{observed node sequence}|{choosable elements}

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.

{observed node sequence}|{choosable element's values}|{choosable element's displayed option}

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.

Display Type Select Widget

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 since the widget has no configuration options.

Here's the configuration of the widget for the element TypesToCollect:

<xsd:element name="TypesToCollect" type="OpenCmsDisplayFormatter" />

Here's how the widget renders if various display formatters are available:

Data view widget

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.

Select widget configuration

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.

Shortcut syntax options

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 option

Any 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|4
If an entry in the configuration String is malformed, this error is silently ignored (but written to the log channel of this class at INFOlevel).

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.