Configuration

The following properties of the UniSelector control can be set or used in the API:

Property Name

Description

Sample Value

AdditionalColumns

Contains the names of columns that should be loaded with the objects of the specified data class in addition to those required by default.

AllowAll

Indicates whether the selector allows the all value.

AllowEditTextBox

Indicates whether the value of the TextBox displayed in SingleTextBox or MultipleTextBox SelectionMode can be manually edited.

AllowEmpty

Indicates whether the selector allows an empty value.

If enabled, the (none) value is available in SingleDropDownList SelectionMode and the Clear button is displayed in SingleTextBox and MultipleTextBox mode.

When an empty value is used, the Value of the control is by default 0 in SingleDropDownList SelectionMode or an empty string in the remaining modes.

AllRecordValue

Contains the value used when the (all) item is selected in SingleDropDownList SelectionMode. The default value is -1.

ButtonImage

Can be used to enter a path to an image. If specified, the selection button is displayed as a LinkButton using this image. Only applies if the SelectionMode is SingleButton or MultipleButton.

"~/App_Themes/Default/Images/SampleImage.png"

CacheMinutes

Number of minutes that the content of the control is cached for, so that it doesn't have to be retrieved from the database each time a user requests the page.

Zero indicates that caching will not be used.

-1 indicates that the site-level settings should be used.

Please refer to the Caching topic to learn more.

DialogWindowHeight

Determines the default height of the opened selection window.

DialogWindowName

Can be used to specify the name of the selection window to prevent conflicts between multiple UniSelector controls.

DialogWindowWidth

Determines the default width of the opened selection window.

DisplayNameFormat

Used to modify the format of the display names of objects in the selection list.

To correctly display values dependant on individual objects, macro expressions in format {%ColumnName%} must be used here. The columns required by the used macros are loaded automatically.

"{%FullName%}, {%Email%}"

EditItemPageUrl

Can be used to specify the URL of a custom page that handles the editing of the selected object. If a value is entered, an edit button that links to the specified URL is displayed. Only available for SingleTextBox and SingleDropDownList SelectionMode.

The URL may contain macros in format ##<ITEM>ID##, which will be resolved into the value of the selected object's ID column. For example, <url>?userid=##USERID## would contain the ID of the currently selected user for a UniSelector set to use the cms.user ObjectType.

EditWindowName

Can be used to specify the name of the object editing window to prevent conflicts between multiple UniSelector controls.

EmptyReplacement

Contains a string that is used in the selection list as a replacement value for objects whose display name column is empty.

"N/A"

Enabled

Indicates whether the control is enabled.

EnabledColumnName

Can be used to specify the name of the column that determines if the selected object is enabled.

FilterControl

Path to the filter control (.ascx file; must inherit from the CMSAbstractBaseFilterControl class) that will be used for custom filtering of objects in the selection window.

"~/CMSFormControls/Filters/CustomFilter.ascx"

GridName

Path to the XML configuration file of the UniGrid control used to display and select objects in Multiple SelectionMode.

IconPath

Can be used to enter the path to the image used in the title of the selection window.

ItemsPerPage

Can be used to set the maximum amount of displayed selected items per page in Multiple SelectionMode.

LocalizeItems

Indicates whether localization macros should be resolved in the control.

MaxDisplayedItems

Determines the maximum amount of objects displayed in the list in SingleDropDownList SelectionMode. The default value is 25.

NewItemPageUrl

Can be used to specify the URL of a custom page that handles the creation of new objects. If a value is entered, a new button that links to the specified URL is displayed. Only available for SingleTextBox SelectionMode.

NoneRecordValue

Contains the value used when the (none) item is selected in SingleDropDownList SelectionMode. The default value is 0.

ObjectType

Specifies the data class of the objects to be selected.

"cms.user"

OrderBy

Contains the ORDERBY clause used to determine the order of objects. Also affects the order in the selection window.

RemoveConfirmation

Can be used to specify the text displayed in the confirmation message displayed when removing selected items from the UniSelector. Entering an empty string disables the confirmation message.

ResourcePrefix

Determines the prefix that is used in the full names of resource strings (Keys) containing the labels of the various interface elements displayed by the UniSelector. This can be used to assign custom strings to the control.

Custom strings can be created at CMS Site Manager -> Development -> UI cultures -> ... edit () a UI culture ... -> Strings. The keys of these strings must use the following format:

The following string names are available for the UniSelector:

•	additems - text caption of the add items button used to open the selection window in Multiple mode

•	all - name of the list item representing the selection of all available objects in SingleDropDownList mode

•	clear - text caption of the clear button used in TextBox modes

•	edit - text caption of the edit button used in SingleTextBox and SingleDropDownList mode

•	empty - name of the list item representing an empty selection in SingleDropDownList mode

•	itemname - header text of the column containing the names of objects in the selection window and the UniGrid displaying selected objects in Multiple mode

•	moreitems - name of the list item that opens the selection window if the maximum amount of list items is exceeded in SingleDropDownList mode

•	new - text caption of the new button used in SingleTextBox mode

•	newitem - name of the list item that opens the new item page in SingleDropDownList mode

•	nodata - text message displayed in Multiple mode if no objects are selected and the ZeroRowsText property is not defined

•	pleaseselectitem - text of the JavaScript alert displayed when the edit button is used when no object is selected

•	removeall - text caption of the button used to deselect all objects in Multiple mode

•	removeselected - text caption of the button used to deselect the specified objects in Multiple mode

•	select - text caption of the select button used to open the selection window in TextBox and Button modes

•	selectitem - text of the labels associated with the action elements used by the UniSelector; this is also used to set the title of the selection window

"mycustom"

ReturnColumnName

Specifies the name of the column used for the values of selected objects by the UniSelector. If empty, the ID column is used.

To ensure correct functionality of the control, the column must be a unique identifier for the given object type.

SelectionMode

Determines the design of the selection dialog displayed by the control. The value of this property affects the behaviour of many of the other properties of the UniSelector control.

The following modes are available:

•	SingleTextBox - consists of a button that allows the selection of one object and a TextBox displaying the selected value.

•	MultipleTextBox - consists of a button that allows the selection of multiple objects and a TextBox displaying the selected values.

•	SingleDropDownList - displays a drop‑down list containing objects. If necessary, the selection window can be opened by selecting (more items ...) from the list.

•	Multiple - consists of a UniGrid control displaying the selected objects and buttons that can be used to add or remove them.

•	SingleButton - consists of a button that allows the selection of one object.

•	MultipleButton - consists of a button that allows the selection of multiple objects.

"SingleTextBox"

"MultipleTextBox"

"SingleDropDownList"

"Multiple"

"SingleButton"

"MultipleButton"

SpecialFields

Can be used to get or set a two dimensional string array that contains custom items to be displayed in SingleDropDownList SelectionMode. The first value in the array is the name of the item in the list, the second represents the value of that item when it is selected.

UseDefaultNameFilter

Indicates whether the default name filter should be used in the selection window. Can be used to disable the default filter if a custom filter is specified through the FilterControl property.

Value

Can be used to get or set the selected value of the control. The column that is used for the values of selected objects can be specified in the ReturnColumnName property.

ValuesSeparator

Specifies the character used to separate selected values in the case of multiple selection. A semicolon (" ; ") is used by default.

WhereCondition

Contains the WHERE clause used for the list of objects available for selection.

ZeroRowsText

Can be used to specify the text displayed when no objects are selected in Multiple SelectionMode.

The following events of the UniSelector control are available:

Event Name

Description

OnItemsSelected

Occurs when an object or objects are selected in SingleButton and MultipleButton Selection Mode. This event is not raised in other modes.

OnSelectionChanged

Occurs when the set of selected objects is changed. The event is not raised in SingleButton or MultipleButton SelectionMode and may not always be triggered in TextBox modes depending on how the selection is changed.

This event is usually used to perform tasks with selected objects in Multiple mode without the need for a confirmation button.

Page url: http://devnet.kentico.com/docs/5_5r2/controls/index.html?uniselector_configuration.htm