• Documentation
  InstallationUsing the Kentico interfaceDeveloping websitesConfiguring KenticoManaging usersSecuring websitesDeploying websitesManaging website contentMultilingual websitesMacro expressionsExternal utilitiesIntegrating 3rd party systemsCustom developmentE-commerce featuresOn-line marketing featuresIntranet featuresCommunity featuresRunning Kentico on Windows AzureReferences
• Tutorial
  Using the Kentico interfaceManaging content - The basicsSite development overviewCreating pages using the portal engineWalkthrough - Creating a new site using the Portal engineCreating pages using ASPX templatesWalkthrough - Creating a new site using ASPX templates

The following example demonstrates how to develop a custom filter for product documents. The filter allows users to view products from specific departments and determine the order in which products are displayed. The filter applies when a postback occurs on the page. You can create filters for all types of documents or other objects using the same approach.

Creating the filter control

1. Open your web project in Visual Studio.

2. Create a New folder under the root called CMSGlobalFiles (if it doesn't already exist).

   • The system can export the content of this folder along with your site when you deploy it to another instance of Kentico.

3. Add a Web User Control named CustomProductFilter.ascx into the CMSGlobalFiles folder.

4. Add the following markup to the control:

   HTML

   Copy

   <%@ Control Language="C#" AutoEventWireup="true" CodeFile="CustomProductFilter.ascx.cs" Inherits="CMSGlobalFiles_CustomProductFilter" %>
   
   <table>
     <tr>
       <td style="padding:2px">
         <cms:LocalizedLabel ID="lblDepartment" runat="server" Text="Product department" DisplayColon="true">
         </cms:LocalizedLabel>
       </td>
       <td style="padding:2px">
         <cms:LocalizedDropDownList ID="drpDepartment" runat="server" Width="180" >
         </cms:LocalizedDropDownList>
       </td>
     </tr>
     <tr>
       <td style="padding:2px">
         <cms:LocalizedLabel ID="lblOrder" runat="server" Text="Order by" DisplayColon="true">
         </cms:LocalizedLabel>
       </td>
       <td style="padding:2px">
         <cms:LocalizedDropDownList ID="drpOrder" runat="server" Width="180" >
         </cms:LocalizedDropDownList>
       </td>
     </tr>
     <tr>
       <td colspan="2" style="padding:2px">
         <cms:LocalizedButton ID="btnFilter" runat="server" Text="Apply Filter" />
       </td>
     </tr>
   </table>

   This creates the design of the filter's user interface. The filter is composed of localized labels, drop-down lists and a button, arranged in a simple table layout. Alternatively, you can use a CSS‑based layout applied through HTML elements (e.g. <div>, <span>, etc.).

   You can enter the captions of the filter's child controls using localization strings through the ResourceString property, rather than directly as Text.

Implementing the filtering logic

1. Switch to the user control's code behind file and add the following references:

   C#

   Copy

   using System.Data;
   
   using CMS.Controls;
   using CMS.Helpers;
   using CMS.Ecommerce;

2. Set the control to inherit from the appropriate base class.

   • This example uses the CMSAbstractDataFilterControl class, since the filter is intended for use with a document data source.

3. Add the following methods into the user control class to load the filtering options into the child drop-down lists:

   C#

   Copy

   /// <summary>
   /// Sets up the inner child controls.
   /// </summary>
   private void SetupControl()
   {
       // Hides the filter if StopProcessing is enabled
       if (this.StopProcessing)
       {
           this.Visible = false;
       }
   
       // Initializes only if the current request is NOT a postback
       else if (!RequestHelper.IsPostBack())
       {
           // Loads product departments as filtering options
           InitializeDepartments();
   
           // Initializes the Order by drop-down list
           IntializeOrder();
       }
   }
   
   /// <summary>
   /// Loads the ordering options into the Order by drop-down list.
   /// </summary>
   private void IntializeOrder()
   {
       // Initializes the ordering options
       this.drpOrder.Items.Add(new ListItem("Price - Ascending", "priceAsc"));
       this.drpOrder.Items.Add(new ListItem("Price - Descending", "priceDesc"));
       this.drpOrder.Items.Add(new ListItem("Product name", "name"));
   }
   
   /// <summary>
   /// Loads all existing product departments as filtering options into the department drop-down list.
   /// </summary>
   private void InitializeDepartments()
   {
       // Gets all product departments from the system's database
       DataSet departments = DepartmentInfoProvider.GetDepartments("", "DepartmentDisplayName", 0, "DepartmentID, DepartmentDisplayName");
   
       // Checks that at least one product department exists
       if (!DataHelper.DataSourceIsEmpty(departments))
       {
           // Binds the departments to the drop-down list
           this.drpDepartment.DataSource = departments;
           this.drpDepartment.DataTextField = "DepartmentDisplayName";
           this.drpDepartment.DataValueField = "DepartmentID";
   
           this.drpDepartment.DataBind();
   
           // Adds the default '(all)' option
           this.drpDepartment.Items.Insert(0, new ListItem("(all)", "##ALL##"));
       }
   }

4. Define the SetFilter() method:

   C#

   Copy

   /// <summary>
   /// Generates a WHERE condition and ORDER BY clause based on the current filtering selection.
   /// </summary>
   private void SetFilter()
   {
       string where = null;
       string order = null;
   
       // Generates a WHERE condition based on the selected product department
       if (this.drpDepartment.SelectedValue != null)
       {
           // Gets the ID of the selected department
           int departmentId = ValidationHelper.GetInteger(this.drpDepartment.SelectedValue, 0);
   
           if (departmentId > 0)
           {
               where = "SKUDepartmentID = " + departmentId;
           }
       }
   
       // Applies the selected product order
       if (this.drpOrder.SelectedValue != "")
       {
           switch (this.drpOrder.SelectedValue)
           {
               case "priceAsc":
                   order = "SKUPrice";
                   break;
   
               case "priceDesc":
                   order = "SKUPrice Desc";
                   break;
   
               case "name":
                   order = "SKUName";
                   break;
           }
       }
   
       if (where != null)
       {
           // Sets the Where condition
           this.WhereCondition = where;
       }
   
       if (order != null)
       {
           // Sets the OrderBy clause
           this.OrderBy = order;
       }
   
       // Raises the filter changed event
       this.RaiseOnFilterChanged();
   }

5. Add two more methods that override the handlers of the control's Init and PreRender events:

   C#

   Copy

   /// <summary>
   /// Init event handler.
   /// </summary>
   protected override void OnInit(EventArgs e)
   {
       // Creates the child controls
       SetupControl();
       base.OnInit(e);
   }
   
   /// <summary>
   /// PreRender event handler
   /// </summary>
   protected override void OnPreRender(EventArgs e)
   {
       // Checks if the current request is a postback
       if (RequestHelper.IsPostBack())
       {
           // Applies the filter to the displayed data
           SetFilter();
       }
   
       base.OnPreRender(e);
   }

When a user clicks the Apply Filter button, a postback occurs, which triggers the SetFilter() method during the PreRender event and the filter applies the conditions to the displayed data. Notice the use of the CMS.Helpers.RequestHelper.IsPostBack() method in the conditions. The control only calls the SetFilter() method when the current page request is a postback, and initializes the child controls only on the first page load (i.e. when the request is not a postback).

Adding the filter to a portal engine page

The filter control is now ready and you can try out its functionality. It is recommended to test the filter on the Corporate or E-commerce sample sites, which already contain examples of product documents.

1. Log in to the administration interface.

2. Open the Pages application and create a new page.

3. Switch to the page's Design tab and add the following web parts:

   Web part	Instructions
   Documents data source	Configure the web part to load product documents. Fill in the Filter name property (e.g. CustomProductFilter).Note: You can alternatively use the Products data source web part for this purpose.
   Filter	Assign a Filter name that matches the data source (CustomProductFilter). Enter the path of the .ascx file implementing your custom filter into the Filter control path property: ~/CMSGlobalFiles/CustomProductFilter.ascx
   Basic repeater	Enter the ID of the Documents data source web part into the Data source name property. Set an appropriate Transformation name, for example: CMS.Product.CorporateSite

   For more information about setting up web parts that display data and allow filtering, see:

   • Loading and displaying data on websites
   • Filtering and paging data

If you view the page on the live site, you can see a list of products with the custom filter above. Try filtering the products by their department and changing their order.