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

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.

<tooltip>

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:

  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”
“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).

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

  1. In the Kentico 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 <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).

Query attributes

Description

Sample value

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.

<pager> (<pagerConfig>)

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.

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.

<key name=“AllowSorting” value=“false” />

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.

<key name=“DisplayFilter” value=“true” />

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.

<key name=“FilterLimit” value=“10” />

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

<key name=“FilterPath” value=“/CMSAdminControls/UI/UniGrid/Filters/TextSampleFilter.ascx” />

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.

<key name=“ShowSelection” value=“true” />

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.

<key name=“SelectionColumn” value=“SiteName” />

ShowSortDirection

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

<key name=“ShowSortDirection” value=“false” />