Walkthrough: Creating a custom form element

Current version: 9.3

Sitecore Forms comes with default form elements that you can drag onto your form. To build a custom form element, you create:

  • A new field template.

  • A new class that derives from the FieldViewModel class (for Simple field types such as an integer field or a multi-line text field ) or from the ListViewModel class (for List field types such as a drop-down list).

  • A razor view file.

  • A field type item that uses the razor view file to do the rendering.

You can also add custom validation to elements.

This walkthrough takes you through the steps to create a custom form element for a video. It describes how to:

  • Create a field template

  • Create a new class

  • Create a razor view file

  • Create the sections for the Form elements pane

  • Configure the field editor parameters

  • Create the field type item

  • Enable the custom field type for operators

Create a field template

A Sitecore template defines form elements. To create a new element, first create a field template.

To create a field template:

  1. In the Content Editor, go to sitecore/Templates and create a new folder (for example, a folder called Fields).

  2. In the content tree, click the new folder and, on the Folder tab, click New Template.

  3. On the Select name page, in the Name field, enter a name for the template and, in the Base template field, select the Field template (Templates/System/Forms/Fields/Field) and then click Next.

  4. On the Location page, select the folder where you want to store the template, click Next, and then click Close.

  5. In the content tree, with the new template selected, click the Builder tab.

  6. Add the following template fields:

    • URL (Single-Line Text)

    • Width (Integer)

    • Height (Integer)

  7. For each template field, on the Content tab in the Data section, select the Shared check box and, in the Message dialog box, confirm your change.

  8. In the content tree, click the new template and, on the ribbon, click the Options tab, and then click Standard values.

  9. On the ribbon, click Save to save the template.

Note

It is important to create standard values for the field templates because the standard values are used as the default field values when the field is added from the form elements pane to the form canvas. If a field template does not have standard values, you cannot drop the element onto the form.

Create a new class

Next, create the logic for the View model by creating a new class that derives from the FieldViewModel class. To create a custom element by customizing an existing form element and extending its functionality, you must inherit from the respective element class. For example, if you want to create a new list element, you can inherit from the ListViewModel class.

Note

You control how the form element displays by arranging the HTML and inserting your own CSS classes.

To add the new class:

  1. In Visual Studio, create a new class library project (for example, FormsDemo).

  2. Add the FieldViewModel class. For example, add the VideoViewModel class:

    public class VideoViewModel : FieldViewModel

    Note

    The models of the posted fields are stored in session state. They must be marked [Serializable] in order to be stored.

  3. Add the properties. For example, add the Url, Width, and Height.

    RequestResponse
    namespace FormsDemo
    {
      [Serializable]
      public class VideoViewModel : FieldViewModel
      {
    	public string Url { get; set; }
    
    	public int Width { get; set; }
    
    	public int Height {get; set;}
    
    	protected override void InitItemProperties(Item item)
      {
        // on load of the form
        base.InitItemProperties(item);
      
            Url = StringUtil.GetString(item.Fields["Url"]);
    	Width = MainUtil.GetInt(item.Fields["Width"]?.Value, 0);
    	Height = MainUtil.GetInt(item.Fields["Height"]?.Value, 0);
      }
  4. Override the InitItemProperties and the UpdateItemFields methods.

    RequestResponse
    protected override void InitItemProperties(Item item)
    {
    	// on load of the form
    	base.InitItemProperties(item);
    	
    	Url = StringUtil.GetString(item.Fields["Url"]);
    	Width = MainUtil.GetInt(item.Fields["Width"]?.Value, 0);
    	Height = MainUtil.GetInt(item.Fields["Height"]?.Value, 0);
    }
    
    protected override void UpdateItemFields(Item item)
    {
    	// upon save
    	base.UpdateItemFields(item);
    	
    	item.Fields["Url"]?.SetValue(Url, true);
    	item.Fields["Width"]?.SetValue(Width.ToString(CultureInfo.InvariantCulture), true);
    	item.Fields["Height"]?.SetValue(Height.ToString(CultureInfo.InvariantCulture), true);
    }
  5. Build the project and deploy the FormsDemo.dll to the Sitecore website bin folder.

Create a razor view file

After you've created the new class, the next step is to create a razor view file to embed a template into your form, in this example, a video element.

To create a razor view file:

  1. For example, for the video element, create the Video.cshtml razor view file:

    Video.cshtml razor view file.
  2. Add the razor view file to the new class library project that you created earlier. The default razor view files for Sitecore Forms are stored in: Website/Views/FormBuilder/FieldTemplates. For example, add the Video.cshtml file to the FormsDemo folder and save.

    Views/FormBuilder/FieldTemplates.

Create the sections for the Form elements pane

Note

For the example in this walkthrough, you must have the Sitecore Rocks Visual Studio plugin. The plugin is compatible with Visual Studio 2019 or earlier.

Now you can add the sections that appear in the Form elements pane. For example, the Single-line text element contains the following sections: Details, Validation, Styling, and Advanced settings.

Single-line text form element.

In this example, for the video element, we want the user to be able to set the Field name, URL, Width, and Height properties.

To add sections to the Form elements pane:

  1. In Sitecore Rocks, expand the core database and right-click the Settings folder that contains the layout parameters for all field property editors: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Settings

  2. Click Add, and click New item.

  3. In the Add New Item dialog box, search for and click the Form Parameters template, enter a name, for example, Video, and click OK.

    Add new item using Form parameters template
  4. Right-click the Video item that you just created and click Add, New item.

  5. To add the new sections for your custom element, search for and click the FormSection template.

    Note

    The FormSection template is the section visualization template for the Speak form and enables you to reuse rendering parameters for the section and field editors.

  6. Enter a name for the new item and click OK. For example, enter Details to add the Details section.

    Add new item for Details section
  7. Right-click the Details item that you just created and click Add, New item.

    For example, to set the FieldName, Width, Height, and URL properties of the video item, you can reuse the FieldName item that is used in the out-of-the-box form elements.

  8. Search for and click FormTextBox Parameters, enter a name (for example, Width) and click OK.

    FormTextBox parameters
    Note

    You must select Speak 2.0 parameters.

  9. Repeat these steps to create all the relevant items, for example, the Height and URL items:

    Elements in the Video item shown in the list view.

Configure the field editor parameters

Now you must configure the parameters for each newly created field editor. For example, you can set the text and position of the label.

To configure the field editor parameters:

  1. Open the Width item and go to the Form section. Edit the following fields:

    • FormLabel – specify the textbox label that displays in the Form elements pane.

    • IsLabelOnTop – select to position the label on top of the input. For consistency, we recommend that you select this check box for all field editor properties.

    • BindingConfiguration – lists the FormData property names and corresponding component bindable properties. The left pane specifies the field model property (note that the property name is in camelCase) and the right pane specifies which editor property to read to update the field model property.

      Binding configuration
  2. In the Details section, reference the field editors in the following fields:

    • ConfigurationItem – specify the parameters for the Speak Expander. You can reuse the DetailsExpander item in: sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Sections

    • ControlDefinitions – specify the field editors that display in the Form elements pane, in order of reference. You can reuse the Fieldname item in: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Details

  3. In the ControlDefinitions field, click Fieldname, and select the Width, Height, and URL items you created earlier.

    Tip

    You can copy and modify sections you have already configured from other editors.

  4. Create the section item using the FormSection template, for example, name it Styling.

  5. To edit the Styling item, in the Data section, edit the following fields:

    • ConfigurationItem – add the reference to the Styling Expander: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Sections/StylingExpander

    • ControlDefinitions – add the reference to the CSS Class: /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Styling/CssClass

      Control definition

Create the field type item

After you have configured the parameters for the field editors, you can now create the custom field type, for example, to enable you to add a video to your form.

To create the field type item:

  1. Go to /sitecore/system/Settings/Forms/Field Types/Basic folder and add a new item.

  2. Base the item on the /System/Forms/Field Type template, enter a name and click Insert. For example, Video.

  3. Edit the Settings section fields:

    • View Path – specify the path that points to the razor view file. For example, FormsDemo/Video.

    • Model Type – specify the model type that references the class name. For example, FormsDemo.VideoViewModel,FormsDemo.

    • Property Editor – point to the item you created earlier. For example, select the property editor for the Video item.

      Set allowed validations
  4. In the Appearance section, edit the following fields:

    • Icon – select the icon that will appear in the Form elements pane. For example, OfficeWhite/32x32/videotape.png.

      Note

      To set the icon that appears in the Content Editor, make sure the Standard fields  check box is selected, and set the _Standard Values icon field value as the corresponding icon from the non-white Office theme Office/32x32/videotape.png

    • BackgroundColor – select the background color for the icon that will appear in the Form elements pane. For example, Sky.

  5. In the Field template field, specify the field template you created previously. For example, sitecore/Templates/FormsDemo/Fields/Video. When you now create a new form, the custom video element is available in the Form elements pane:

    Video element in Form elements pane

Enable the custom field type for operators

If you want to apply conditional logic to the new field type, you first need to enable it for the relevant operators. Otherwise, when you edit conditions for the field type, the list of operators will be empty.

To register the custom field type:

  1. In the Master database, open the /sitecore/system/Settings/Forms/Meta Data/Conditions/Operators root.

  2. In the tree, select the operator you want to update.

  3. In the Allowed Field Types section, add the new field.

Do you have some feedback for us?

If you have suggestions for improving this article,