Customizing Form Widget Markup with Kentico 12

By Shelby Tieche On October 28, 2019

Customizing Form Widget Markup with Kentico 12
Kentico 12 has a new and improved Form Builder, which makes creating forms a breeze. Using Form Builder and Page Builder, with the addition of the Form Page Builder Widget, it is the perfect tool to make the process of adding forms to your website virtually painless. 

Having control of a Kentico form's markup is invaluable when you're creating an out-of-the-box experience for your clients. It also allows developers to easily match the look and feel of a website's style guide without battling existing markup. Your site's global CSS styles should handle most input styling; however, there are still times when you need to add custom markup, such as classes or attributes, to a form layout and its elements.

In this blog post, we’ll go over how to create and add custom markup to a form in Kentico 12 with Page Builder and Form Builder using C#, HTML, and CSS. 

Setting Up Form Layouts from Page Builder Sections

By default, Kentico Form Builder comes with two Form Sections: Default and Two columns. Form Sections are the area of page builder that can hold multiple fields to allow you as the developer to use not only full width but multiple column layouts within your form and it’s fields.  This is beneficial because this allows developers to easily control the layout of forms by adding custom layout classes that can be styled by other layout modes such as Flexbox in CSS.  

If you would like to create more advanced Form Sections, reference Kentico’s documentation on how to create and register custom Form Sections here.  For this article, we will use the Default Form Section that uses Bootstrap markup.

Creating a form in Form Builder and adding it to Page Builder

Once you have your already default or custom Form Sections available, you are ready to start creating your form in Form Builder. With Kentico 12, adding the ability to combine these different layouts on the fly for certain inputs to me personally is a game-changer. I recall in past Kentico versions having to write out custom HTML layouts in the Layout tab and wrapping custom macros that I could never remember the name of in repetitive HTML code. Form Builder cuts out these HTML layout headaches and allows not only you as the developer, but the client to easily create beautifully formatted forms. Below is an example of the Form I created in Kentico Form Builder and the markup for a custom Form Section using Flexbox.

Form: 

Kentico Form Builder

Two Column Layout: 
 
<div class="two-column-section">
     <div class="section">
           @Html.Kentico().FormZone()
     </div>
     <div class="section">
           @Html.Kentico().FormZone()
     </div>
</div>

.two-column-section {
     @media screen and (min-width: $breakpoint-md) {
           display: flex;
 }

 .section {
           @media screen and (min-width: $breakpoint-md) {
                 flex: 0 1 50%;
           }
     }
}

Adding Custom Markup to the Form 

Once you have added your Page Section for Form Builder into your pages Index.cshtml view file, it creates an editable area in Page Builder for you to start adding Widgets. Kentico has a Form Page Builder Widget that we will be using. 

Kentico Form Page Builder Widget

Select the form you created from the list, and you will now see your form on the page. However, there is a slight problem. Your form might not look completely how you want it to look. As a developer working with clients, it is very common to be working with a style guide of some sort. And although most of your input and form styles should be already set globally in your CSS, you may want to have full control of the markup of this form still. 

To go from this:

Form Builder

To this:

Form Builder 2

How do we get full custom control of the HTML markup of a Form Builder form?


It's simple!

1. Create custom global rendering configurations for Form Builder.  Do this by creating a new FormBuilderRenderConfig class. This should be live in your App_Start folder.

Global rendering config file (/App_Start/FormBuilderRenderConfig.cs)
using Kentico.Forms.Web.Mvc;
using Kentico.Forms.Web.Mvc.Widgets;
using System.Web.Mvc;

namespace ProjectCodeName.Web.App_Start
{

   public class FormBuilderRenderConfig
   {
       public static void SetGlobalRenderingConfigurations()
       {
       }
   }
}

2. Call the new static method in your Global.asax .cs so it runs during initialization.
 FormBuilderConfig.SetGlobalRenderingConfigurations();
Once your global rendering configuration file is set up to use with Form Builder, that’s it! You can start using the FormWidgetRenderingConfiguration type to change the markup around the form, and the FormFieldRenderingConfiguration to modify the markup for each form field. You can find the list of many available properties in Kentico’s documentation for custom form markup and custom form field markup.

In this example, we will be wrapping each field in a custom div class and wrapping each label within that field section in a custom div class. We will also be getting rid of markup that is not needed that comes with Form Builder by default. First, let’s get rid of the div soup we don’t need.
public static void SetGlobalRenderingConfigurations()
       {        
           // Wraps input and explanation text
           FormFieldRenderingConfiguration.Widget.EditorWrapperConfiguration =
            new ElementRenderingConfiguration
            {
                ElementName = string.Empty
            };


           // Wraps input HTML and validation message
           FormFieldRenderingConfiguration.Widget.ComponentWrapperConfiguration =
               new ElementRenderingConfiguration
               {
                   ElementName = string.Empty
               };
       }

Next, let's add a class to each field, label, and it’s validation in a custom class. The class form-group will be the global class that will control the spacing of each of your input sections.
public static void SetGlobalRenderingConfigurations()
       {        
           // Wraps input and explanation text
           FormFieldRenderingConfiguration.Widget.EditorWrapperConfiguration =
            new ElementRenderingConfiguration
            {
                ElementName = string.Empty
            };

           // Wraps input HTML and validation message
           FormFieldRenderingConfiguration.Widget.ComponentWrapperConfiguration =
               new ElementRenderingConfiguration
               {
                   ElementName = string.Empty
               };
 
           FormFieldRenderingConfiguration.Widget.RootConfiguration =
               new ElementRenderingConfiguration
               {
                   ElementName = "div",
                   HtmlAttributes = { { "class", "form-group" } }
               };
       }
Finally, let's add a custom class to each label within each input section of form-group.
public static void SetGlobalRenderingConfigurations()
       {        
           // Wraps input and explanation text
           FormFieldRenderingConfiguration.Widget.EditorWrapperConfiguration =
           new ElementRenderingConfiguration
            {
                ElementName = string.Empty
            };

           // Wraps input HTML and validation message
           FormFieldRenderingConfiguration.Widget.ComponentWrapperConfiguration =
               new ElementRenderingConfiguration
               {
                   ElementName = string.Empty
               };

           FormFieldRenderingConfiguration.Widget.RootConfiguration =
               new ElementRenderingConfiguration
               {
                   ElementName = "div",
                   HtmlAttributes = { { "class", "form-group" } }
               };

           // Wraps label in markup
           FormFieldRenderingConfiguration.Widget.LabelWrapperConfiguration =
              new ElementRenderingConfiguration
              {
                  ElementName = "div",
                  HtmlAttributes = { { "class", "label" } }
              };
       }
Your form’s field markup should now look something like this.
<div class="form-group">
  <div class="label">
    <label 
      class="control-label required-field" 
      for="form-CustomForm-c7e1_FirstName_Value">
      First Name
    </label>
  </div>
  <input
    aria-required="true"
    class="form-control"
    data-ktc-notobserved-element=""
    id="form-CustomForm-c7e1_FirstName_Value"
    name="form-CustomForm-c7e1.FirstName.Value"
    required=""
    type="text"
    value=""
  />
  <div
    class="field-validation-valid"
    data-valmsg-for="form-CustomForm-c7e1.FirstName.Value"
    data-valmsg-replace="true"
  ></div>
  <div
    class="field-validation-valid"
    data-valmsg-for="form-CustomForm-c7e1.FirstName"
    data-valmsg-replace="true"
  ></div>
</div>
As stated above, you can use the FormWidgetRenderingConfiguration type, like the FormFieldRenderingConfiguration type used in this post, to add custom markup to the form as a whole. It gives the ability to add a wrapper class to target a specific form with a page specific class,  also the control to add custom  HTML attributes to the submit button as well. 
FormWidgetRenderingConfiguration.Default =
new FormWidgetRenderingConfiguration 
 {
     // Submit button HTML attributes
     SubmitButtonHtmlAttributes = { { "class", "btn btn-primary" } }
 };

The Benefits

Having all of these properties and options gives you as the developer full control as to how you want to create the look and feel for your website’s Form Builder forms. It is a great tool to create reusable, responsive, and site branded forms with ease. 

Keep your eyes peeled for my next addition to this series, where I dive into how you can keep working with Form Builder customizations to add contextual markup and HTML to forms to do things like targeting specific input types for custom styling, validation, as well as ADA compliance.

Also, tell me what you think! Have you been liking Kentico 12’s new Page Builder and Form Builder? What are you implementing in your code to keep your Forms clean and consistent? Let me know in the comments below. 

Share This Post:

Twitter Pinterest Facebook Google+
Click here to read more Kentico posts
Start a Project with Us

About the author

When Shelby was thirteen she didn’t realize that the hours she spent staying up late building themes and layouts for MySpace and Xanga pages would later inspire her future career choice. As a recent grad from Michigan State and an even more recent Texas transplant, she now applies her knowledge to the front-end development team at BizStream. Shelby is excited to be back in the Grand Rapids area where she frequents music venues and local breweries.

View other posts by Shelby

Subscribe to Updates

Stay up to date on what BizStream is doing and keep in the loop on the latest with Kentico.