Form component filtering

Form component filtering allows you to hide form components from the Form Builder’s user interface. For example, if you develop a custom version of one of the system’s default components, you can help users choose the correct one by hiding the original.

Creating filters

Form component filters are classes that implement the IFormComponentFilter interface and its Filter method. The method’s parameters give you access to the following objects:

IEnumerable<FormComponentDefinition> – a collection of definitions representing the available form components. Each contains metadata under which the form component was registered into the system, such as the identifier, name, or description.
FormComponentFilterContext – contains contextual information about the form being edited via the Form Builder interface, such as the form code name. You can use the information to provide a different set of components for specific forms.

The Filter method needs to return the collection of the filtered form component definitions.

The following example filters all default Xperience form components from the Form Builder user interface.



using System.Linq;
using System.Collections.Generic;

using Kentico.Forms.Web.Mvc;
using Kentico.Forms.Web.Mvc.FormComponents;

namespace LearningKit.FormBuilder
{
    public class FormComponentsFilter : IFormComponentFilter
    {
        public IEnumerable<FormComponentDefinition> Filter(IEnumerable<FormComponentDefinition> formComponents, FormComponentFilterContext context)
        {
            // Filters out all Xperience form components from the Form Builder UI
            return formComponents.Where(component => !component.Identifier.StartsWith("Kentico"));
        }
    }
}

You can also filter out individual Xperience form components by matching their identifiers with the IDENTIFIER constant exposed by each form component class. See Reference - Form Builder components.



using System.Linq;
using System.Collections.Generic;

using Kentico.Forms.Web.Mvc;
using Kentico.Forms.Web.Mvc.FormComponents;

namespace LearningKit.FormBuilder
{
    public class IndividualFormComponentsFilter : IFormComponentFilter
    {
        public IEnumerable<FormComponentDefinition> Filter(IEnumerable<FormComponentDefinition> formComponents, FormComponentFilterContext context)
        {
            // Filters specified form components
            return formComponents.Where(component => !GetComponentsToFilter().Contains(component.Identifier));
        }

        // A collection of form component identifiers to filter
        private IEnumerable<string> GetComponentsToFilter()
        {
            return new string[] { TextInputComponent.IDENTIFIER, TextAreaComponent.IDENTIFIER, USPhoneComponent.IDENTIFIER };
        }
    }
}

Register filters

Register filters by adding them to the FormBuilderFilters.FormComponentFilters collection on application start.

Note that the filtering is cumulative. The process starts with the collection of all form components registered in the system. Each subsequently applied filter then works with the collection of form components returned by the previous filter:

Example - Register form component filters



using CMS;
using CMS.DataEngine;

using Kentico.Forms.Web.Mvc;

[assembly: RegisterModule(typeof(FormComponentFilters))]

public class FormComponentFilters : Module
{
    // Module class constructor, inherits from the base constructor with the code name of the module as the parameter
    public FormComponentFilters() : base("FormComponentFilters")
    {
    }

    // Initializes the module. Called when the application starts.
    protected override void OnInit()
    {
        base.OnInit();

        RegisterFormComponentFilters();
    }

    private void RegisterFormComponentFilters()
    {
        // Selectively hides default system form components 
        FormBuilderFilters.FormComponents.Add(new IndividualFormComponentsFilter());
        // Hides all default system form components 
        FormBuilderFilters.FormComponents.Add(new FormComponentsFilter());
    }
}

Register filters that use dependency injection

Form component filter classes support dependency injection and their constructor can have parameters (e.g., instances of services registered in the project’s DI container).

Such filters must be registered into the FormBuilderFilters.FormComponentFilters collection using the Add<FilterClassType> method:

Example - Register form component filters



using Kentico.Forms.Web.Mvc;

...   

protected override void OnInit()
{
   base.OnInit();
   RegisterFormComponentFilters();
}

private void RegisterFormComponentFilters() 
{ 
    // Selectively hides default system form components 
    FormBuilderFilters.FormComponents.Add<IndividualFormComponentsFilter>(); 
    // Hides all default system form components 
    FormBuilderFilters.FormComponents.Add<FormComponentsFilter>(); 
}