How to create a Fieldset HTML element in Forms

The scope of this post is to walk you through a detailed process of how to create a custom Form element. You can achieve the same by following the Walkthrough: Creating a custom form element page. However, I want to share a step by step process with some extra explanations and tips.

Over the past weeks, I have been working on a migration of Web Forms for Marketers to Forms. I found it would be interesting to start a series of blogs to share some of the experiences I achieved throughout this process.

Today, we are going to create HTML <fieldset> element that is used to group several controls as well as labels. You find an example below:

<form>
  <fieldset>
    <legend>Choose your favorite monster</legend>
    … Some HTML here …
  </fieldset>
</form>

The complete code can be found in my Github repository. The Sitecore package can be downloaded here.

Note: In Forms, fields are called elements.

Create a field template

When you create a Forms element, you must create a template first. The template stores values for that Forms element. For the HTML <fieldset> element, we just need a template with a label and CSS-related fields.

  1. In the Sitecore Content Editor, navigate to /sitecore/Templates and create a new template. You can create the new template wherever you prefer. However, it is recommended that you follow the structure as described in the Helix principles.
  2. Click the /sitecore/Templates/Feature folder, add a new folder named Forms, and then add a new Template.
  3. Give the template the name “Fieldset” and select as Base template: /Templates/System/Forms/Fields/Field.
  4. After the template creation, add the following additional base template /Templates/System/Forms/Label Settings template.
  5. Finally create the Standard values on the Fieldset template.
Figure 1: Fieldset field template

Every field should inherit from the /Templates/System/Forms/Fields/Field template. This is required. Now, if you want to have the fields Title and Css Label, you can reuse the base template /Templates/System/Forms/Label Settings.

Important: If a field template does not have standard values, the Forms field won’t work. The standard values items are used to populate the default Forms field values when the field is added from the form elements pane to the canvas.

Next, let’s add a checkbox field named Is Label Visible. Mark this field as “Shared”. The idea of this field is to control whether the <legend> markup will be visible.

Figure 2: Adding Is Label Visible field

Now let’s quickly switch to the Visual Studio solution.

Install required NuGet packages

Make sure you install the following packages according to the Sitecore version you are using:

  • Sitecore.ExperienceForms
  • Sitecore.ExperienceForms.Mvc
  • Sitecore.Kernel
  • Sitecore.Mvc

Note: Up to version 9.0 Update-2 you can install the *.NoReferences packages. Starting on version 9.1, you no longer have the *.NoReferences packages. However, you can use the new Nuget PackageReference feature. The Visual Studio extension NuGet PackageReference Upgrader can help you with the migration to PackageReference.

Figure 3: Sitecore Nuget Packages as PackageReference

Create a view model class

The view model class will contain all the necessary logic for the HTML <fieldset> element.

When you create new element (field) in Sitecore Forms, if you don’t need it to be persisted in database, you can simply derive the view model class from the Sitecore.ExperienceForms.Mvc.Models.Fields.FieldViewModel class.

On the other hand, when you need it to be persisted in database, you must derive the view model class from the Sitecore.ExperienceForms.Mvc.Models.Fields.InputViewModel<T> class.

The HTML <fieldset> element doesn’t need to be persisted in database, so we are going to derive the view model class from the FieldViewModel base class.

As we are reusing the /Templates/System/Forms/Label Settings base template, we also are going to derive the Fieldset view model from the Sitecore.ExperienceForms.Mvc.Models.Fields.TitleFieldViewModel class which derives from FieldViewModel class and already implement the logic for the Label and Css Label properties.

  1. Create a new class that derives from the Sitecore.ExperienceForms.Mvc.Models.Fields.TitleFieldViewModel class.
  2. Name this class FieldsetViewModel.
  3. Add the following code:
Figure 4: FieldsetViewModel class

In the code above, we observe the following:

  • We created a public property named IsLabelVisible to store the information from the Is Label Visible field from/to our Fieldset field template. It is a good practice to store the field name in a constant and reuse it across your code. You can use the Guid of the field instead.
  • The InitItemProperties method stores information in the IsLabelVisible property. InitItemProperties will be called in two moments. First, when you open the Forms application and second when you render the form in your website. The item is the Fieldset item in the content tree from a specific Form. e.g. /sitecore/Forms/Sample Form/Page/Fieldset.
  • The UpdateItemFields method reads the information from the IsLabelVisible property and persists into the corresponding field item. e.g. /sitecore/Forms/Sample Form/Page/Fieldset. The UpdateItemFields method will be called once you hit the Save button in the Forms application.
  • As Sitecore stores Boolean information as a string “1” or “0” (instead of true or false) we had to convert the Boolean value from the IsLabelVisible property to a string “1” or “0” in the UpdateItemFields method.
  • Why haven’t we implemented the logic for the Title and Css Label fields? Because the base class TitleFieldViewModel already takes care of that for us. Just make sure you invoke the base.InitItemProperties(item) and base.UpdateItemFields(item) methods.

Important: Because the view models are stored in session state they must be marked [Serializable].

The default razor view files for Sitecore Forms are stored in /Views/FormBuilder/FieldTemplates. We are going to create the Fieldset view in the FieldTemplates folder.

  1. Add the folders FormBuilder and FieldTemplates to the Views folder in your project.
  2. Next, create a new View named Fieldset (right click FieldTemplates folder -> Add -> View).
  3. Add the following code:
Figure 5: Fieldset razor view file

Note: Whenever you create Forms elements that serves as containers, you must run the html helper RenderFields which can be located in the namespace Sitecore.ExperienceForms.Mvc.Html.

Important: Don’t forget to enclose any HTML tag. That will cause a known bug. Whenever you save the Form, it will be deleted.

By now, your Visual Studio solution should look like the following:

Figure 6: Visual Studio solution

Deploy the Visual Studio project to your Sitecore instance

Having the view model class and the razor view built, now deploy the Visual Studio project to your Sitecore instance.

Figure 7: Deploying the Visual Studio solution

Create a field property editor for the Form elements pane

Next we are going to create the field property editor for the HTML <fieldset> element. A field property editor is where you can add the sections that appear in the Form elements pane. For example, the Email element contains the following sections: Details, Validation, Styling, Conditions, and Advanced settings.

Figure 8: Forms Element sections for Email element

To create the field property editor, you can either use the Content Editor or the Sitecore Rocks extension. Sitecore Rocks is a Visual Studio extension that allows you to quickly manipulate Sitecore items among other features.

  1. In Sitecore Rocks, expand the core database and navigate to /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Settings. In the Content Editor, you find the same folder by navigating to /sitecore/client/Applications/Forms/Components/Layouts/PropertyGridForm/PageSettings/Property Editor Settings.
  2. Right-click and add a new item from the template /sitecore/client/Business Component Library/version 2/Layouts/Renderings/Forms/Form/Form Parameters. Enter the name “Fieldset”.

Next we are going to add new sections to the field property editor of the Fieldset.

  1. Right-click the form parameter item named “Fieldset” we have just created and add a new item from the template /sitecore/client/Applications/FormsBuilder/Common/Templates/FormSection. Enter the name “Details”.
  2. Repeat the same step but add one more item named “Styling”

By now, you should have something similar as the image below.

Figure 9: Details and Styling sections of Fieldset field property editor

What we just did was to define two sections to the HTML <fieldset> element. The section Details will contain the properties Label and the Field name. As those properties already exist, we are going to reuse them.

Click the “Details” section of the “Fieldset” form parameter and select the following values:

ConfigurationItemsitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Sections/DetailsExpander
ControlDefinitions 1) sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Details/FieldName
2) /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Details/Label

Note: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common contains common properties defined by system. Before adding a new property, check if it doesn’t exist in the common properties.

By now the “Details” section should look like the image below:

Figure 10: Configuration of the Details section

Next, click the “Styling” section of the “Fieldset” form parameter and select the following values:

ConfigurationItem /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Sections/StylingExpander
ControlDefinitions 1) /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Styling/CssClass
2) /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Styling/LabelCssClass

By now the “Styling” section should look like the image below:

Figure 11: Configuration of the Styling section

If things seem confusing then look at the image below and see what we have just configured.

Figure 12: Changes reflected in the Forms element pane

Next, we are going to create the property for the Is Label Visible field.

  1. Right-click the Details item that you just created and add a new item from the template /sitecore/client/Business Component Library/version 2/Layouts/Renderings/Forms/Form/Templates/FormCheckBox Parameters. Enter the name “Is Label Visible”.
  2. Next, click the “ Is Label Visible” item enter the following values:
FormLabelIs Label Visible?
IsLabelOnToptrue
BindingConfigurationisLabelVisible (camel cased) | IsChecked
Figure 13: Adding a property for the Is Label Visible field

Now, click back the “Details” section of the “Fieldset” form parameter and add the “Is Label Visible” to the ControlDefinitions field.

Figure 14: Adding the “Is Label Visible” to the Controls Definition property.

Note: If you forget to add the “Is Label Visible” to the Controls Definition property, it won’t be visible in the Form element pane.

By now, you should see the Is Label Visible property in the Forms element pane.

Figure 15: Is Label Visible property

Create the field type item

Now we can create the custom field in Sitecore. To create the field type item:

  • Go to /sitecore/system/Settings/Forms/Field Types/Structure folder.
  • Right-click the Structure folder and add a new item from the template /System/Forms/Field Type, enter “Fieldset” name.

Edit the Settings section fields:

View Path
This is the path that points to the razor view file. You don’t have to add the “.cshtml” extension. By default, Forms is expecting all the views to be saved to the [site]\Views\FormBuilder folder. So that’s why you don’t have to enter the whole path.
FieldTemplates/Fieldset
Model Type
The full qualified namespace of the view model class we created in Visual Studio.
Custom.Feature.Forms.Models.Fields.FieldsetViewModel, Custom.Feature.Forms
Property EditorProperty Editor Settings/Fieldset
Field Template
As this field filters only templates available at “/sitecore/templates/System/Forms/Fields” you must enable “Raw Values” option in the View tab and paste the complete path to the Fieldset template
sitecore/Templates/Feature/Custom/Fieldset

In the Appearance section, edit the following fields:

Icon
The icon that will appear in the Forms elements pane.
OfficeWhite/32×32/document_header.png.
BackgroundColor
The background color for the icon that will appear in the Form elements pane.
Eggplant

Below is an image of how you field type should look like.

Figure 16: Data in the Fieldset field type

Test the HTML<fieldset>element

Now, open the Forms application. You should see the HTML <fieldset> element in the Forms Elements Pane.

Figure 17: Form elements pane showing the Fieldset element

Try adding a new HTML <fieldset> element.

Figure 18: Data in the Fieldset element

Don’t forget to save the changes. And check if they were persisted to the respective item in the Content Tree.

Figure 19: Data in the Fieldset element in the Content Editor

If you want to learn how to render a form in your website, please read Add a form to a webpage documentation.

Credits

Photo by Danilo Cestonato on Unsplash

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s