Reference - UniGrid definition

The UniGrid 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):

Important: The names of elements and their attributes in UniGrid XML configuration files are case sensitive. In most cases, the names must be written in lower case (with the exception of the <columns><column><filter><Parameters> element).




<?xml version="1.0" encoding="utf-8" ?>
<grid>

    <actions>
        <action />
        ...
    </actions>

    <columns>
        <column>
            <tooltip />
            <filter>
                <Parameters>
                    <filterparameter />
                    ...
                </Parameters>
            </filter>
        ...
        </column>
      ...
    </columns>

    <objecttype />

    <query>
        <parameter />
        ...
    </query>

    <pager>
        <key name="DefaultPageSize" value="10" />
        ...
    </pager>

    <options>
        <key name="DisplayFilter" value="true" />
        ...
    </options>

</grid>

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




<%@ Register Namespace="CMS.UIControls.UniGridConfig" TagPrefix="ug" Assembly="CMS.UIControls" %>

Then add elements inside the UniGrid control tags according to the following structure:




<cms:UniGrid runat="server" ID="UniGrid" ... >

    <GridActions>
        <ug:Action />
        ...
    </GridActions>

    <GridColumns>
        <ug:Column>            
            <Tooltip />
            <Filter>
                <CustomFilterParameters>          
                    <ug:FilterParameter />
                    ...
                </CustomFilterParameters>
            </Filter>
            ...
        </ug:Column>
        ...
    </GridColumns>

    <PagerConfig DisplayPager="true" ... />

    <GridOptions DisplayFilter="true" ... />

</cms:UniGrid>

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)
- Action (ug:Action)
Columns (GridColumns)
- Column (ug:Column)
  - Tooltip
  - Filter
Object type
Query
- Parameter
Pager (pagerConfig)
Options (GridOptions)

<actions> (<GridActions>)

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 <action> 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 <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”

<action> (<ug:Action>)

Action elements define individual actions offered by the UniGrid.

Implement the functionality of individual actions through handlers of the UniGrid’s OnAction event. See: UniGrid - 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

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 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.ExtendedControls.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.Helpers.CSSHelper.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}’);”
Action security
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).

Default object menu actions

If your UniGrid control uses an object type data source (specified either through the <objecttype> 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.

<columns> (<GridColumns>)

The columns element represents the main content of the UniGrid. The <columns> element itself has no attributes, since each column has its own settings. Define individual columns by adding child <column> elements.

<column> (<ug:Column>)

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

Columns can contain child <tooltip> and <filter> 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 <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.

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.

<filter>

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
size	Determines the maximum amount of characters that users can enter into the textbox of the default filter. Available for Text, Integer and Double 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. It is recommended to set the value according to the data type of the column: text, bool, integer or double. If your UniGrid control uses an object type data source, you can filter the objects according to their site bindings: Add a <filter> 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” “site”

<objecttype>

The objecttype element defines the data class of the Kentico objects that the UniGrid loads and displays. You can find a list of all available data classes and related information in the CMS_Class database table.

Note: Object type data sources are not supported for classes representing page types (i.e. those whose value in the ClassIsDocumentType column is 1). In these cases, you can load the required data:

Through the <query> element
By assigning a data source manually through the UniGrid control’s DataSource property (before its ReloadData() method is called).

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

name

Must contain the code name of the data class.

“cms.user”

<query>

The <query> element specifies the query that retrieves the data displayed in the UniGrid from the Kentico database. The query element can contain <parameter> child elements.

To work with the system’s queries:

In the Kentico administration interface, open the Modules application.
Edit the related module.
Open the Classes tab.
Edit the related class.
Manage the queries on the Queries tab.

You can alternatively assign the UniGrid’s data source:

Through the <objecttype> 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).

columns

Names of the columns that the query retrieve.

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

name

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

“cms.site.selectsitelist”

Tip: When using a <query> 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 <query> element’s columns attribute, with the ID column first
Set the parameters attribute of the definition’s <actions> element, and include the ID column there
Set the commandargument attribute of individual <action> elements in the definition to the name of the ID column

<parameter>

Parameter elements allow you to define the values of parameters for the parent <query> element.

Parameter attributes	Description	Sample value
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” “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 <key> elements in the UniGrid’s XML configuration file, or as attributes of the <PagerConfig> 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.	<key name=“DisplayPager” value=“false” />
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.	<key name=“DefaultPageSize” value=“10” />
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).	<key name=“PageSizeOptions” value=“10,50,200” />
ShowDirectPageControl	If true, the pager displays a textbox that allows users to change the page directly by entering a number.	<key name=“ShowDirectPageControl” value=“true” />
ShowFirstLastButtons	If true, the pager includes links to the first and last page (if there is a large enough number of items).	<key name=“ShowFirstLastButtons” value=“false” />
ShowPageSize	If true, the pager displays the page size selector.	<key name=“ShowPageSize” value=“false” />
ShowPreviousNextButtons	If true, the pager displays buttons that link to the previous and next page.	<key name=“ShowPreviousNextButtons” value=“false” />
ShowPreviousNextPageGroup	If true, the pager displays links to the previous and next groups of page links.	<key name=“ShowPreviousNextPageGroup” value=“false” />
VisiblePages	Determines the amount of page links displayed in one group.	<key name=“VisiblePages” value=“5” />

<options> (<GridOptions>)

The options element configures additional settings and special features of the UniGrid control. You can either add the settings as child <key> elements in the UniGrid’s XML configuration file, or as attributes of the <GridOptions> element directly in the control’s markup.