Reference - System form components

This page lists all components that are available for the form builder by default in new installations of Xperience. For details on how to programmatically configure these components when used in the widget configuration dialog, or in the form builder, see Assigning editing components to properties. 

Configuring selector editing components

When using selector components as editing components, configure the DataSource property to define their options. You can either specify a list of values, or a semicolon-separated list of values and text. Each option needs to be entered on a separate line. For example:

        // Assigns a selector component to the SelectedOption property
        [EditingComponent(DropDownComponent.IDENTIFIER)]
        // Configures the list options available in the selector
        [EditingComponentProperty(nameof(DropDownProperties.DataSource), "cz;Czech Republic\r\nusa;United States")]
        public string SelectedOption { get; set; }

Alternatively, you can load the items from a dynamic data source. See Using a dynamic data source with selector components for more information.

    // Sets "." as the delimiter for the options
    [EditingComponentProperty(nameof(DropDownProperties.DataSourceValueSeparator), ".")]

Configuring the File uploader

The following settings from the Settings application allow you to configure the behavior of the File uploader form component:

• System → Files → Custom form files folder – sets a custom folder used to store files uploaded using the form component. See Settings - Files.
• System → Files → Upload extensions – allows you to specify a list of file extensions users are allowed to upload using the form component. See Settings - Files.

All files are automatically synchronized across the live-site and administration projects using web farms.  In cases where you expect large volumes of user data to be uploaded, or you wish to keep all files in a shared location to prevent needless duplication, it is beneficial to map the form files folder to a shared location.

The remainder of this sections details further configuration of the form component and corresponding system settings:

• Limiting the maximum uploadable file size – describes how to set the maximum allowed size of uploaded files.
• Denial of service protection – describes measures the system employs as prevention against malicious attacks.

Limiting the maximum uploadable file size

<system.webServer>
    <security>
        <requestFiltering>
            <requestLimits maxAllowedContentLength="MAXSIZE_IN_BYTES" />
        </requestFiltering>
    </security>
</system.webServer>
<system.web>
    <httpRuntime maxRequestLength="MAXSIZE_IN_KILOBYTES" />
</system.web>

<location path="Kentico.FormBuilder/FormFileUploader">
    ...
</location>

using Kentico.Forms.Web.Mvc;

public void ConfigureServices(IServiceCollection services)
{
    ... 

    // Sets the maximum file size of files uploaded using the 'File uploader' form component to 100MB
    // You can also load this value from any configuration source using the configuration provider pattern 
    services.Configure<FormBuilderOptions>(options => options.FileUploaderFileSizeLimit = 1024 * 100);
}

Denial of service protection

<!-- Sets the folder size limit to 1000 MB -->
<add key="CMSTemporaryUploadFilesFolderSizelimit" value="1000" />

using Kentico.Forms.Web.Mvc;

public void ConfigureServices(IServiceCollection services)
{
    ... 

    // Sets the temporary folder size limit to 1000MB
    // You can also load this value from any configuration source using the configuration provider pattern 
    services.Configure<FormBuilderOptions>(options => options.TemporaryUploadFilesFolderSizeLimit = 1000);
}

The system deletes the contents of the temporary folder once every two hours using the Delete old temporary upload files scheduled task (which runs via the administration project). If you wish to modify this behavior, for example in cases where you expect higher volumes of form submissions containing large files, you can override the default two hour interval by configuring the CMSDeleteTemporaryUploadFilesOlderThan setting key in the <appSettings> section of the administration project’s web.config file.

<!-- Sets the folder cleanup period to one hour -->
<add key="CMSDeleteTemporaryUploadFilesOlderThan" value="1" />

Configuring reCAPTCHA

You need to register your site to use the reCAPTCHA API and obtain a pair of API keys:

1. Go to https://www.google.com/recaptcha/admin and sign in with your Google account.
2. Select the reCAPTCHA type that you wish to use.
   • For reCAPTCHA v2, choose the “I’m not a robot” Checkbox option.
3. Fill in all required details, including the domain where your site is running (the presentation domain of your live site).
4. Copy your Site key and Secret key.

Next, enter your site’s reCAPTCHA API keys into Xperience:

1. Open the Settings application in the administration interface.

2. Navigate to the Security & Membership → Protection settings category.

3. Under reCAPTCHA v2 or reCAPTCHA v3 section, paste the API keys into the Site key and Secret key settings respectively.

4. When using reCAPTCHA v3, set the default Score threshold required for the validation to be successful. You can override the score threshold when adding the reCAPTCHA component to individual forms.

5. Save the settings.

   Tip: If you run multiple sites in your Xperience instance, you can switch between them using the Site selector and enter different API keys for each site.

With the API keys entered into the system, the reCAPTCHA form component now works in forms. When composing forms, the form builder interface allows users to configure additional properties for specific reCAPTCHA fields.

reCAPTCHA v2

• Theme – sets the appearance of the reCAPTCHA element (Light or Dark).
• Size – sets the size of the reCAPTCHA element (Normal or Compact).
• Type – sets the type of challenge used if the initial noCAPTCHA validation fails (Image or Audio).

reCAPTCHA v3

• Score Threshold – reCAPTCHA returns a score for every request between 0.0 (very likely a bot) and 1.0 (very likely a good interaction). This threshold determines the score that must be reached for the form validation to be successful. Set a higher value if you have issues with spam or bots, and a lower value if you wish to simplify accessibility for users.

  If the validation fails for a user, there are no further challenges and form submission is not possible. In these cases, users can attempt to refresh the page again.

• Theme – sets the appearance of the reCAPTCHA badge (Light or Dark).

• Badge Position – Bottom right and Bottom left display the reCAPTCHA badge in the corresponding position at the bottom of the form. Inline displays the reCAPTCHA badge as a standard field within the form.

reCAPTCHA privacy and personal data handling

The reCAPTCHA API works by collecting hardware and software information, such as device and application data, and sending this data to Google for analysis. However, the reCAPTCHA form component is not integrated with the consent functionality in Xperience. If required, you need to display any required privacy information to site visitors and collect consents manually.

For users in the European Union, you must comply with Google’s EU User Consent Policy.

Using multiple reCAPTCHAs on the same page

The system does not support the use of multiple reCAPTCHA fields within the same form. You can have multiple different forms with a reCAPTCHA field on the same page.

Customizing reCAPTCHA messages

If you wish to change the error messages that reCAPTCHA displays to users, create custom resource strings with the appropriate keys and enter the required text content as the translation values for specific cultures.

Important: The resource strings must be added to your live site application.

Use the following resource string keys for error messages related to basic verification:

• recaptcha.error.missing-input-response – displayed when a user does not provide the required input, for example when the validation checkbox is not clicked.
• recaptcha.error.invalid-input-response – displayed when the user’s input is invalid or malformed.

You can also use the following resource string keys for other technical errors:

• recaptcha.error.serverunavailable – the reCAPTCHA server is unavailable.
• recaptcha.error.bad-request – the validation request is invalid or malformed.
• recaptcha.error.invalidconfiguration – the reCAPTCHA site and secret key settings are not configured in Xperience.
• recaptcha.error.missing-input-secret – the secret API key is missing.
• recaptcha.error.invalid-input-secret – the secret API key is invalid or malformed.
• recaptcha.error.timeout-or-duplicate – timeout or the same form contains multiple reCAPTCHA fields.