Reference - UniGrid definition

cssclass

Specifies the name of a CSS class from the website's stylesheet that the control applies to the actions column.

"UniGridCustomActionsColumn"

parameters

A list of columns from the data source separated by semicolons. The UniGrid provides the specified columns as parameters in the onclick or menuparameter attributes of child <action> elements.

"AttachmentGUID;AttachmentFormGUID"

showheader

Indicates whether the UniGrid displays the header of the actions column. The default value is true.

width

Sets the width of the actions column in the UniGrid.

"30%"
"100px"

caption

Text used as the tooltip of the image defined in the icon attribute. You can enter the name of a resource string enclosed between $ characters.

"$General.Delete$"

commandargument

The name of the column whose value the action passes as the actionArgument parameter of OnAction event handlers.

If not defined, the action uses the first column in the source data.

confirmation

The text displayed in a JavaScript confirmation for the action. Most commonly used as a confirmation for delete type actions. You can enter the name of a resource string enclosed between $ characters.

"$General.ConfirmDelete$"

contextmenu

The relative path to a control (.ascx file) that implements a context menu for the action. Controls created for this purpose must inherit from the CMS.Base.Web.UI.CMSContextMenuControl class.

"~/CMSAdminControls/UI/UniGrid/Controls/ObjectMenu.ascx"

externalsourcename

Name of the action passed as the sourceName parameter of OnExternalDataBound event handlers.

"deletefile"

fonticonclass

Sets the action's image using a font icon. Enter the name of a CSS class that defines the font icon.

To use the default font icon classes, you need to link the system's CSS stylesheets onto the page containing the UniGrid – call the CMS.Base.Web.UI.CssRegistration.RegisterBootstrap(Page) method in the page's code behind.

Alternatively, you can set the action's image using a standard image file through the icon attribute.

"icon-eye"

fonticonstyle

Sets the color of the action's font icon (specified through the fonticonclass attribute). The default options are:

• default (gray)
• allow (green)
• warning (orange)
• critical (red)

"default"
"allow"
"warning"
"critical"

icon

Use the icon attribute to set the action's image using a standard image file (if you do not wish to use a font icon).

Specify the name of an image file located in the folder defined by the ImageDirectoryPath property of the UniGrid.

"delete.png"

menuparameter

Contains an array of parameters passed to the control implementing the action's context menu (the path to this control must be specified in the contextmenu attribute). You can retrieve these parameter in the control's code using the GetContextMenuParameter JavaScript function.

You can insert the values of columns defined in the parameters attribute of the parent <actions> element using the following expressions:

{0} - first parameter {1} - second parameter

and so forth.

"new Array('cms.site', '{0}')"

mousebutton

Specifies which mouse button causes the action's context menu to appear (if a context menu is enabled via the contextmenu attribute).

If not defined, both mouse buttons open the context menu.

"left"
"right"

name

Identifies the action in the code that implements the functionality of the UniGrid's actions. The system passes the action name to handlers of the OnAction event through the actionName parameter.

Predefined UniGrid actions

If the UniGrid has an object type data source (specified either through the <objecttype> element or the ObjectType property), you can use the following predefined actions without writing any code:

• #delete - deletes the object displayed on the given UniGrid row (removes the object from the Kentico database). The action automatically requires users to have the Delete permission for the given object type.

• #destroyobject - deletes the object and its version history (the object cannot be restored from the system's recycle bin). The action automatically requires users to have the Delete permission for the given object type.

• #move / #moveup / #movedown - moves items within ordered lists of objects. The #move action allows drag and drop to any position, #moveup and #movedown switch objects with the previous or next item in the list.

  • • Only works if the object type has a defined order for the data records (uses a database column to store the item order).
    • The actions automatically require users to have the Modify permission for the given object type.
    • Sorting must be disabled for all columns in the UniGrid to ensure that the order is displayed correctly. Disable the AllowSorting attribute of the options element or the allowsorting attribute of individual column elements.
    • All items in the UniGrid's data must belong to the same order. If the object type contains multiple subsets of objects that each have their own separate order, you need to filter the data to include only items that belong to a single order (for example through the UniGrid control's WhereConditon property).

"delete"

onclick

The JavaScript OnClick function for the given action

You can insert the values of columns defined in the parameters attribute of the parent <actions> element using the following expressions:

{0} - first parameter {1} - second parameter

and so forth.

"alert(‘{0}’);"

modulename

Add this attribute (and the permissions or uielements attributes) to leverage the Kentico security model for the action. You can make the action usable only by a limited group of users.

Enter the code name of the module related to the action. You can find information about modules, their permissions and UI elements in the Modules application of the Kentico administration interface.

"cms.ecommerce"

permissions

Sets the code name of the permission that users must have to perform the action. The permission must belong to the module specified in the modulename attribute.

"modifyorders"

uielements

Sets the UI element that users must be allowed to view in order to perform the action. The user interface element must belong to the module specified in the modulename attribute.

"orders.general"

hideifnotauthorized

Indicates whether the UniGrid completely hides the action for users who are not allowed to perform it (as defined by the attributes above).

caption

Text displayed in the button, and also used as the button's tooltip. You can enter the name of a resource string enclosed between $ characters.

"$Button.Caption$"

buttonclass

CSS class (or classes) from the website's stylesheet that the UniGrid uses to style the appearance of the action button.

"btn btn-secondary"

buttonstyle

Styles the appearance of the action button based on a set of predefined options:

• Primary (green)
• Default (gray)
• None (styling then relies on custom classes specified via the buttonclass attribute)

To use the default button styles, you need to link the system's CSS stylesheets onto the page containing the UniGrid – call the CMS.Base.Web.UI.CssRegistration.RegisterBootstrap(Page) method in the page's code behind.

"Primary"
"Default"
"None"

behavior

Determines whether the mass action redirects users to a different page or opens a modal dialog. The corresponding values are:

• redirect
• openmodal

In both cases, the URL of the target page or dialog must be set through the url attribute or indirectly using a predefined mass action.

"redirect"
"openmodal"

caption

Sets the text displayed in the mass action selector. You can enter the name of a resource string enclosed between $ characters.

"$General.Delete$"

name

Identifier of the mass action (required for all mass actions).

Allows you to specify predefined mass actions. Predefined mass actions do not require development of additional pages or components and have an automatic url value.

• #delete - deletes the selected objects (removes the objects from the Kentico database). The action automatically requires users to have the Delete permission for the given object type.

"#delete"

url

Sets the URL of the page or modal dialog that opens when a user performs the mass action. Not necessary for predefined mass actions.

The target page must contain the logic that performs the mass action.

"~/CMSAdminControls/UI/UniGrid/Pages/MassDelete.aspx"

action

Sets the name of an action that the UniGrid performs when a user clicks the content of the column's cells. You need to define an action with a matching name via the name attribute of an <action> element.

allowsorting

Indicates whether the column can be used to sort the rows of the UniGrid.

Note: To disable sorting for all columns in the UniGrid, set the AllowSorting attribute of the options element to false.

caption

Specifies the text displayed as the header for the column. You can enter the name of a resource string enclosed between $ characters.

"$general.name$"

commandargument

The name of the column whose value the column passes as the actionArgument parameter of OnAction event handlers (if the column uses an action specified via the action attribute).

If not defined, the action uses the first column in the source data.

cssclass

Specifies the name of a CSS class from the website's stylesheet that the UniGrid uses to style the appearance of the column.

"UniGridCustomColumn"

externalsourcename

Sets a name for the column that the control passes as the sourceName parameter of OnExternalDataBound event handlers. You can use such handlers to implement custom functionality in the column's cells.

Using column transformations

The UniGrid provides built-in transformation functions that allow you to format the column's content without writing any code. You can assign the following values into the externalsourcename attribute by default:

• #yesno - applies to columns with a bit (boolean) type data source. Converts the values to text: Yes (colored green) or No (colored red).
• #yes - applies to columns with a bit (boolean) type data source that have a true value (1). Displays:  Yes (colored green).
• #isnullyesno - displays Yes (colored green) if the column's value is null or DBNull, No (colored red) for all other values.
• #sitename - converts site ID (integer) values into site display names.
• #sitenameorglobal - converts site ID values into site display names. If a record is not related to a specific site (i.e. the site ID is null), the cell displays (global) as its value.
• #countryname - converts ID (integer) values into the display name of the Country object with the given ID.
• #culturename - converts culture code text values into the full name of the matching culture. Other available variants are #cultureshortname and #culturenamewithflag.
• #username - converts ID (integer) values into the user name of the User account with the given ID.
• #classname - converts ID (integer) values into the display name of the Kentico class with the given ID.
• #htmlencode - HTML encodes text values.
• #url - converts URL text values into links.
• #mailto - converts email addresses into links.
• #filesize - recalculates file size values in bytes to values in kilobytes (kB), megabytes (MB), gigabytes (GB), etc.
• #date - formats datetime values to display only the date, without the time. For example: 4/15/2013
• #time - formats datetime values to display only the time, without the date. For example: 7:58:39 AM
• #userdatetime - modifies datetime values according to the time zone settings of the user viewing the page.
• #usertime - formats datetime values to display only the time, without the date. The function modifies the time according to the time zone settings of the user viewing the page.
• #userdatetimegmt - modifies datetime values according to the time zone settings of the user viewing the page and displays the difference from GMT.
• #usertimezonename - displays the name of the time zone configured for the user viewing the page.
  For example: Arizona (GMT - 07.00)

You can also Register custom UniGrid transformations.

To set default values for functions, add the "|" character as a separator and specify the value. For example: #username|None. The column uses the default value if the result of the function is null or an empty string.

You can also specify custom transformation expressions for columns that contain the ID values of other objects. For example, you can use the following externalsourcename values for user ID columns:

• #transform: cms.user.fullname - displays the full name of each user instead of the ID.
• #transform: cms.user : {%FullName%} ({%UserName%}) - loads the user object with the matching ID for each row and formats it according to the entered macro expressions, e.g. Andrew Jones (Andy).

If a user decides to sort the UniGrid according to a column with an ID transformation, the order of the rows is based on the ID values, not the output of the transformation.

"user_modify"
"#yesno"
"#culturename|{$general.default$}"

href

If you enter a URL here, the UniGrid generates a link to the given URL around the content of the column's cells. Macros {0}, {1}, ... can be used to access parameters defined by the parameters attribute.

"~/page.aspx"

icon

Name of an image that the UniGrid displays in column cells after the content loaded from the data source. The image must be located in the folder defined by the ImageDirectoryPath property of the UniGrid.

"edit.png"

istext

Indicates whether the content of the column is of type Text or nText. The UniGrid generates a special OrderBy clause according to this attribute's value, so you need to set it correctly to enable sorting for the column.

localize

Indicates whether the column supports localization for string values.

maxlength

Sets the maximum number of characters that can be displayed in the column's cells. The last 3 characters are replaced by periods.

columnname
(name in markup)

Sets a custom name for the column, which the UniGrid uses in the column dictionary accessible through the NamedColumns property.

parameters

Specifies the names of columns from the data source, which can be used as parameters in the URL generated by the Href attribute. Separated by semicolons.

source

Name of the column from the data source that the UniGrid uses as the source for the column's content.

Use the ##ALL## macro to specify all columns in the data source.

sort

Defines the column name that the UniGrid uses for sorting if you enter the ##ALL## macro into the source attribute.

style

CSS style applied to the entire column.

"padding:10px"

visible

Indicates whether the column is visible.

width

Determines the width of the column.

"20%"
"200px"

wrap

Indicates whether the column uses word wrapping.

encode

Indicates whether the output of the tooltip is HTML encoded.

externalsourcename

Name used to identify the tooltip through the sourceName parameter of handlers of the UniGrid's OnExternalDataBound event. You can use a handler to customize the appearance of the tooltip.

source

Name of the column from the UniGrid's data source that is used as the source for the tooltip's content.

width

Determines the width of the tooltip.

defaultvalue

Specifies a default values that the UniGrid presets in the filter when the page is loaded. The value must match the type of the filter.

fieldname

Sets a custom name that can be used to identify the given filtering field in the form used by the default UniGrid filter. You can work with the field using the FilterForm property of the UniGrid.

For example:

// Hides the filtering field with the "customField" fieldname value in the default UniGrid filter
UniGrid.FilterForm.FieldsToHide.Add("customField");

format

Allows you to define a custom format for the WHERE clause that the default filter generates for the column. You can use the following dynamic expressions:

{0} - returns the name of the associated column (or the value of the filter element's source attribute) {1} - returns the operator selected in the default filter's drop‑down list {2} - returns the filtering value (entered into the default filter's textbox)
{3} - resolves into the default WHERE condition

The default WHERE condition is [{0}] {1} {2}, but automatically adds:

• Single quotes around string values
• The N prefix to string values if required
• % wildcards around string values for LIKE operators
• is null conditions for inequality operators

" [{0}] {1} N'%{2}%' "

path

Assigns a custom filter for the column instead of the default UniGrid filter. Enter the path to the user control (.ascx file) that implements the filter.

• If set, the filter ignores the type attribute.
• The default relative path is ~/CMSAdminControls/UI/UniGrid/Filters/.

For more information, see: Creating custom UniGrid filters

size

Determines the maximum amount of characters that users can enter into the textbox of the default filter.

• Available for Text, Integer, Double and Decimal filter types.
• The default value is 1000.

source

Sets the name of the column used in the WHERE clause generated by the filter.

type

Determines the filter type that the UniGrid creates for the given column. We recommend setting the value according to the data type of the column: text, bool, integer, double or decimal

If your UniGrid control uses an object type data source, you can filter the objects according to their site bindings:

1. Add a <filter> element under any column (the data of the column is not used)
2. Set the value of the type attribute to site.

"text"
"bool"
"integer"
"double"
"decimal"
"site"

columns

Names of the object type's columns that the UniGrid retrieves.

• Separate the columns using commas.
• If empty, all the UniGrid retrieves all columns.

By default, the values of the first column are passed as the actionArgument parameter of the UniGrid's OnAction event handlers. You can override this column in the definition by specifying a column name in the commandargument attribute of individual <action> or <buttonaction> elements.

name

Must contain the object type value for the given type of Kentico object. To find a list of available object type values, open the System application in the Kentico administration interface and select the Object types tab.

"cms.user"

columns

Names of the columns that the query retrieves.

• Separate the columns using commas.
• If empty, all the query retrieves all columns.

By default, the values of the first column are passed as the actionArgument parameter of the UniGrid's OnAction event handlers. You can override this column in the definition by specifying a column name in the commandargument attribute of individual <action> or <buttonaction> elements.

name

Must contain the code name of the used system query in format: <class name>.<query name>

"cms.site.selectsitelist"

name

Sets the name of the parameter. Insert parameters into queries using the following syntax: @<paramater name>

For example, if your query looks like this:

SELECT TOP @customTop FROM CMS_User

You need to enter customTop into the name attribute. The query then uses the value of the parameter element instead of the @customTop expression.

type

The type of the parameter.

"String"
"Int"
"Double"
"Decimal"
"Bool"

value

The value of the parameter.

DisplayPager

Indicates if the UniGrid displays a pager. True by default.

DefaultPageSize

Defines the default amount of rows displayed on one UniGrid page. If the value is not included among the options defined by the PageSizeOptions key, the system automatically inserts the value as an additional option.

PageSizeOptions

Can be used to override the default values offered by the page size selector. Values must be separated by commas.

You can use the ##ALL## value to add an option that lists all available rows on a single page (not recommended if you have objects with a very large number of records).

The default values are defined by the CMSDefaultPageSizeOptions web.config key (5,10,25,50,100 if it is not set).

ShowDirectPageControl

If true, the pager displays a textbox that allows users to change the page directly by entering a number.

If all three page navigation keys (ShowDirectPageControl, ShowFirstLastButtons, ShowPreviousNextButtons) are false, the UniGrid only loads a limited number of records based on the configured page size.

ShowFirstLastButtons

If true, the pager includes links to the first and last page (if there is a large enough number of items). False by default.

If all three page navigation keys (ShowDirectPageControl, ShowFirstLastButtons, ShowPreviousNextButtons) are false, the UniGrid only loads a limited number of records based on the configured page size.

ShowPageSize

If true, the pager displays the page size selector.

ShowPreviousNextButtons

If true, the pager displays buttons that link to the previous and next page.

If all three page navigation keys (ShowDirectPageControl, ShowFirstLastButtons, ShowPreviousNextButtons) are false, the UniGrid only loads a limited number of records based on the configured page size.

ShowPreviousNextPageGroup

If true, the pager displays links to the previous and next groups of page links.

VisiblePages

Determines the amount of page links displayed in one group.

AllowSorting

If true, users can sort the rows displayed by the UniGrid according to the values of individual columns (depending on the settings of the allowsorting attribute of the column elements). If false, sorting is always disabled for all columns.

The default value is true.

DisplayFilter

Indicates whether the UniGrid displays a filter above the grid. If the number of displayed rows is lower than the value of the FilterLimit key, the filter is hidden despite this setting.

FilterLimit

The UniGrid displays the filter only if the number of displayed rows is greater than or equal to this key's value. The default value is loaded from the CMSDefaultListingFilterLimit web.config key.

FilterPath

Allows you to replace the whole default UniGrid filter with your custom filter. Enter the path to the user control (.ascx file) that implements the filter.

• If set, individual filter settings for columns are ignored.

For more information, see: Creating custom UniGrid filters

ShowSelection

Indicates whether the UniGrid displays a column that allows users to select the rows of the grid. You can use selection to perform mass actions that affect multiple rows.

You can access the selected rows in the API through the SelectedItems property of the UniGrid.

Note: The selection column is automatically enabled if the UniGrid definition contains at least one massaction element.

SelectionColumn

Sets the name of the column from which the UniGrid loads values into the array of selected rows. You can access the array of selected rows through the SelectedItems property of the UniGrid.

By default the UniGrid uses the first column in the data source.

ShowSortDirection

Determines if the UniGrid displays an arrow showing the current sorting direction in the header of the column used for sorting.