Customizing Datatypes
Using Advanced Widgets
Each type of a data type field has one or more widgets associated with it. If more than one widget can be used with a field, one of them is assigned to the field by default.
Some widgets have no parameters and can be used out-of-the-box when assigned. Other widgets have parameters and can be therefore configured.
Normally, the configurable widgets have reasonable default values for their parameters. You can thus use them out-of-the-box as well. However, if you have some specific requirements, you can override these defaults.
The following widgets have no parameters:
- DateSelector
- DateTimeSelector
- Selector (data reference)
- Optional Selector
- MediaFileFolderSelector
The configurable widgets are as follows:
- TextBox
- TextArea
- CheckBox
- VisualXhtmlEditor
- ImageSelector
- MediaFileSelector
- BoolSelector
- DataIdMultiSelector
- Selector (string)
Note: You can have a quick overview of all the widgets in A Guide to Creating Data Types.
In this chapter we will focus on the configurable widgets. You will learn in detail how to set up parameters of these widgets.
Each parameter is listed by its name used in the Form XML (“XML Name”), which may be different from its name visible to the user in the Field Widget Configuration window (“GUI Name”).
Each parameter has a short description provided and its type specified. It is indicated whether the parameter is required or optional. Its possible values and its default value are specified.
The TextBox widget has allows you to choose whether the text entered will be spell-checked (Firefox only) based on the current language of the website. You should explicitly disable spell checking on fields that contain e-mails, code values etc. not suitable for spell checking.
SpellCheck
XML Name | SpellCheck |
GUI Name | Spell check |
Type | Boolean |
Required | No |
Description | If true (“Allow spell checking”), the text entered in the field will be spell-checked (Firefox and IE10 only). |
Possible values | True (“Allow spell checking”) / False (“Do not allow spell checking”) |
Default value | True |
The TextArea widget has allows you to choose whether the text entered will be spell-checked (Firefox only) based on the current language of the website. You should explicitly disable spell checking on fields that contain e-mails, code values etc. not suitable for spell checking.
SpellCheck
XML Name | SpellCheck |
GUI Name | Spell check |
Type | Boolean |
Required | No |
Description | If true (“Allow spell checking”), the text entered in the field will be spell-checked (Firefox and IE10 only). |
Possible values | True (“Allow spell checking”) / False (“Do not allow spell checking”) |
Default value | True |
The CheckBox widget has a label to its left copied from its corresponding property. You can also specify the label for the check box item. It will appear to its right.
ItemLabel
XML Name | ItemLabel |
GUI Name | Sub label |
Type | String |
Required | No |
Description | Text to the right of the check box on a form |
Possible values | Any valid string that can serve as a check box item label |
Default value | (none) |
The BoolSelector widget always specifies two options to choose from, which read “True” and “False” by default. You can override these defaults by modifying its corresponding parameters.
TrueLabel
XML Name | TrueLabel |
GUI Name | True label |
Type | String |
Required | Yes |
Description | A label that describes one of the two possible options. Use this parameter to specify a custom label for the True option. |
Possible values | Any valid string that can serve as a label for an option |
Default value | True |
FalseLabel
XML Name | FalseLabel |
GUI Name | False label |
Type | String |
Required | Yes |
Description | A label that describes one of the two possible options. Use this parameter to specify a custom label for the False option. |
Possible values | Any valid string that can serve as a label for an option |
Default value | False |
The VisualXhtmlEditor widget allows the user to create and edit XHTML formatted content for the field. It comes with a predefined set of class names used for formatting XHTML elements (“common”). If you have defined your own set of class names, you can specify it instead.
ClassConfigurationName
XML Name | ClassConfigurationName |
GUI Name | Class configuration name |
Type | String |
Required | No |
Description | A string used to configure the visual editor and offer the editor a special set of class names for formatting XHTML elements. |
Possible values | Any valid string that serve as the name of a predefined set of class names |
Default value | common |
With the DataIdMultiSelector widget you can use items in a data type as options in a list to choose from. Since the widget has two views – verbose for longer lists and compact for shorter ones, you can configure how to present the options by selecting the proper view.
OptionsType
XML Name | OptionsType |
GUI Name | Data type to select from |
Type | Type |
Required | Yes |
Description | A data type whose items will serve as the list of options to choose from |
Possible values | Any valid data type |
Default value | (none) |
CompactMode
XML Name | CompactMode |
GUI Name | Compact UI |
Type | Boolean |
Required | No |
Description | If true (“Compact”), a compact representation of long option lists will be used; otherwise, the full representation. |
Possible values | True (Compact) / False (Verbose) |
Default value | False (Verbose) |
Unlike the Selector widget used with other field types, the Selector widget used with the String type has a number of parameters to configure.
First of all, you can specify the option list to choose from by using a specific function that will return a simple enumerable list of such options (for example, Composite.Utils.String.Split) or an object with multiple properties (fields), for example a data type.
If the function returns an object with multiple properties, you should also choose which of the properties will supply values for options in the list (for example, “ID”) and which will supply labels for options in the list (for example, “Name”).
You can also make a selection of an option in a list required or optional. By allowing multiple selections and selecting the Compact or Verbose mode, you can change the way the options are presented to the user.
Options
XML Name | Options |
GUI Name | Options |
Type | IEnumerable (simple lists), Dictionary |
Required | Yes |
Description | A list of elements to use as options. |
Possible values | A call to a function that can return a list of options |
Default value | (none) |
KeyFieldName
XML Name | KeyFieldName |
GUI Name | Source key field name |
Type | String |
Required | No |
Description | A name of the property in the option source, whose values will be used as key values. In other words, if your option source returns a list of objects or XElements, this field specifies the name of the field (property) to use for key values. Leave this field empty to use the source option value as a string. |
Possible values | A valid string that specifies the name of the property in the option source, or an empty string (none) |
Default value | (none) |
LabelFieldName
XML Name | LabelFieldName |
GUI Name | Source key field label |
Type | String |
Required | No |
Description | A name of the property in the option source, whose values will be used as labels for options in the list. In other words, if your option source returns a list of objects or XElements, this field specifies the name of the field (property) to use for labels. Leave this field empty to use the source option value as a string. |
Possible values | A valid string that specifies the name of the property in the option source, or an empty string (none) |
Default value | (none) |
Required
XML Name | Required |
GUI Name | Selection required |
Type | Boolean |
Required | No |
Description | If true, the user is forced to select a value in the list; otherwise, no selection is allowed (“<NONE>”). This parameter has no effect if the Multiple selection parameter is set to True. |
Possible values | True / False |
Default value | True |
Multiple
XML Name | Multiple |
GUI Name | Multiple selection |
Type | Boolean |
Required | No |
Description | If true, the user can select none, one or more than one value in the list. The selected values will be joined in a comma-separated string like 'A,B,C'. If set to true, this feature disables the Selection required parameter. If set to true, it also changes the view of the widget from drop-down list to the compact or verbose list (as defined in the Compact mode parameter). |
Possible values | True / False |
Default value | False |
Compact
XML Name | Compact |
GUI Name | Compact mode |
Type | Boolean |
Required | No |
Description | If true, the UI element will be presented in a compact view; otherwise, the verbose view is used. This parameter has effect only when the Multiple selection parameter is set to True; otherwise, a drop-down list is used. |
Possible values | True (Compact) / False (Verbose) |
Default value | False (Verbose/Show all options) |
By default, the ImageSelector widget allows the user to select the images from the entire Media Archive (“All Media Files”).
To narrow the scope, you can choose a folder, from which the images will be only selected. You can also configure the widget so that the user can choose not to select any image in the list (“<NONE>”).
MediaFileFolderReference
XML Name | MediaFileFolderReference |
GUI Name | Image folder |
Type | DataReference<C1 Media Folder> |
Required | Yes |
Description | A media folder to choose images from. It also includes images from all subfolders. |
Possible values | Any valid path to a media folder |
Default value | All Media Files |
Required
XML Name | Required |
GUI Name | Selection required |
Type | Boolean |
Required | No |
Description | If true, selecting an image will be required; otherwise, optional (“<NONE>”). |
Possible values | True / False |
Default value | True |
By default, the MediaFileSelector widget allows the user to select the media from the entire Media Archive (“All Media Files”).
To narrow the scope, you can choose a specific folder, from which the media files will be only selected. You can further narrow the list of available media files by filtering the media files by their extensions as well as by indicating whether to include files from subfolders.
You can also configure the widget so that the user can choose not to select any media file in the list (“<NONE>”).
MediaFileFolderReference
XML Name | MediaFileFolderReference |
GUI Name | Media Folder |
Type | DataReference<C1 Media Folder> |
Required | Yes |
Description | A media folder to choose files from. |
Possible values | Any valid path to a media folder |
Default value | All Media Files. |
FileExtensionFilter
XML Name | FileExtensionFilter |
GUI Name | File extension filter |
Type | String |
Required | No |
Description | This parameter limits the list to files which have the specified extension. |
Possible values | A string that specifies any valid file extension |
Default value | (none) |
IncludeSubfolders
XML Name | IncludeSubfolders |
GUI Name | Include Subfolders |
Type | Boolean |
Required | No |
Description | If true, files from subfolders will be included in the list; otherwise, only files in the specified folder will be listed |
Possible values | True / False |
Default value | True |
Required
XML Name | Required |
GUI Name | Selection required |
Type | Boolean |
Required | No |
Description | If true, selecting a media file will be required; otherwise, optional (“<NONE>”). |
Possible values | True / False |
Default value | True |