Built-in Kentico CMS UI Controls
Part I - UniGrid
Karol Jarkovsky
Sr. Solution Architect
Kentico Software
http://devnet.kentico.com/Blogs/Karol-Jarkovsky.aspx
karolj@kentico.com
Agenda
•
•
•
•
•
•
Overview
Hierarchy
XML Definition
Properties
Actions
Q&A
Overview
In Kentico CMS UI used for displaying list of items like:
• Users, Roles, Sites, Event log, etc.,
• List view mode, Outdated documents, etc.,
Hierarchy
• UniGrid.ascx control located in ‘~/CMSAdminControls/UI/UniGrid’,
• Default folder for filters ‘~/CMSAdminControls/UI/UniGrid/Filters/’,
• Default folder for images
‘~/App_Themes/Default/Images/Design/Controls/UniGrid/Actions’
asp:GridView
Grid XML Def
OnAction
OnExternal
DataBound
Data
Filter
OnBefore
DataReload
OnAfter
DataReload
XML Definition
• <actions> - through its child <action> elements you add
action(s) (Edit, Delete, Modify, etc.) for every row to the
UniGrid causing action event fired that you can then
handle in your code,
• <columns> - you use this section to define columns
being displayed in the UniGrid,
• <objecttype /> - when specified UniGrid retrieves data
from DB using information related to the given class
name,
• <query> - when specified the query is executed to get
the data, instead of explicitly providing DataSource or
<objecttype /> info,
• <pager> - used to enable and define functionality of the
built-in pager control,
• <options> - used to enable additional extensions of the
UniGrid control
XML Definition - Actions
The following attributes of the <actions> element are available:
• parameters- columns used as parameters for onclick attribute of child
<action> nodes,
• showheader- indicates whether the header for action buttons cell should be
displayed,
• width- width of actions cell in the UniGrid
XML Definition – Actions - Action
The following attributes of the <action> element are available:
• caption- localization string for the action icon tooltip,
• commandargument- column whose value is passed as actionArgument
parameter to the OnAction event handler where you can implement action logic
using passed value,
• confirmation- localization string used for confirmation dialog displayed prior to
the action,
• externalsourcename- this value is passed to the OnExternalDataBound event
handler as sourceName parameter,
• icon- icon file used for action image button, located within ImageDirectoryPath
• name- value is passed to the OnAction event handler as actionName,
• onclick- JavaScript OnClick function for the action
XML Definition – Columns- Column
The following attributes of the <column> element are available:
• allowsorting- indicates whether column is used for rows sorting,
• caption- localization string for the column header text,
• cssclass- CSS class used for the column,
• externalsourcename- name of the column passed as sourceName to the
OnExternalDataBound event handler,
• href- if URL supplied the link is generated around the cell text, you can use
macros to access parameters,
• icon- image inserted into the cell right after the cell text, needs to be located
within ImageDirectoryPath,
• istext- used for generating ORDER BY statement in the query when sorting
enabled for this field. Must be set for fields allowing sorting,
XML Definition – Columns- Column
• localize- indicates whether localization is enabled for cell data,
• parameters- column names used for href attribute accessible through the macro,
• source- name of the column used as a source field for the cell, if ##ALL## used
the whole row is passed so you can generate cell text from within
OnExternalDataBound event handler,
• sort- if you use ##ALL## for source attribute you use this attribute top specify
single column that will be used for sorting,
• style- in-line style used for entire cell,
• visible- visibility of column,
• width- width of cell- relative or absolute,
• wrap- indicates whether the text is wrapped when longer then cell available
width
XML Definition – Columns- Column- child elements
The following child elements are allowed for the <column> element :
• tooltip – displays tooltip when hovering over cell text, in case image is defined for cell
tooltip is assigned to the icon only,
• encode- indicates whether tooltip text should be encoded,
• externalsourcename- name identifying tooltip in OnExternalDataBound event,
allows you to create complex tooltips,
• source• width• filter- element can be used to add given column to the UniGrid filter,
• format- allows you to create custom WHERE clause generated by default filter,
{0} – column name, {1} – operator, {2}- value fro the text box,
• size- max length of text box, default value 1000
• source- column used in default WHERE clause generated by filter,
• pathpath
to
the
custom
ASCX
control
used
as
filterCMSAbstractBaseFilterControl
• type- type of default filter to be created- text, checkbox, integer, double
XML Definition – Object type, Query & Parameter
The following child elements are allowed for the <objecttype> element :
• columns- columns that should be retrieved from DB for given object type,
• name- code name of the object to retrieve- class name format,
The following child elements are allowed for the <query> element :
• columns- columns that should be retrieved from DB for given object type,
• name- full code name of the system query to be executed to retrieve,
The following child elements are allowed for the <parameter> element that itself is child of
<query> parameter :
• name- name of the parameter defined in the query like @<parameter name>,
• type – type of the parameter- String, Int, Double, Bool
• value- parameter value,
XML Definition – Pager
The following keys are allowed as child elements for the <pager> element :
• DefaultPageSize- default number of rows displayed on the UniGrid page, must be one
of options defined by PageSizeOptions,
• PageSizeOptions- used to specify options in the page size drop-down list, multiple
values separated by comma, ##ALL## macro used to define option that all rows should
be displayed,
• ShowDirectPageControl- displays additional drop-down list displaying page numbers
you can choose to go to particular page directly,
• ShowFirstLastButtons- first/last page buttons displayed,
• ShowPageSize- displays drop-down list with page size options,
• ShowPreviousNextButtons- displays previous/next page buttons,
• ShowPreviousNextPageGroup- displays buttons moving page navigation to the next
group of page links,
• VisiblePages- page links group size
XML Definition – Options
The following keys are allowed as child elements for the <options> element :
• DisplayFilter- displays default UniGrid filter (based on columns settings), if total
number of data rows available is less than FilterLimit this settings is ignored,
• FilterLimit- minimum number of data rows displayed by UniGrid before filter is
shown,
default
value
comes
from
web.config
file
from
the
CMSDefaultListingFilterLimit key,
• ShowSelection- if true selection checkboxes are displayed in the very left column.
It is useful for mass actions when selected items can be accessed in the code
behind through the SelectedItems property of the UniGrid,
• SelectionColumn- name of the column whose value is going to be inserted into
the array of selected items,
• ShowSortDirection- displays little arrow icon next to the header text indicating
current sorting direction.
UniGrid – Properties
The UniGrid exposes the properties following:
• Columns- columns loaded from the data source specified in DataSource,
• DataSource- source of the data (used when no query, no object type defined),
• DelayedReload- you can force UniGrid to postpone data loading if needed, the
data won’t load unless you manually call ReloadData() UniGrid method,
• FilterDirectoryPath- default path for the custom filters,
• FilteredZeroRowsText- displayed when no data available when filter is applied,
• GridName- file path to the XML definition file,
• GridView- makes inner GridView control available outside UniGrid,
• SelectedItems- list of all items selected in the UniGrid using selection boxes
UniGrid – Events
The UniGrid fires the following events:
• OnAction- event is fired for all action buttons defined in the XML definition
file. The name of the action is passed to the event handler along with
information on what row fired action,
• OnExternalDataBound- when UniGrid starts binding the data event is fired
so you can influence the output for the specific column. Parameters passed to
the event handler indicates what cell is being bound and what is the source
data for this cell,
• OnBeforeDataReloadReloadData() method,
event is fired before data are loaded from
• OnAfterDataReload- event is fired after the data are load by ReloadData()
method
Questions
Thank you
Thank you!