• 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 Microsoft AzureUsing Amazon web services with KenticoReferencesRelease notes - Kentico 8 versions
• 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

2. Add the filter control onto your website through the Filter web part.

   • You need to specify the path to the .ascx file in the Filter control path property.

3. Attach the filter web part to the data source web part of the matching type.

You can also use custom filters anywhere in your code as standard user controls, for example on ASPX templates or in other web parts. All necessary properties, such as the FilterName used to connect with the data source, are inherited from the base class.

Example - Creating a custom product filter

The following example demonstrates how to develop a custom filter for product pages. 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 pages 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;
   using System.Web.UI.WebControls;

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 page 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
       var departments = DepartmentInfoProvider.GetDepartments();
   
       // 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 pages.

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:

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.