Developing custom form components

Form components are reusable elements that allow content creators and marketers to compose forms via the form builder. Each component represents a specific form field, such as a text box for user input, a group of radio buttons, etc. Users are free to add, remove, or reorder individual form components and specify their properties via the form builder interface in the Forms application.

A form composed using the form builder is a collection of form component instances, where each instance represents an individual form field. Together, these instances comprise the main body of the form.

In addition to form components included in the form builder by default, you can implement custom form components tailored to your specific scenarios and requirements. Components can consist of multiple input elements. Their partial values can be, as part of the component's custom code, aggregated, and the resulting value saved into the corresponding database table.

On this page, you will learn how to:

Developing form components

All form components need to inherit from the FormComponent<TProperties, TValue> class, where the TProperties generic parameter needs to be a class derived from FormComponentProperties<TValue>, and the TValue type needs to be identical for both classes. Each component also requires a corresponding view template that describes how its input elements are rendered. 

See Example - Developing a custom form component for a full step-by-step example demonstrating how to implement and register a custom form component in the system.

Follow these steps to create a custom form component:

  1. Open your MVC project in Visual Studio.
  2. Create a form component class that inherits from FormComponent<TProperties, TValue>.
    • This class defines properties used for model binding from the component's input elements.
    • The TValue generic determines the data type of the form component's overall value (i.e., a basic data type such as string, int or bool).
  3. Create a form component properties class that inherits from FormComponentProperties<TValue>.

    • This class is used to define the properties of the form component (i.e., the component's underlying database column type, constraints, and other configuration options. See Defining form component properties).

    • The TValue generic needs to match the data type of the corresponding form component.

    We recommend storing the classes of form components under a dedicated ~/FormComponents folder.

  4. In the model class derived from FormComponent<TProperties, TValue>:
    1. Substitute the generic TProperties parameter with the type derived from FormComponentProperties<TValue>.
    2. Define properties used to pass values from the form component's input elements to Kentico for data binding, and decorate them with the BindableProperty attribute.

    3. Override the following methods:
      • GetValue – gets the value of the form field instance passed from a view where the instance is rendered. Can be used to compose multiple bindable properties into a single value.
      • SetValue – sets the class's properties based on the value of the underlying form field instance.

      Custom handling of server-side field value evaluation

      By default, Kentico monitors all input elements of form fields that possess dependencies requiring server-side evaluation. Whenever the system detects a change in the value of such inputs, it automatically submits the form to the server for evaluation. This occurs, for example, when a user fills in a form field that has a visibility condition associated with it (to check whether the depending field should be displayed or hidden).

      You may want to prevent the automatic evaluation in form components that construct their resulting value from multiple inputs (via the GetValue method). In such components, it does not usually make sense to evaluate the component's resulting value until after the values for all of the component's partial inputs have been provided, as demonstrated, for example, in the sample Rgb color selector component.

      If you wish to prevent Kentico from monitoring a form component:

      1. Override the virtual CustomAutopostHandling property, inherited from the FormComponent base class, and set it to true, which ensures Kentico does not automatically observe any of the component's inputs.
      2. Manually submit the form to the server for evaluation by calling the window.kentico.updatableFormHelper.updateForm JavaScript function with the this.form argument, i.e. window.kentico.updatableForHelper.updateForm(this.form), within your custom JavaScript code or within an element's HTML event attribute (most commonly onchange, or onclick). The form is submitted only when the function is executed, leaving it up to the component's developer to ensure this happens at an opportune moment. For example, when all the required values have been provided.

      For a sample implementation, please refer to Example - Developing a custom form component.

    4. (Optional) Override the virtual LabelForPropertyName member to specify which property the 'for' attribute of the field's <label> element targets. By default, the value of this property is set to the name of the first bindable property found within the form component class.

        public class CustomFormComponent : FormComponent<CustomFormComponentProperties, string>
        {
            // Specifies the property is used for data binding by the form builder
            [BindableProperty]
            // Used to store the value of the input field of the component
            public string Value { get; set; }
     
     
            // Gets the value of the form field instance passed from a view where the instance is rendered
            public override string GetValue()
            {
                return Value;
            }
     
     
            // Sets the default value of the form field instance
            public override void SetValue(string value)
            {
                Value = value;
            }
        }
    

  5. In the class derived from FormComponentProperties<TValue>:
    • Call the constructor of the base class and specify the data type of the underlying database column using the FieldDataType enumeration.

      The base class constructor also takes the following optional parameters:

      • size – sets the size of the corresponding component's underlying database column.

      • precision – governs the number of digits floating point numbers stored in the database can contain.

      These parameters configure the underlying database column, and need to be specified when the data type of the form component requires it, for example:

      • Specify the size parameter when defining components with the FieldDataType.Text data type – base(FieldDataType.Text, size: 200)
      • Specify the precision parameter when defining components with the FieldDataType.Decimal data type – base(FieldDataType.Decimal, precision: 10)
    • Override the DefaultValue property, used to get or set the default value of fields based on the form component.
    • (Optional) Declare additional custom properties the form component requires.

            // Sets a custom editing component for the DefaultValue property
            // System properties of the specified editing component, such as the Label, Tooltip, and Order, remain set to system defaults unless explicitly set in the constructor
            [DefaultValueEditingComponent(TextInputComponent.IDENTIFIER)]
            public override string DefaultValue
            {
                get;
                set;
            }
     
     
            // Initializes a new instance of the CustomFormComponentProperties class and configures the underlying database field
            public CustomFormComponentProperties()
                : base(FieldDataType.Text, size: 200)
            {
            }
    

  6. Create a new partial view used to render an instance of the form component and place it in the ~/Views/Shared/FormComponents folder. Use a view name that matches the identifier assigned to the form component upon its registration and prefix it with the underscore ('_') character (to indicate a partial view according to MVC best practices).

    You can override the default system behavior and place views into custom locations by specifying an optional parameter during the component registration.

    In the view:

    1. Retrieve the dictionary collection of system HTML attributes by calling the ViewData.GetEditorHtmlAttributes extension method (from the Kentico.Forms.Web.Mvc namespace). You can modify the collection to include any custom attributes the component requires, such as CSS classes and data attributes. Ensure the collection is included in each input element as certain features, such as visibility condition evaluation, may not work otherwise.

    2. Specify input elements for the component. If possible, use extension methods provided by the MVC framework's HtmlHelper class to render individual inputs as they, by default, provide an easy way to merge additional HTML attributes and ensure the inputs contain fully qualified names, facilitating model binding.
      If you need to write more complex inputs, we recommend writing an extension method that handles the creation of input elements via the TagBuilder class, which simplifies the addition of custom attributes and handles attribute encoding by default. To generate fully qualified names and identifiers for model binding, use the Html.NameFor and Html.IdFor extension methods, respectively. See Example - Developing a custom form component for an example implementation.

    _CustomFormComponent.cshtml
    @using Kentico.Forms.Web.Mvc
     
    @* Gets a collection of system HTML attributes necessary for the correct functionality of the form component inputs *@
    @{
        IDictionary<string, object> htmlAttributes = ViewData.GetEditorHtmlAttributes();
    }
     
    @model LearningKit.Models.FormBuilder.CustomFormComponents.CustomFormComponent
     
    @* Specifies additional HTML attributes of the form component. Checks for the existence of certain attributes in case 
        the returned 'htmlAttributes' collection already contains them (e.g., when the component is rendered within
        the administration interface, where Kentico provides CSS classes to maintain the admin UI look and feel) *@
    @{
        if (htmlAttributes.ContainsKey("class"))
        {
            htmlAttributes["class"] += " myclass";
        }
        else
        {
            htmlAttributes["class"] = "myclass";
        }
    }
     
    @* Renders the input element for the 'Value' property of the form component *@
    @Html.TextBoxFor(m => m.Value, htmlAttributes)
    

  7. (Optional) Write any required CSS and JavaScript code the component requires for its functionality. Place the script and style files into the ~Content/FormComponents/<FormComponentIdentifier> folder. See Adding CSS styles for form components and Adding scripts for form components for more information and recommended practices.

Registering form components

To register a form component, annotate the class derived from FormComponent<TProperties, TValue> with the RegisterFormComponent assembly attribute. This attribute ensures the component is recognized by the system and available for use in the form builder. When registering the component, specify the following parameters:

  • Identifier – string identifier of the form component. 

    If you are planning to distribute your components, or are using components from third-party sources, consider specifying the identifier in a format that uniquely identifies your form component to avoid potential conflicts with identifier names. For example, use CompanyName.ModuleName.ComponentName.

  • FormComponentType – the System.Type of the form component class.
  • Name – sets the name of the form component. Displayed when adding form fields on the Form builder tab in the administration interface.
  • (Optional) Description – sets the description of the form component. Displayed when adding form fields on the Form builder tab in the administration interface.
  • (Optional) IsAvailableInFormBuilderEditor – determines if the form component can be added as a form field. True by default. If set to false, the component can only be added via the EditingComponent attribute.
  • (Optional) ViewName – specifies the name of the view used to display the component, for example CustomComponent. If not set, the system searches for a corresponding _<Identifier>.cshtml view in the ~/Views/Shared/FormComponents/ folder.
  • (Optional) IconClass – the font-icon assigned to the form component. Displayed in the component listing when adding new fields on the Form builder tab. For a list of font icons available by default in the system, see Kentico icon list.

    Localizing form component metadata

    Both the Name and the Description of form components can be localized using resource string keys. See Localizing MVC builder components.

You can see the registration of a sample form component of the CustomFormComponent type in the code snippet below:

// Registers a form component for use in the form builder
[assembly: RegisterFormComponent("CustomFormComponent", typeof(CustomFormComponent), "Custom component", Description = "This is a custom form component.", IconClass = "icon-newspaper")]
The form component is now created and registered in the system. Users can include it when composing forms using the form builder interface.

Adding CSS styles for form components

Use the following approach to add CSS styles for your form components:

  • For basic styles that are required for the component to render correctly, create stylesheet files in sub-folders under the ~/Content/FormComponents directory of your MVC project (you may need to create the FormComponents directory). Use sub-folders that match the identifiers of individual components.
  • If you wish to provide additional styling for the Kentico administration interface (for example to ensure that components are in line with the overall look and feel of the admin UI), add another stylesheet file to the same directory with the .admin.css extension.
  • Any site-specific styles that finalize the live site design of the form component should be handled separately within the given site's main stylesheet.

    Avoid potential conflicts between styles from other third-party form components by adding a unique prefix to your CSS classes and identifiers (for example, #CompanyName-mid-button) or employ similar measures to ensure their uniqueness.

The system automatically creates bundles containing all .css files located under ~/Content/FormComponents – one for general styles and another for the administration interface styles. The bundles are then linked in the following locations:

  • When working with forms in the Forms application of the Kentico administration interface.
  • The bundle containing general styles is linked on all pages with page builder editable areas (the page builder is used to display forms on the live site via the Form widget).

The same bundles also contain styles added for form sections in the ~/Content/FormSections directory.

CSS file order

Do not make any assumptions about the relative order of the source CSS in the resulting bundles – individual files contained in the bundle may or may not precede each other.

Adding scripts for form components

If your form components require any JavaScript, place script files into sub-folders under the ~/Content/FormComponents directory of your MVC project (you may need to create the FormComponents directory). Use sub-folders that match the identifiers of individual components or a Shared sub-folder for assets used by multiple components.

The system automatically creates a bundle containing all .js files located under ~/Content/FormComponents. The bundle is then linked in the following locations:

  • When working with forms in the Forms application of the Kentico administration interface.
  • On all pages with page builder editable areas (the page builder is used to display forms on the live site via the Form widget).

The same bundle also contains script files added for form sections in the ~/Content/FormSections directory.

Initializing component scripts

In many cases, you will need to initialize your scripts from the views of form components (for example if you need to call a function on page load or register an event listener). For most types of page or element events, you can use HTML Event Attributes of elements in your views.

For scripts that you want to run on page load, you need to consider the following:

  • The bundles containing your main scripts are added at the end of the HTML document's body tag, so they are not available in the component code during the page load process. A solution is to run the initialization script during the DOMContentLoaded event.
  • Components may be added dynamically after the page is loaded. In this case, the DOMContentLoaded event has already occurred and will not fire again.

For example, the following script demonstrates how to reliably call a custom function on page load:

if (document.readyState === "loading") {
    // Calls the function during the 'DOMContentLoaded' event, after the HTML document has been completely loaded
    document.addEventListener("DOMContentLoaded", function () {
        customFunction();
    });
} else { 
    // Calls the function directly in cases where the component is rendered dynamically after 'DOMContentLoaded' has occurred
    customFunction();
}

This approach ensures that the initialization script runs correctly when the form component is displayed on the live site, as well as in the form builder interface.

Note: Apart from initialization code, avoid linking or executing scripts directly within form component views – this could lead to duplicated scripts for forms that contain multiple fields based on the same component, or on pages with multiple forms.

Using jQuery scripts

By default, Kentico links two system jQuery bundles into the pages of the form builder interface. The system jQuery version is 3.3.1. If you wish to use a different version of jQuery within your form components, you need to create your bundle(s) with the corresponding paths:

  • ~/bundles/jquery
  • ~/bundles/jquery-unobtrusive-ajax – bundle for using the jquery.unobtrusive-ajax JavaScript library

When you register a bundle with one of these paths, the form builder interface links your jQuery bundle instead of the corresponding system bundle.

Important: When you register a custom jQuery bundle, the system no longer links the default jQuery bundle on pages with page builder editable areas (the page builder is used to display forms on the live site via the Form widget). You need to manually link your custom jQuery bundle on the given pages (either within the used layout or directly in the page's view).

For more information, see Creating pages with editable areas in MVC.


Was this page helpful?