Defining form component properties

Alongside their front-end logic, form components contain a set of properties that can be exposed to users via the properties panel of the form builder, or a widget's configuration dialog. Using the provided interface, users can, for example, modify a form field's label, tooltip, required status, etc.

The properties panel lists all editable properties belonging to the currently selected form component. The editing interface for each property is provided by another form component and is fully customizable. This relationship is illustrated by the following screenshot:

Form component relationship overview

Form components acting in this capacity are referred to as editing components in the documentation.

On this page, you will learn about:

  • Defining properties for custom form components
  • System properties shared by every form component
  • Exposing properties for editing by assigning editing components
  • Configuring the properties of assigned editing components 

Defining properties for custom form components

You can define custom properties for each component in its corresponding properties class. To expose these properties for editing, use the EditingComponent attribute.

See Example - Defining a 'Character size' property.

System properties of components

Each form component inherits basic system properties from the FormComponentProperties base class:

PropertyDescription

Additional information

LabelThe label text displayed in the properties panel.

Can be localized by setting the value to an expression in format {$key$}. Replace "key" with the key of a resource string.

Required

When true, the form can only be submitted if the field has a value specified.

SmartField

Indicates whether the field behaves as a smart field.

Fields marked as smart are displayed only on repeated views of a form, as a replacement for other fields that were already filled in by the given visitor.
DefaultValueThe default value of the property's input field.
NameThe unique identifier of fields within the given form. If a user adds multiple fields based on the same component to a form, the system automatically appends a number to the default name.
SizeSets the size of the underlying database column.

When configured, it overrides the size set in the form component's properties class constructor.

If configured for an editing component (e.g., in a widget configuration dialog), sets the maximum number of characters the property can contain.

PrecisionThe number of digits floating point numbers stored in the database can contain.When configured, it overrides the precision set in the form component's properties class constructor.

ExplanationText

A short message usually displayed under the input field.

Can be localized by setting the value to an expression in format {$key$}.
Tooltip

The tooltip of the property displayed on hover.

Can be localized by setting the value to an expression in format {$key$}.
PlaceholderSets a placeholder text for the input field of the component. 

The system offers a set of attribute annotations you can use to display and configure additional component properties, namely:

Assigning and configuring editing components

Only some system properties are editable on a component's properties panel by default. To expose additional system or custom properties to users, annotate them with the EditingComponent attribute.

The EditingComponent attribute assigns a form component to provide an editing interface for the annotated property (the specified component acts as the property's editing component). The attribute takes the string identifier of a form component as its argument.

Identifiers of system form components are contained in the IDENTIFIER constant exposed by system form component classes. See Reference - System form components.

The following example shows the declaration of a property that has the TextInputComponent form component assigned as its editing component.

        // Assigns the 'TextInputComponent' as the editing component of the 'CustomProperty' property
        [EditingComponent(TextInputComponent.IDENTIFIER)]
        public string CustomProperty { get; set; }

The data type (i.e., string, decimal, etc.) of the editing component must correspond to the data type of the property being annotated.

You have configured the component's property. If you select a field backed by the customized form component, you can see the changes reflected in the field's properties panel.

See Example - Defining a custom 'Character size' property for an example implementation of a custom property that enables users to set the 'size' attribute of a form field.

The EditingComponent attribute also provides a shorthand for configuring some of the component's system properties via its optional constructor parameters. You can configure the following properties:

  • Label
  • DefaultValue
  • Tooltip
  • ExplanationText
  • Order - the order in which the properties appear in the editing interface.

MVC framework data annotation attributes 

You can use data attributes provided by the MVC framework in the System.ComponentModel.DataAnnotations namespace to annotate properties. For example, to set a property as required, annotate it with the Required attribute:

        // Assigns the 'IntInputComponent' as the editing component of the 'MyProperty' property and configures its system properties
        [EditingComponent(IntInputComponent.IDENTIFIER, ExplanationText = "Please enter a number", Label = "Custom property", Tooltip = "Stores a numeric value.", Order = 0)]
        [Required]
        public int MyProperty { get; set; }

Overriding the editing components of system properties

All system properties use system form components as their editing components. You can assign different editing components for these properties by overriding them in the properties class used by your form component, and designating different editing components using the EditingComponent attribute.

The following example overrides the base implementation of the Tooltip and Label properties, assigns them custom editing components, and configures some of their system properties using optional constructor parameters of the EditingComponent attribute:

        // Overrides the Label property and sets its editing component to 'TextInputComponent'
        [EditingComponent(TextInputComponent.IDENTIFIER, Label = "Label")]
        public override string Label { get; set; }
 
 
        // Overrides the Tooltip property and sets its editing component to 'TextInputComponent'
        [EditingComponent(TextInputComponent.IDENTIFIER, Label = "Tooltip")]
        public override string Tooltip { get; set; }
Alternatively, you can use the DefaultValueEditingComponent attribute to simplify the assignament of an editing component for the DefaultValue property:
        // 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;
        } = "DefaultValue";

Configuring editing component properties

By default, form components designated as editing components use the initial values of their properties. To configure an editing component's property values, add the EditingComponentProperty attribute with the following parameters:

  • PropertyName – a string name of the property that you wish to set.
  • PropertyValue – a value to assign to the property. For properties with text values, you can set localized values through expressions in {$key$} format. Replace "key" with the key of the resource string that stores the appropriate text localizations.

The following sample code demonstrates this attribute:

        // Enables the 'ACustomProperty' property for editing via the properties panel and assigns 'CustomFormComponent' as its editing component
        [EditingComponent("CustomFormComponent")]
        // Sets the editing component's 'MyProperty' property to '10'
        [EditingComponentProperty("MyProperty", 10)]
        // Sets the editing component's 'CustomProperty' to a localized value using the 'customproperty.value' resource string
        [EditingComponentProperty("CustomProperty", "{$customproperty.value$}")]
        public string ACustomProperty { get; set; }

Example - Defining a 'Character size' property

This example demonstrates how to declare and configure a property that sets a field's width to exactly fit the specified number of characters:

  1. Open your project in Visual Studio.
  2. Declare a new property in a component properties class and configure it using the EditingComponent attribute:

        public class CharacterSizeProperties : FormComponentProperties<string>
        {
            // Gets or sets the default value of the form component and the underlying field
            [DefaultValueEditingComponent(TextInputComponent.IDENTIFIER)]
            public override string DefaultValue
            {
                get;
                set;
            }
     
     
            // Defines a custom property and its editing component
            [EditingComponent(IntInputComponent.IDENTIFIER, Label = "Size", DefaultValue = 40, Tooltip = "Enter the number of characters the field's width should be set to.", ExplanationText = "Sets the field's width to exactly fit the specified number of characters", Order = -95)]
            public int CharacterSize { get; set; }
     
     
            // Initializes a new instance of the properties class and configures the underlying database field
            public CharacterSizeProperties()
                : base(FieldDataType.Text, 500)
            {
            }
        }
    

  3. In the view templates of form components utilizing the extended properties class, set the 'size' attribute of the <input> element to the value of the custom property.

    @using Kentico.Forms.Web.Mvc
     
    @model LearningKit.FormBuilder.FormComponents.CustomPropertyComponent
     
    @{
        @* Gets a collection of system HTML attributes necessary for the correct functionality of the form component inputs *@
        var htmlAttributes = ViewData.GetEditorHtmlAttributes();
     
        @* Specifies additional HTML attributes for the form component *@
        htmlAttributes["size"] = Model.Properties.CharacterSize;
    }
     
    @* Renders the input element for the 'Value' property of the form component *@
    @Html.TextBoxFor(m => m.Value, htmlAttributes)
    

  4. Save the changes and Build your project.

The custom property can now be edited on the properties panel of form components using the modified properties class. When editors configure the property, the width of the input field is set to exactly fit the specified number of characters.


Was this page helpful?