UniGrid definition

Many configuration options that determine the behavior, design and content of the UniGrid control must be specifically defined. This can either be done either in an external XML configuration file, which is then assigned to the control through its GridName property, or directly within the definition of the control in the ASPX markup of the page or user control where the UniGrid is placed.

When using an external XML file, it must be organized according to the structure shown below (some elements are optional):

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

InfoBox_Exclamation

Important!

If you use an external XML configuration file to specify the UniGrid's definition, the names of elements and their attributes used must be written in lower case to be recognized correctly, since it is case sensitive.

To define the UniGrid directly in the ASPX markup, it is first necessary to register the following namespace at the start of the code (in addition to the UniGrid control):

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

Then you can simply add elements under the control according to the following structure:

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

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

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

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

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

</cms:UniGrid>

When using this approach, the data source of the control must be specified directly through the UniGrid's properties (Query, ObjectType or DataSource). An advantage of this option is that you may use the IntelliSense in Visual Studio to help find the appropriate elements and attributes.

Individual elements that can be defined for the UniGrid and their attributes are described below:

•<actions>

•<columns>

•<objecttype>

•<query>

•<pager>

•<options>

<actions> (<GridActions>):

This element is used to define a column that contains various possible actions (e.g. Edit, Delete, View...) represented by icons for every row of the UniGrid. Individual actions must be defined by child <action> elements.

The following attributes of the <actions> element are available:

Attribute Name	Description	Sample Value
cssclass	Specifies the name of a CSS class from the assigned stylesheet to be used to style the appearance of the actions column.	"UniGridCustomActionsColumn"
parameters	A list of columns separated by semicolons that will be usable as parameters in the onclick or menuparameter attributes of child <action> elements .	"AttachmentGUID;AttachmentFormGUID"
showheader	Indicates whether the header of the actions column should be displayed. The default value is true.
width	Determines the width of the actions column in the UniGrid.	"30%" "100px"

This element may contain <action> and <separator> child elements.

<action> (<ug:Action>):

This element is used to define individual actions. The implementation of individual actions is handled during the OnAction event of the UniGrid control. Any advanced features of individual action buttons, such as defining when a button should be functional, can be implemented in the handler of the OnExternalDataBound event.

The following attributes are available:

Attribute Name	Description	Sample Value
caption	Specifies the 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 should be passed as the actionArgument parameter of the OnAction event handler. If not defined, the first column of the data source will be used.
confirmation	The text used 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 that is passed as the sourceName parameter of the OnExternalDataBound event handler.	"deletefile"
icon	Name of the image that should be used as the icon of the action. The image must be 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). These parameters may be retrieved in the control's code using the GetContextMenuParameter JavaScript function. The columns defined in the parameters attribute of the <actions> element may be entered as parameters 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	Name of the action. This is passed to the handler of the OnAction event as the actionName parameter.	"delete"
onclick	The JavaScript OnClick function for the given action. It may use the columns defined in the parameters attribute of the <actions> element as parameters, which can be called by using the following expressions: {0} - first parameter {1} - second parameter and so forth.	"alert(‘{0}’);"
Action security
modulename	This attribute (and the two listed below) may be specified to leverage the security model of Kentico CMS to 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 Site Manager -> Development -> Modules interface.	"cms.ecommerce"
permissions	Sets the code name of the permission that users must have to be allowed to perform the action. The permissions must belong to the module specified in the modulename attribute.	"modifyorders"
uielements	If specified, users will need to be allowed to view the given UI element in order to perform the action. The given user interface element must belong to the module specified in the modulename attribute.	"orders.general"
hideifnotauthorized	Indicates if the action should be hidden for users who are not allowed to perform it (as defined by the attributes above).

InfoBox_Note

Default object menu action

If your UniGrid control uses an object type data source (specified either through the <objecttype> definition element or the ObjectType property), then an action providing a context menu will automatically be added to the displayed grid.

This menu provides options that can be used to Export, Backup, Restore or Destroy the listed objects. Some types of objects may not have all menu options available.

This does not occur if you manually specify another action with a contextmenu attribute or in cases where there are no actions at all defined for the grid. You can also disable this action by setting the ShowObjectMenu property of the UniGrid to false.

<separator> (<ug:ActionSeparator>):

This element is used to define a separator between actions. The following attribute is available for it:

Attribute Name

Description

Sample Value

text

Text to be generated in the Literal control between actions.

"<span class=" UniGridActionSeparator"

>&nbsp;</span>"

<columns> (<GridColumns>):

This element represents the main section of the UniGrid. The <columns> element itself has no attributes as each column can have its own settings. Individual columns are defined by child <column> elements.

<column> (<ug:Column>):

This element is used to define columns. Any advanced functionality of the cells in the given column can be implemented in the handler of the OnExternalDataBound event.

The following attributes are available for it:

Attribute Name	Description	Sample Value
action	Can be used to set the name of an action that will be performed when the content of this column's cells is clicked. An action with this name must be defined for the UniGrid via the name attribute of an <action> element.
allowsorting	Indicates whether the column can be used to sort the rows of the UniGrid.
caption	Specifies the text used 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 should be passed as the actionArgument parameter of the OnAction event handler when the action specified via the action attribute is used. If not defined, the first column of the data source will be used.
cssclass	Specifies the name of a CSS class from the assigned stylesheet to be used to style the appearance of the given column.	"UniGridCustomColumn"
externalsourcename	Sets a name for the column that will be passed as the sourceName parameter of the OnExternalDataBound event handler. Used for implementing custom functionality in the cells of the given column. You can use the following expressions as the value to call built‑in functions of the UniGrid that format the content of the column without having to write any code: •#yesno - can be set for columns with a source that uses the bit (boolean) data type. The values are displayed as Yes (colored green) or No (colored red). •#sitename - converts site ID (integer) values into the appropriate site display name for each row. •#sitenameorglobal - converts site ID values into the appropriate site display name for each row. If a record is not related to a specific site (i.e. the site ID is null), then the given 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. •#htmlencode - HTML encodes text values. •#url - converts URL text values into links. To set a default value used if the result of the function is null or an empty string, add the "\|" character as a separator and specify the value after, for example: #username\|None You can also specify custom transformation expressions for columns that contain the ID values of other objects. For example, the following externalsourcename values could be used for a user ID column: •#transform: cms.user.fullname - ensures that the full name is displayed for each user instead of the ID. •#transform: cms.user : UserIsEditor #yesno - checks the bit value of the UserIsEditor column for each user and formats it according to the internal #yesno function. •#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 this type of column, the order of the rows will be based on the ID values, not the output of the transformation.	"user_modify" "#yesno" "#culturename\|{$general.default$}"
href	If a URL is entered here, a link to this URL is generated around the content of the cells in this column. Macros {0}, {1}, ... can be used to access parameters defined by the parameters attribute.	"~/page.aspx"
icon	Name of an image that should be added into the column cells after the loaded data. 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. This is used to generate a special OrderBy clause of the query, so it must be set if sorting is enabled for the column.
localize	Indicates whether localization should be enabled for string values in the column.
maxlength	Sets the maximum number of characters that can be displayed in the column's cells. The last 3 characters will be replaced by periods.
name	Can be used to set a custom name for the column, which will be used in the column dictionary accessible through the NamedColumns property of the UniGrid control.
parameters	Names of the columns used as parameters of the URL generated by the Href attribute. Separated by semicolons.
source	Name of the column from the data source of the UniGrid that is used as the source for the content of this column. The special macro ##ALL## can be used to specify all columns.
sort	Used to define the column name to be used for sorting if the ##ALL## macro is used in the source attribute.
style	The style used for the entire column.	"padding:10px"
visible	Indicates whether the column should be visible.
width	Determines the width of the column.	"20%" "200px"
wrap	Indicates whether word wrapping is used in the column.

The column element may contain child <tooltip> and <filter> elements.

<tooltip>:

When this element is added, a tooltip is displayed when the mouse hovers over the content of the cells in this column. If an icon is present in the cell, the tooltip is displayed over the icon instead of the text. The content of the tooltip can be defined and configured by the following attributes:

Attribute Name	Description	Sample Value
encode	Indicates whether the output of the tooltip should be encoded.
externalsourcename	Name used in the OnExternalDataBound event for changing the appearance of the tooltip. This can be used to create complex tooltips including images, panels etc.
source	Name of the column from the data source of the UniGrid that is used as the source of the tooltip.
width	Determines the width of the tooltip.

<filter>:

When this element is added, the given column will be used in the UniGrid filter. The following attributes are available to configure the filter:

Attribute Name	Description	Sample Value
format	Can be used to define a custom WHERE clause format to be generated by the default filter. The following expressions can be used: {0} - is resolved into the column name {1} - is resolved into the operator selected in the drop‑down list of the default filter {2} - is resolved into the value entered into the textbox of the default filter	" [{0}] {1} '{2}' "
defaultvalue	Can be used to specify a value that will be preset in the filter when the page is loaded. The entered value must match the type of the filter.
path	Path to the control (.ascx file) that should be used instead of the default filter for the column. If filled, the type attribute is ignored. The default relative path is ~/CMSAdminControls/UI/UniGrid/Filters/.
size	Determines the maximum amount of characters that can be entered into the textbox of the default filter. Available for Text, Integer and Double filter types. The default value is 1000.
source	Name of the column used in the WHERE clause generated by the filter.
type	Determines the filter type that should be created 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, it is also possible to filter objects according to their binding to specific sites. This can be achieved by creating a <filter> element under any column (the data of the column is not used) and setting the type value to site.	"text" "bool" "integer" "double" "site"

<objecttype>:

This element can be used to define the data class of the objects that should be loaded as the data source and displayed by the UniGrid control. A list of all data classes and related information can be found in the CMS_Class database table. Please note that this approach is not supported for classes representing document types (those whose value in the ClassIsDocumentType column is 1). However, it can be used to load data from custom tables.

If this element isn't used, a data source must be retrieved by means of the <query> element or assigned through the UniGrid control's DataSource property before its ReloadData() method is called. Alternatively, the ObjectType property of the UniGrid control can be used for the same purpose.

The following attributes can be used to define the object type:

Attribute Name

Description

Sample Value

columns

Names of the columns that should be retrieved separated by commas. If empty, all columns will be retrieved.

By default, the values of the first column are passed as the actionArgument parameter of the OnAction event handler. This can be overridden for actions by specifying a column name in the commandargument attribute of individual <action> elements.

name

Code name of the used data class.

"cms.user"

<query>:

This element can be used to specify the system query that will retrieve data from the Kentico CMS database to be displayed by the UniGrid control. If it isn't used, an external data source must be assigned through the UniGrid control's DataSource property before its ReloadData() method is called. Alternatively, the Query property of the Unigrid control can be used for the same purpose.

The following attributes can be used to define the query:

Attribute Name

Description

Sample Value

columns

Names of the columns that should be retrieved by the query separated by commas. If empty, all database columns will be retrieved.

name

Code name of the used system query in format <class name>.<query name>.

"cms.site.selectsitelist"

The query element may contain <parameter> child elements:

<parameter>:

This element can be used to define the value of a parameter inside the specified query.

The following attributes must be filled to define the parameter:

Attribute Name	Description	Sample Value
name	Name of the parameter. Parameters are placed into queries using the following syntax: @<paramater name> For example, if the specified query looked like this: SELECT TOP @customTop FROM CMS_User Then entering customTop into this attribute would cause the value of this element to be used by the query instead of the @customTop expression.
type	The type of the parameter.	"String" "Int" "Double" "Bool"
value	The value of the parameter.

<pager> (<PagerConfig>):

This element is used to define the behaviour of the UniGrid pager. You can either add the settings as child <key> elements in the XML configuration file, or as attributes of the <PagerConfig> element when defined directly in the code. The following are available:

Key name	Description	Sample Value
DisplayPager	Indicates if a pager should be included below the UniGrid. True by default.	<key name="DisplayPager" value="false" />
DefaultPageSize	Defines the default amount of rows displayed on one UniGrid page. The value must be one of the options offered by the page size selection drop‑down list. These values are defined by the PageSizeOptions key.	<key name="DefaultPageSize" value="10" />
PageSizeOptions	This setting can be used to override the default values offered by the page size selection drop‑down list. Values must be separated by commas. The ##ALL## macro can be used as a value to indicate that all rows should be displayed. The default value is “25,50,100,##ALL##”.	<key name="PageSizeOptions" value="10,20,##ALL##" />
ShowDirectPageControl	Indicates whether a drop‑down list used for direct page selection should be displayed.	<key name="ShowDirectPageControl" value="true" />
ShowFirstLastButtons	Indicates whether the buttons that link to the first and last page should be displayed.	<key name="ShowFirstLastButtons" value="false" />
ShowPageSize	Indicates whether the page size selection drop‑down list should be displayed.	<key name="ShowPageSize" value="false" />
ShowPreviousNextButtons	Indicates whether the buttons that link to the previous and next page page should be displayed.	<key name="ShowPreviousNextButtons" value="false" />
ShowPreviousNextPageGroup	Indicates whether the buttons that link to the next group of page links should be displayed.	<key name="ShowPreviousNextPageGroup" value="false" />
VisiblePages	Determines the amount of displayed page links in one group.	<key name="VisiblePages" value="5" />

<options> (<GridOptions>):

This element is used to define additional settings and special features of the UniGrid control. You can either add the settings as child <key> elements in the XML configuration file, or as attributes of the <GridOptions> element when defined directly in the code. The following are available:

Key name	Description	Sample Value
DisplayFilter	Indicates whether a filter should be displayed above the UniGrid. If the amount of displayed rows is lower than the value of the FilterLimit key, the filter will be hidden despite this setting.	<key name="DisplayFilter" value="true" />
FilterLimit	Determines the minimum amount of rows that must be displayed in the UniGrid before a filter is shown. The default value is read from the CMSDefaultListingFilterLimit web.config key.	<key name="FilterLimit" value="10" />
ShowSelection	Indicates whether a column allowing the selection of rows should be displayed on the left of the UniGrid. This can be used to perform mass actions affecting multiple rows. The selected rows can be accessed through the SelectedItems property of the UniGrid.	<key name="ShowSelection" value="true" />
SelectionColumn	Name of the column used as an item in the array of selected rows which can be accessed through the SelectedItems property of the UniGrid. By default the first column in the data source is used.	<key name="SelectionColumn" value="SiteName" />
ShowSortDirection	Determines if an arrow showing the sorting direction should be displayed next to the header of the column used for sorting.	<key name="ShowSortDirection" value="false" />

Help URL: http://devnet.kentico.com/docs/7_0/controls/index.html?unigrid_definition.htm