Developing custom form layouts

The layout of forms composed via the Kentico form builder is based on elements called sections. Each form section defines a block of HTML code containing one or more zones. These zones can then hold any number of form fields (based on form components).

When creating forms in the form builder interface of the Forms application, editors first add or adjust the sections, and then add individual fields into the resulting zones.

The system provides a Default form section which organizes fields in a basic single-column layout (one zone). The default section is automatically added into new forms, and in cases where an editor removes the last section from a form. If you wish to use more advanced layouts for fields in your forms, you need to develop and register your own form sections.

Developing form sections

Form sections are implemented as controllers that return HTML markup containing form zones.

Form sections 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 sections in MVC Areas may lead to unexpected behavior.

Implementing form section controllers

When creating controllers for form sections, implement the default Index action which retrieves the section markup. The action must return the section’s HTML content, typically a partial view.

The recommended location to store form section controllers is the ~/Controllers/FormSections folder.

    public class TwoColumnFormSectionController : Controller
    {
        // Action used to retrieve the section markup
        public ActionResult Index()
        {
            return PartialView("FormSections/_TwoColumnFormSection");
        }
    }

Registering form sections

Register sections by adding the RegisterFormSection assembly attribute to the controller class. Specify the following attribute parameters:

• Identifier – a string identifier of the form section. We recommend using sufficiently unique identifiers to avoid potential conflicts with other third-party sections, for example using a company name prefix.
• Controller type – the System.Type of the form section controller class.
• Name – the name of the form section. Displayed when selecting sections on the Form builder tab in the administration interface.
• (Optional) Description – a description of the form section. Displayed as a tooltip when selecting sections on the Form builder tab in the administration interface.
• (Optional) IconClass – the font-icon assigned to the form section. Displayed when selecting sections on the Form builder tab in the administration interface. For a list of font icons available by default in the system, see Kentico icon list.

using Kentico.Forms.Web.Mvc;

[assembly: RegisterFormSection("LearningKit.FormSections.TwoColumns", typeof(TwoColumnFormSectionController), "Two columns", Description = "Organizes fields into two equal-width columns side-by-side.", IconClass = "icon-l-cols-2")]

The section is now available in the form builder interface.

Implementing form section views

Create partial views with the required formatting. Use the FormZone extension method to identify locations where form fields can be placed.

The recommended location for the view files is the ~/Views/Shared/FormSections folder.

@using Kentico.Forms.Web.Mvc
@using Kentico.Web.Mvc

<div>
    <div style="float:left; width:50%;">
        @Html.Kentico().FormZone()
    </div>
    <div style="float:left; width:50%;">
        @Html.Kentico().FormZone()
    </div>
    <div style="clear:both;" />
</div>

Adding CSS styles for form sections

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

• For basic styles that are required for the section to render correctly, create stylesheet files in sub-folders under the ~/Content/FormSections directory of your MVC project (you may need to create the FormSections directory). Use sub-folders that match the identifiers of individual sections.

• If you wish to provide additional styling for the Kentico administration interface (for example to ensure that the sections 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 section should be handled separately within the given site’s main stylesheet.

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

The system automatically creates bundles containing all .css files located under ~/Content/FormSections – 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 components in the ~/Content/FormComponents directory.

Adding scripts for form sections

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

The system automatically creates a bundle containing all .js files located under ~/Content/FormSections. 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 components in the ~/Content/FormComponents directory.

Initializing section scripts

If you need to initialize scripts (for example register an event listener), you can add script tags directly into the view code of your form builder sections. However, you need to keep the following in mind:

• Do not rely on the order of execution of multiple script tags within one section. The order of their execution may be different in the form builder interface than on the live site.

• If you declare variables within section script tags, the variables are defined in the global namespace. To prevent conflicts in forms containing multiple instances of the same section, wrap the scripts into a self-executing anonymous function.

• If you use assets stored in the ~/Content/FormSections folder within the section views, the related bundles are added at the end of the HTML document’s body tag. Such assets are not available in the section code during the page load process. A solution is to run the initialization script during the DOMContentLoaded event. However, sections in the form builder interface 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:

  Copy

  
  
  
    @using Kentico.Forms.Web.Mvc
    @using Kentico.Web.Mvc
  
    <div>
        @Html.Kentico().FormZone()
    </div>
    <script type="text/javascript">
    (function () {
        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 section is rendered dynamically after 'DOMContentLoaded'
            customFunction(); 
        }
    })(); 
    </script>
  
  
    

Apart from initialization code, avoid linking or executing scripts directly within form section views. This could lead to duplicated scripts for forms that contain multiple instances of the same section, 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 sections, you need to create your own bundle(s) with the corresponding paths:

• ~/bundles/jquery
• ~/bundles/jquery-unobtrusive-ajax – bundle for using the jquery.unobtrusive-ajax.js JavaScript library (not to be confused with the jquery.validate.unobtrusive.js 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.