XML definition

Many configuration options that determine the behaviour, design and content of the UniGrid control must be defined in an external XML configuration file, which is then assigned to the control through its GridName property.

The following is the structure that this kind of XML file must have:

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

<grid>

...

</actions>

...

</columns>

<query>

...

</query>

<pager>

...

</pager>

...

</options>

</grid>

Please be aware

The names of elements and their attributes used in this XML configuration file are case sensitive and must be written in lower case to be recognized correctly.

Individual child elements that can be added under the main <grid> element are described below:

•

•

•	<objecttype>

•

<query>

•

<pager>

•

actions:

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
parameters	A list of columns used as parameters in the onclick attribute of child <action> elements separated by semicolons.	"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:

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 resource string used as the tooltip of the image defined in the icon attribute. Must begin and end with the $ character.	"$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 is used.
confirmation	The resource string used in a JavaScript confirmation. Most commonly used as a confirmation for delete type actions. Must begin and end with the $ character.	"$General.ConfirmDelete$"
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"
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 uses 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}’);"

separator:

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:

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:

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
allowsorting	Indicates whether the column can be used to sort the rows of the UniGrid.
caption	Specifies the resource string used as the header for the column. Must begin and end with the $ character.	"$general.name$"
externalsourcename	Name of the column passed as the sourceName parameter of the OnExternalDataBound event handler. Used for implementing custom functionality in the cells of the given column.
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 is enabled for strings in the column.
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}' "
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.
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/.
type	The filter type that should be created for the given column.	"Text" "Bool" "Integer" "Double"

objecttype:

This element can be used to define the data class of the objects that should be displayed by the UniGrid control. A list of all data classes and related information can be found in the CMS_Class database table. If it 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:

This element is used to define the behaviour of the UniGrid pager. This is done by adding <key> child elements; the following are available:

Key name	Description	Sample Value
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:

This element is used to define additional settings and special features of the UniGrid control. This is done by adding <key> child elements; 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" />

Page url: http://devnet.kentico.com/docs/5_5r2/controls/index.html?unigrid_xml_definition.htm