---
title: Creating custom UniGrid filters
related:
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/reference-unigrid-definition.md
- https://docs.kentico.com/13/custom-development/extending-the-administration-interface/developing-form-controls/example-developing-custom-form-controls.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
If you need to add custom filtering options to listing pages that utilize a [UniGrid](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid.md), you can develop and assign your own filter controls.
> **Note:** **Note**: We strongly recommend using the default UniGrid filter for standard filtering scenarios. Only implement a custom filter control if the default filter cannot fulfill your requirements. To use the default filter, you only need to configure the **filter** element under the appropriate **column** elements in the UniGrid's definition.
>
> For more information about the default UniGrid filter, see [Reference - UniGrid definition](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/reference-unigrid-definition.md).
To implement a custom UniGrid filter, you need to create a user control (.ascx file) in your administration project. We recommend storing your filter controls in one of the following folders:
- _\~/CMSModules/_ – if you are developing the filter as part of a [custom module](https://docs.kentico.com/13/custom-development/creating-custom-modules.md).
- _\~/CMSGlobalFiles_ – general location recommended for files that are not associated with a specific module or site.
You can create two main types of custom filter controls for the UniGrid:
- [Filters for specific columns](#creating-filters-for-specific-columns)
- [Filters that completely replace the default UniGrid filter](#fully-replacing-the-default-unigrid-filter)
## Creating filters for specific columns
The default UniGrid filter is a form that consists of multiple filtering fields. Each field typically provides filtering based on a different data column in the UniGrid listing.
To implement a custom filter control for a specific UniGrid column:
1. Create a user control within the administration project.
2. Build the filtering interface by adding elements to the control's markup.
3. Perform the following in the control's code behind:
- Make the filter control inherit from the **CMS.FormEngine.Web.UI.FormEngineUserControl** class.
- Override the **Value** property – get and set the value selected within the filter.
- Override the **GetWhereCondition()** method – return a string containing an SQL where condition that performs the required filtering (use the _Value_ property in the condition).
- Add any other logic required by the filter (for example initialization of filtering options).
You can then assign the filter to a column in the definition of a UniGrid:
1. Find the **** (XML) / **** (markup) element representing the corresponding column.
2. Add a **** element under the column element.
3. Set the filter element's attributes:
- **type**: _custom_
- **path**: enter the path to your custom filter's user control file
```xml
...
...
```
The system inserts the custom filter for the given column into the UniGrid's overall filter. The custom filter can be combined with filters defined for other columns (both default and custom).
> **Info:** Custom filters that inherit from _FormEngineUserControl_ provide automatic support for the UniGrid filter state management features (storing of the filter state for each user and resetting to the default state).
### Setting parameters for custom column filters
If your custom filter control has properties that change its behavior, you can set their values directly in the UniGrid definition. This gives your custom filters greater flexibility, since you can use a different filter configuration for every instance of the UniGrid.
To assign values to the properties of custom filters in the UniGrid definition:
1. Add a **** (XML) / **** (markup) element under the given **** element.
2. Create a child **** (XML) / **** (markup) element for every property that you want to set.
3. Set the following attributes for each filter parameter:
- **name** – identifier of the parameter (used when getting the value in the filter's properties).
- **value** – the value assigned to the filter property. The type of the value attribute is a string, but you can use _ValidationHelper_ methods to load the value as another type.
To load UniGrid parameter values in your custom filter, call the **GetValue** method (inherited from _FormEngineUserControl)_ within the _get_ code of your properties. Then use **CMS.Helpers.ValidationHelper** methods to convert the value to the appropriate type. See the [Example](#example---creating-a-custom-user-filter) for additional details.
The system assigns the values from the UniGrid definition into the filter's properties before displaying the page.
## Fully replacing the default UniGrid filter
You can create custom filters that completely replace the entire default filter of the UniGrid (for all columns).
To develop the custom filter control:
1. Create a user control within your administration project.
2. Build the filtering interface by adding elements to the control's markup.
3. Make the filter control's class implement the **CMS.FormEngine.Web.UI.IFilterControl** interface (use the **WhereCondition** property to generate the filtering condition).
You can then assign the filter to a UniGrid:
1. Edit the UniGrid's definition.
2. Find or add the **** (XML) / **** (markup) element.
3. Enter the path to your custom filter's user control file:
- XML: Add a **** element under **** with the path as the key's value.
- Markup: Set the path using the **FilterPath** attribute of the **** element.
The given UniGrid instance now uses your custom filter. Any filter settings for individual columns are ignored.
## Example - Creating a custom user filter
The following example demonstrates how to create a custom filter for a UniGrid displaying user objects. The sample filter is intended for a _**specific column**_ and limits which users are displayed based on their preferred content culture. The filter provides a dynamically loaded list of cultures for selection and can be configured to offer only cultures assigned to the current site or only designated UI cultures.
Start by developing the filter control:
1. Open your administration project in Visual Studio.
2. Expand the **\~/CMSGlobalFiles** folder (create the folder if it does not exist yet).
3. Create a new web user control named **UserCultureFilter.ascx**.
4. Add a **CMSDropDownList** into the control's markup to provide the filtering interface:
```xml
<%@ Register namespace="CMS.Base.Web.UI" assembly="CMS.Base.Web.UI" tagPrefix="cms" %>
```
5. Switch to the control's code behind and add the following code:
```csharp
using System;
using System.Data;
using System.Web.UI.WebControls;
using CMS.FormEngine.Web.UI;
using CMS.Localization;
using CMS.Helpers;
using CMS.SiteProvider;
public partial class CMSGlobalFiles_UserCultureFilter : FormEngineUserControl
{
///
/// Gets or sets the value selected within the filter.
///
public override object Value
{
get
{
return drpCultures.SelectedValue;
}
set
{
drpCultures.SelectedValue = ValidationHelper.GetString(value, "");
}
}
///
/// Indicates whether the filter only provides cultures that are assigned as content cultures to the current site.
///
public bool CurrentSiteCulturesOnly
{
get
{
// Gets the value from the matching element in the UniGrid's XML definition
object parameterValue = GetValue("currentsiteculturesonly");
return ValidationHelper.GetBoolean(parameterValue, false);
}
set
{
SetValue("currentsiteculturesonly", value);
}
}
///
/// Indicates whether the filter only provides designated UI cultures.
///
public bool UICulturesOnly
{
get
{
// Gets the value from the matching element in the UniGrid's XML definition
object parameterValue = GetValue("uiculturesonly");
return ValidationHelper.GetBoolean(parameterValue, false);
}
set
{
SetValue("uiculturesonly", value);
}
}
///
/// Loads the filtering options during the initialization of the control.
///
protected override void OnInit(EventArgs e)
{
base.OnInit(e);
// Only initializes the culture options on the first page load
if (IsPostBack == false)
{
// Prepares a where condition for loading cultures based on the filter's parameters
string where = String.Empty;
// Adds a condition for loading only cultures assigned to the current site
if (CurrentSiteCulturesOnly)
{
where = "CultureID IN (SELECT CultureID FROM CMS_SiteCulture WHERE SiteID = " + SiteContext.CurrentSiteID + ")";
}
// Adds a condition for loading only designated UI cultures
if (UICulturesOnly)
{
if (!where.Equals(String.Empty))
{
where += " AND ";
}
where += "CultureIsUICulture = 1";
}
// Loads the cultures from the Xperience database based on the where condition
DataSet ds = CultureInfo.Provider.Get()
.Where(where)
.Result;
// Binds the loaded cultures to the filter's drop-down list
drpCultures.DataSource = ds;
drpCultures.DataBind();
// Adds the '(any)' and '(default)' filtering options
drpCultures.Items.Insert(0, new ListItem("(default)", ""));
drpCultures.Items.Insert(0, new ListItem("(any)", "_any"));
}
}
///
/// Generates the SQL Where condition used to limit the data displayed in the connected UniGrid.
///
public override string GetWhereCondition()
{
string filterCultureCode = Value as string;
// Returns an empty condition if the special (any) option is selected in the filter
if (filterCultureCode.Equals("_any"))
{
return String.Empty;
}
// Returns a condition for loading users whose preferred content culture matches the filter's value.
return "(PreferredCultureCode = N'" + Value + "')";
}
}
```
The filter control is now ready to be assigned to any UniGrid component that works with user objects (and includes the _PreferredCultureCode_ column in the loaded data). For example, the following [UniGrid definition](https://docs.kentico.com/13/custom-development/extending-the-administration-interface/ui-controls/unigrid/reference-unigrid-definition.md) uses the custom filter for a column, and sets the filter's _CurrentSiteCulturesOnly_ and _UICulturesOnly_ parameters.
```xml
```
If you view the output of the UniGrid, you can use the custom filter to control which users are displayed. The filter offers culture options according to the parameters that you configured in the UniGrid definition.
