Skip to content
OpenCms documentation
OpenCms documentation

Widget configuration

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

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

Layout of the string widget

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.

Layout of the boolean widget

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:

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

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

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.

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.

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

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

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.

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

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.

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

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.

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

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

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

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.

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.

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.

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.

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.

The date-picker dialog shown in the picture appears if you click on the line where the currently set date is shown.

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 serial date widget

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="" />
Note that the widget stores it's data in a specific format. If you want to configure a default value, you might first set this value using the widget, copy the value and maybe add macros like %(currentdate).

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.

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:

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

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

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

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.

Layout of the multi-group selector widget

The widget can be chosen by the following layout node.

<layout element="GroupMulti" widget="GroupMultiSelectorWidget" />

A regular expression to filter available 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.

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

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.

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.

Layout of the VFS file widget. Pushing the folder button on the right of the input field, the dialog shown in the next screeenshot appears.
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" />

Files are hidden in the popup tree.

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

The site selector is hidden (default).

Files are shown in the popup tree (default).

Do not filter resources by project (default).

Show only resources of the current project.

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.

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.

The site selector is shown.

The folder the popup tree is opened with.

The site the popup tree is opened with.

File Selection dialog for the VfsFileWidget when the configuration option 'galleryselect' is given.

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

Layout of the VFS image widget

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.

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

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.

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.

ContentEditor_ImageGalleryWidget1

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.
  • Set the focal point of the image (see Figure [Setting the focal point]). It is used as center of the image when it is cropped. Hence, the focal point should be on the most interesting part of the image.
  • 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.
Adjusting a selected image
Image gallery widget: Focal point selection
Browse an image gallery
Select an image gallery

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:

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

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.

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:

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.

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

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.

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

An optional class implementing dynamic startup configurations and format values.

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

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

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 localization picker widget

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.

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:

Any string value that you will use to describe the location

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.

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

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

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:

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.

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.

The configuration options are available only since OpenCms 11.
<!-- ... -->
<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 display type select widget

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