---
title: Reference - UniGrid definition
related:
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/adding-custom-unigrid-transformations.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/creating-custom-unigrid-filters.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
The [UniGrid](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md) is a complex control, so you need to explicitly define the design, content and many other configuration options. You can use two different approaches:
- An external XML configuration file, assigned through the UniGrid's **GridName** property
- ASPX markup directly within the UniGrid control definition (on the page or user control containing the UniGrid)
## Using external XML files
Organize the UniGrid XML configuration file according to the following structure (some elements are optional):
```html
...
...
...
...
...
...
...
...
```
## Using ASPX markup
To define the UniGrid directly in the ASPX markup, you first need to register the following namespace on the web form or user control (in addition to the UniGrid user control):
```html
<%@ Register Namespace="CMS.UIControls.UniGridConfig" TagPrefix="ug" Assembly="CMS.UIControls" %>
```
Then add elements inside the UniGrid control tags according to the following structure:
```html
...
...
...
...
...
```
> **Info:** **Notes**
>
> - When using markup, you need to specify the data source of the control directly through the UniGrid's properties (**Query**, **ObjectType** or **DataSource**).
> - You can use the IntelliSense in Visual Studio to help find the appropriate elements and attributes.
## UniGrid elements
The following reference describes all elements that you can define for UniGrid controls (and their attributes):
- [Actions (GridActions)](#referenceunigriddefinition-actions)
- [Action (ug:Action)](#referenceunigriddefinition-action)
- [ButtonAction (ug:ButtonAction)](#referenceunigriddefinition-buttonaction)
- [Mass actions (GridMassActions)](#referenceunigriddefinition-massactions)
- [Mass action (ug:MassAction)](#referenceunigriddefinition-massaction)
- [Columns (GridColumns)](#referenceunigriddefinition-columns)
- [Column (ug:Column)](#referenceunigriddefinition-column)
- [Tooltip](#referenceunigriddefinition-tooltip)
- [Filter](#referenceunigriddefinition-columnfilters)
- [Object type](#referenceunigriddefinition-objecttype)
- [Query](#referenceunigriddefinition-query)
- [Parameter](#referenceunigriddefinition-queryparameter)
- [Pager (pagerConfig)](#referenceunigriddefinition-pager)
- [Options (GridOptions)](#referenceunigriddefinition-options)
### ()
The _actions_ element defines a column with various actions (Edit, Delete, View, etc.) for every row of the UniGrid, represented by icons. Individual actions must be defined by child **** elements.
| Actions attributes | Description | Sample value |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| 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 **** 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" |
#### ()
_Action_ elements define individual actions offered by the UniGrid. Visually, actions have the form of an icon or image. You can alternatively use [ButtonAction](#referenceunigriddefinition-buttonaction) elements.
- Implement the functionality of individual actions through handlers of the UniGrid's **OnAction** event. See: [UniGrid - Getting started](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md#getting-started)
- You can add advanced logic for individual actions buttons in handlers of the UniGrid's **OnExternalDataBound** event (for example, defining for which rows the actions are available). See: [UniGrid - Implementing custom functionality](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md#implementing-custom-functionality)
| Action attributes | Description | Sample value |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| caption | Text used as the tooltip of the image defined in the **icon** attribute. You can enter the name of a [resource string](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md) 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](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md) 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](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/working-with-font-icons.md). 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 **** 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 __ 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 Xperience 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 **** element using the following expressions:
**{0}** - first parameter **{1}** - second parameter
and so forth. | "alert(‘{0}’);" |
| Action security | | |
| modulename | Add this attribute (and the _**permissions**_ or _**uielements**_ attributes) to leverage the Xperience 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 Xperience 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). | |
> **Note:** **Default object menu actions**
>
> If your UniGrid control uses an object type data source (specified either through the __ definition element or the **ObjectType** property), the grid automatically displays an action that opens a context menu when clicked. This menu provides options that allow users to Export, Backup, Restore or Destroy the listed objects. Some types of objects do not support all menu options.
>
> The UniGrid does not add the default object menu action if you manually specify another action with a **contextmenu** attribute, or if there are no actions at all defined for the grid. You can also disable the menu action by setting the **ShowObjectMenu** property of the UniGrid to _false_.
#### ()
_ButtonAction_ elements define individual actions offered by the UniGrid. Button actions are an alternative to [Action](#referenceunigriddefinition-action) elements. Use the approach described for _Action_ elements to implement button actions.
_ButtonAction_ elements provide most of the same configuration attributes as _Action_ elements. The _fonticonclass_, _fonticonstyle_, and _icon_ attributes are not available, and the following differences apply:
| ButtonAction attributes | Description | Sample value |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- |
| caption | Text displayed in the button, and also used as the button's tooltip. You can enter the name of a [resource string](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md) 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" |
### ()
The _massactions_ element is a container for the definitions of actions that can apply to multiple UniGrid rows. The element itself has no attributes – each mass action has its own settings. Define individual mass actions by adding child **** elements.
#### ()
_Massaction_ elements represent actions that can apply to multiple UniGrid rows. If you define at least one mass action:
- The UniGrid automatically displays a column that allows users to select rows.
- The following mass action controls are displayed below the UniGrid's main item listing and pager: Scope selector (all items or selected items), Mass action selector, OK button
| Massaction attributes | Description | Sample value |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| 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](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md) 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 Xperience 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" |
### ()
The _columns_ element represents the main content of the UniGrid. The __ element itself has no attributes, since each column has its own settings. Define individual columns by adding child **** elements.
#### ()
_Column_ elements define the UniGrid's columns. You can implement advanced formatting logic for the cells in columns in handlers of the UniGrid's **OnExternalDataBound** event. See: [UniGrid - Implementing custom functionality](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md#implementing-custom-functionality)
Columns can contain child **** and **** elements.
| Column attributes | Description | Sample value |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| 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 **** 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](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface/working-with-resource-strings.md) 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 Xperience 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](https://docs.kentico.com/13/configuring-xperience/configuring-time-zones.md) 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](https://docs.kentico.com/13/configuring-xperience/configuring-time-zones.md) 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](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/adding-custom-unigrid-transformations.md).
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](https://docs.kentico.com/13/multilingual-websites/setting-up-a-multilingual-user-interface.md) 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. | |
#####
If you add a _tooltip_ element under a column, the UniGrid displays a tooltip when a user hovers over the content of the column's cells. If an icon is present in the cell, the tooltip is displayed over the icon instead of the text.
| Tooltip attributes | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
#####
If you add a _filter_ element under a column, the UniGrid uses the given column in the filter.
| Filter attributes | Description | Sample value |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| 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](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/creating-custom-unigrid-filters.md) | |
| 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:
Add a **** element under any column (the data of the column is not used)
Set the value of the **type** attribute to _site_. | "text"
"bool"
"integer"
"double"
"decimal"
"site" |
###
The _objecttype_ element defines the type of the Xperience objects that the UniGrid loads and displays.
> **Note:** **Note**: Object type data sources are not supported for objects representing pages. In these cases, you can load the required data:
>
> - Through the **** element.
> - By assigning a data source manually through the UniGrid control's **DataSource** property (before its _ReloadData()_ method is called).
| Objecttype attributes | Description | Sample value |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| 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 **** or **** elements. | |
| name | Must contain the object type value for the given type of Xperience object. To find a list of available object type values, open the **System** application in the Xperience administration interface and select the **Object types** tab. | "cms.user" |
###
The __ element specifies the query that retrieves the data displayed in the UniGrid from the Xperience database. The query element can contain **** child elements.
> **Info:** To work with the system's queries:
>
> 1. In the Xperience administration interface, open the **Modules** application.
> 2. Edit the related module.
> 3. Open the **Classes** tab.
> 4. Edit the related class.
> 5. Manage the queries on the **Queries** tab.
You can alternatively assign the UniGrid's data source:
- Through the **** element.
- Through the UniGrid control's **Query** or **ObjectType** properties.
- By assigning an external data source in the UniGrid control's **DataSource** property (before its _ReloadData()_ method is called).
| Query attributes | Description | Sample value |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| 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 **** or **** elements. | |
| name | Must contain the code name of the used system query in format: _._ | "cms.site.selectsitelist" |
> **Tip:** **Tip**: When using a __ data source together with UniGrid actions that target specific objects in the list (editing, deleting, etc.), you need to specify the ID column of the given data as an action argument. Use one of the following options:
>
> - List all required data columns in the __ element's **columns** attribute, with the ID column first
> - Set the **parameters** attribute of the definition's __ element, and include the ID column there
> - Set the **commandargument** attribute of individual __ elements in the definition to the name of the ID column
####
_Parameter_ elements allow you to define the values of parameters for the parent __ element.
| Parameter attributes | Description | Sample value |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| name | Sets the name of the parameter. Insert parameters into queries using the following syntax: _@_
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. | |
### ()
The pager element defines the behavior of the UniGrid pager. You can either add the settings as child **** elements in the UniGrid's XML configuration file, or as attributes of the __ element directly in the control's markup.
The following settings are available:
| Key name | Description | Sample value |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| 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. | |
### ()
The options element configures additional settings and special features of the UniGrid control. You can either add the settings as child **** elements in the UniGrid's XML configuration file, or as attributes of the **** element directly in the control's markup.
The following settings are available:
| Key name | Description | Sample value |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| 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](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/creating-custom-unigrid-filters.md) | |
| 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. | |