Built-in Kentico CMS UI Controls Part I - UniGrid

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

2. Agenda • Overview • Hierarchy • XML Definition • Properties • Actions • Q & A

3. Overview • In Kentico CMS UI used for displaying list of items like: • Users, Roles, Sites, Event log, etc., • List view mode, Outdated documents, etc.,

4. 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’

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

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

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

8. 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,

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

10. 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, • path- path to the custom ASCX control used as filter- CMSAbstractBaseFilterControl • type- type of default filter to be created- text, checkbox, integer, double

11. 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,

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

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

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

15. 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, • OnBeforeDataReload- event is fired before data are loaded from ReloadData() method, • OnAfterDataReload- event is fired after the data are load by ReloadData() method

16. Questions ?

17. Thank you Thank you!