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:

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. 

Follow these steps to create a form component:

1. Open your live site 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 (e.g., 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 ~/Models/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 Xperience 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, Xperience 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 Xperience from monitoring a form component:

   1. Override the virtual CustomAutopostHandling property, inherited from the FormComponent base class, and set it to true, which ensures Xperience 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.

   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.
   Copy

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

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. For the list of available data types or to learn how to register custom data types suitable for your component, see Managing field data types.

     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.

     • Annotate the property with the DefaultValueEditingComponentattribute to specify the form component providing the default value editing interface in the form builder properties panel. For a full list of system form components, refer to Reference - System form components.

   • (Optional) Declare additional propertiesthe form component requires.

   Copy

   
   
   
            // 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 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.Kentico().GetEditorHtmlAttributes extension method (from the Kentico.Forms.Web.Mvc namespace). You can modify the collection to include additional 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 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 definition of additional 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.

      Modal dialogs

      You can also implement modal dialogs to be able to handle more complex inputs in a new pop-up dialog.

   _CustomFormComponent.cshtml

   Copy

   
   
   
    @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.Kentico().GetEditorHtmlAttributes();
    }
   
    @model LearningKit.FormBuilder.FormComponents.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 Xperience 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 – a 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 the Icon list.

  Localizing form component metadata

  Both the Name and the Description of form components can be localized using resource string keys. See Localizing 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.IDENTIFIER, 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.

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

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