Creating a Document Category Filter

Login to vote

Kentico provides an interface for developers to create custom controls to filter data sources such as document, navigation, and custom table data sources. Users can interact with these controls to filter the results of the data source. In this post I will show you how to build a category filter that will allow users to filter a list of documents based on the categories that the documents belong to.

If you are unfamiliar with creating custom filters in Kentico, I recommend you first take a look at the Kentico documentation on creating custom filters.

Step 1:

The first thing we need to do is create a new Web User Control called CategoryFilter.ascx in the CMSGlobalFiles directory and set it to inherit from CMSAbstractDataFilterControl.


Step 2:

Add the following controls to your front-end file of your category filter:

<asp:CheckBoxList ID="Categories" runat="server" />
<asp:Button ID="btnFilter" Text="Filter" OnClick="btnFilter_Click" runat="server" />

This is the checkbox list that will display the categories and the filter button that will preform the filtering action.

Step 3:

Now, add the following code to the code-behind file of your category filter:

protected override void OnInit(EventArgs e)

private void SetupControl()
    if (StopProcessing) return;
    if (RequestHelper.IsPostBack()) return;

    // Bind categories to check box list
    InfoDataSet<CategoryInfo> categories = CategoryInfoProvider.GetCategories(CMSContext.CurrentSiteID);

    Categories.DataSource = categories;
    Categories.DataTextField = "CategoryDisplayName";
    Categories.DataValueField = "CategoryID";

This code retrieves all of the available categories from your site and binds them to the checkbox list.

Step 4:

Now we need to create the code that will preform the filter on our data source web part; add the following code to the code-behind file:

protected void btnFilter_Click(object sender, EventArgs e)

private void SetFilter()
    // Extract category ids from selected categories
    IEnumerable<string> categoryIds = from ListItem item in Categories.Items where item.Selected select item.Value;

    if (!categoryIds.Any()) return; // If no categoies where selected, then return

    // Query database for selected categories
    InfoDataSet<CategoryInfo> categories = CategoryInfoProvider.GetCategories(String.Format("CategoryID IN ({0})", String.Join(",", categoryIds)), null);

    List<string> conditions = new List<string>();
    // Build a "where" condition for each one of the selected categories
    foreach (CategoryInfo category in categories.Items)
        conditions.Add(CategoryInfoProvider.GetCategoryDocumentsWhereCondition(category, true));

    // Join the where conditions with an "OR" statement to include documents that belong to any of the selected categories.
    // You can use an "AND" statement to limit the results to documents that belong to all of the selected categories
    WhereCondition = conditions.Join(" OR ");

    // Raise the filter changed event

This code will retrieve the selected categories from the data base and create a 'where' condition for each one. The key method to pay attentions to is the GetCategoryDocumentsWhereCondition method. This method takes in a CategoryInfo object and returns a SQL 'where' condition for documents based on the given category. We use this method to create a 'where' condition based on each of the selected categories and then join those conditions together with 'or' statements to filter documents that belong to any of the selected categories. Next we set the 'WhereCondition' property of the CMSAbstractDataFilterControl that will be given to the data source web part. Last we fire the RaiseOnFilterChanged event to notify the data source web part that the filter has changed.

Step 5:

To add the category filter to our page, click the add web part button in the design view of the page template and select the 'Filter' web part.


In the configuration, set the filter name to 'CategoryFilter' and set the filter control path to '/CMSGlobaFiles/CategoryFilter.ascx'.


Step 6:

Add your document data source web part. In this example I am using a Repeater. Make sure you set the filter name to be the same name that is set in your filter web part (in this case ‘CategoryFilter’).


Now you can use this filter to filter your repeater documents by category.


Where to go from here

To further refine your category selection options, take a look at the Category List web part (CMSWebParts/TaggingCategories/CategoryList.ascx). This web part allows you to configure which categories are displayed and builds the category list in a hierarchical fashion.

The full source can be download here:

Posted by Ryan Williams on 9/19/2013 12:13:36 PM
Blog post currently doesn't have any comments.