Data source and filter controls Miro Remias Solution architect Kentico software miro@kentico.com

Agenda Introduction Data source controls - API Filter controls - API Life cycle Examples – developing custom controls

Introduction Re-usable source of data (better performance, caching available) Higher design flexibility Easy data filtering Source database/ external source Filter name Filter name Filter n Filter 1 Data source Filter name SourceControlName Web part control ID Data source name Listing control Web part control ID Repeater (documents) Datalist (documents) BasicRepeater BasicDatalist Uni pager Target control name

Data source controls API - I Available data source controls: CMSDocumentsDataSource: CMSControlDataSource: CMSBaseDataSource CMSQueryDataSource: CMSBaseDataSource CustomTableDataSource: CMSBaseDataSource FileSystemDataSource: CMSBaseDataSource SQLDataSource: CMSBaseDataSource UsersDataSource: CMSBaseDataSource WebServiceDataSource: CMSBaseDataSource XMLDataSource: CMSBaseDataSource AttachmentsDataSource: CMSBaseDataSource CMSControlDataSource TreeProvider ClassNames Path CultureCode CombineWithDefaultCulture SelectOnlyPublished MaxRelativeLevel CheckPermissions FilterOutDuplicates SelectTopN InitDataProperties() ReloadData() GetDefaultCacheDependendencies() CMSBaseDataSource : CMSAbstractBaseFilterControl DataSource RelatedData GetDataSource() SourceFilterControl.InitDataProperties() GetDataSourceFromDB GetRelatedData (TreeNode for AttachmentsDataSource) GetDataSourceFromDB() GetRelatedData() InvalidateLoadedData() (DataSource and RelatedData = null) ClearCache()

Data source controls API - II Developing custom data source control / web part Steps to follow: Create control file. Inherit from CMSBaseDataSource or from CMSControlDataSource class. Register custom method in for OnFilterChanged handler of source filter control in OnInit method. Call InvalidateLoadedData() and RaiseOnFilterChanged() methods in this custom method. Implement GetDataSourceFromDB method to return custom DataSource. Create web part file. Assign WebPartControlID of the web part to FilterName property of your data source control in SetupControl method. Example 1 (Excel data source control) Detail information can be found in developer’s guide: http://devnet.kentico.com/docs/devguide/developing_datasource_web_parts.htm

Filter controls API - I Available filter classes: CMSAbstractDataFilterControl - works with document data sources. CMSAbstractMenuFilterControl - works with navigation web parts. CMSAbstractQueryFilterControl - works with custom table and query data sources. CMSAbstractBaseFilterControl - works with all data sources. CMSAbstractControlFilterControl TreeProvider ClassNames Path CultureCode CombineWithDefaultCulture SelectOnlyPublished MaxRelativeLevel CheckPermissions InitDataProperties() ReloadData() CMSAbstractBaseFilterControl StopProcessing CacheItemName CacheDependencies CacheMinutes SiteName WhereCondition OrderBy TopN SelectedColumns FilterChanged FilterName FilterControlPath FilterControl SourceFilterName SourceFilterControl FilteredControl DisableFilterCaching Value OnFilterChanged InitDataProperties() OnLoad() -> SourceFilterControl.OnFilterChanged -> RaiseOnFilterChanged() -> OnFilterChanged ResetFilter() CMSAbstractDataFilterControl SelectTopN SelectedItemTransformationName RelatedNodeIsOnTheLeftSide RelationshipName RelationshipWithNodeGuid PageSize InitDataProperties() CMSAbstractMenuFilterControl ApplyMenuDesign UseItemImagesForHiglightedItem HighlightAllItemsInPath SubmenuIndicator UseAlternatingStyles CSSPrefix WordWrap HideControlForZeroRows ZeroRowsText Columns InitDataProperties() CMSAbstractQueryFilterControl QueryName GeneralConnection PageSize SelectTopN InitDataProperties()

Filter controls API - II Developing custom filter control Steps to follow: Create control file. Inherit from suitable (CMSAbstractDataFilterControl, CMSAbstractMenuFilterControl, CMSAbstractQueryFilterControl, CMSAbstractBaseFilterControl) filter class. Initialize child controls in OnInit method. Implement SetFilter method, where call to RaiseOnFilterChanged method is necessary. Call SetFilter method in OnPreRender method if there was post back. Use filter control in Filter web part. Important notes !!! All filters and data source controls as well as some other controls (BasicRepeater etc.) are loaded into hash table: CMS.Controls.CMSControlsHelper.CurrentFilters. When you set FilterName property CMSControlsHelper.SetFilter() method is called to add the control to CurrentFilters hash table. Example 2 (Excel filter control) Detail information can be found in developer’s guide: http://devnet.kentico.com/docs/devguide/developing_custom_filters.htm

Life cycle – Custom data source + filter controls ExcelDataSource [w] Filter [w] BasicRepater [w] ExcelDataSourceControl [c] [edsc] ExcelFilter [c] [ef] OnContentLoaded SetupControl edsc.FilterName LoadFilter ef.FilterName EnsureFilterControl OnInit ef.OnFilterChanged GetDataSource InitializeColumns OnLoad Onload edsc.OnFilterChanged OnPreRender SetFilter RaiseOnFilterChanged OnFilterChanged InvalidateLoadedData edsc.DataSource Access CurrentFilters hash table and access DataSource propety of CMSBaseDataSource control which will call CMSBaseDataSource.GetDataSource method -> SourceFilterControl(ExcelFilter).InitDataProperties(this) and after that -> GetDataSourceFromDB() of ExcelDataSourceControl control and load the dataset in GetDataSourceFromExcel method

? Questions FAQ – http://devnet.kentico.com/FAQs.aspx Developing custom filter blog post from Karol Jarkovsky: http://devnet.kentico.com/Blogs/Karol-Jarkovsky/March-2011/Custom-filter-development-with-Kentico-CMS.aspx FAQ – http://devnet.kentico.com/FAQs.aspx KB - http://devnet.kentico.com/Knowledge-Base.aspx Documentation - http://devnet.kentico.com/Documentation.aspx Technical support - http://www.kentico.com/Support.aspx (support@kentico.com)

Thank you! Miro Remias miro@kentico.com Solution architect Kentico software