Filtering form components

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 - System form 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 };
        }
    }
}

Registering filters

Register filters by adding them to the FormBuilderFilters.FormComponentFilters collection on application start. For example, as part of custom module initialization code, or in your application’s startup code.

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

using Kentico.Forms.Web.Mvc;

...

protected void Application_Start()
{
    ...

    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());
}

using Kentico.Forms.Web.Mvc;

... 

protected void ConfigureServices() 
{ 
    ... 
    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()); 
}

Registering 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:

using Kentico.Forms.Web.Mvc;

...

protected void Application_Start()
{
    ...

    RegisterFormComponentFilters();
}

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

    // Hides all default system form components
    FormBuilderFilters.FormComponents.Add<FormComponentsFilter>();
}

using Kentico.Forms.Web.Mvc;

... 

protected void ConfigureServices() 
{ 
    ... 
    RegisterFormComponentFilters(); 
} 

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