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

Define a form component
Register the component in the system
Add CSS for the component
Add custom client scripts for the component

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 TValuetype needs to be identical for both classes. Each component also requires a corresponding view template that describes how its input elements are rendered.

MVC Areas

Form components are designed to be used in the global scope and therefore must be registered in the application root of your MVC project (not in an MVC Area). Registering form components in MVC Areas may lead to unexpected behavior.

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

Follow these steps to create a form component:

Open your MVC project in Visual Studio.
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 (e.g., a basic data type such as string, int or bool).
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 ~/Models/FormComponents folder.

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.updatableFormHelper.updateForm(this.form), within your 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.
1. (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>
    {
        public const string IDENTIFIER = "CustomFormComponent";

        // 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;
        }
    }

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)

Developing form components

Developing form components

Registering form components

Adding CSS styles for form components

Adding scripts for form components

Initializing component scripts

Using jQuery scripts