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 Kentico 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 Kentico form components from the form builder UI
            return formComponents.Where(component => !component.Identifier.StartsWith("Kentico"));
        }
    }
}

You can also filter out individual Kentico 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 the Application_Start method in Global.asax.cs.

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