Walkthrough: Creating a custom form element

Last updated Thursday, November 2, 2017 in Sitecore Experience Platform for Content Author, Marketer
Keywords: Forms, Web forms

Sitecore Forms comes with default form elements that you can drag and drop on your form. To build a custom form element, you must create a new field template, a new class that derives from the FieldViewModel class, a razor view file, and a field type item that uses the razor view file to do the rendering.

This walkthrough describes how to:

Note

This walkthrough uses an example of a video element. The scenario is just an example describing the steps involved to build a custom form element.

Create a field template

A Sitecore template defines form elements. To create a new element, you must create its template first.

To add a template:

  1. In the Sitecore Content Editor, navigate to sitecore/Templates and create a new folder. For example, the Fields folder.
  2. Click the new folder and then click New Template.
  3. Enter a name, select the Base template: Templates/System/Forms/Fields/Field, and click Next.

    Picture 16

  4. Click the new template, and on the Builder tab, add the relevant template fields.

    For example, to add an element that adds a YouTube video to a form, you must specify the link to the YouTube video and set the width and the height of the video:

    • URL (single line text)
    • Width (integer)
    • Height (integer)

    Picture 1

    Note

    Make sure to select the Shared check box.

  5. Save the template.
  6. On the ribbon, click Options, and click Standard values.

    Make sure to select standard values from the Options tab.

    Note

    Make sure to create standard values for the field templates. The standard values items are used to populate the default field values when the field is added from the form elements pane to the canvas. If a field template does not have standard values, the element cannot be dropped on the form.

Create a new class

Now you can create the logic for the View model by creating a new class that derives from the FieldViewModel class. You can 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

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

    add the new class

  4. Override the InitItemProperties and the UpdateItemFields methods.

    Override the InitItemProperties method.

  5. Build the project and deploy the FormsDemo.dll to the Sitecore website bin folder.

Create the razor view file

The next step is to create the razor view file:

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

    Create a 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.

    Add the razor view file to the new class library project.

Create the sections for the Form elements pane

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.

Add the sections for the new 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. The next steps describe how to create the property editor that is displayed in the Form elements pane.

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 select the Form Parameters template, enter a name, for example, Video, and click OK.

    Click the new template, and on the Builder tab, add the relevant data template fields.

  4. Right-click the Video item that you just created and click Add, click New item.
  5. To add the new sections for your custom element, search for and select 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.

    Enter a name for the new item.

  7. Right-click the Details item that you just created and click Add, then click 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 and select FormTextBox Parameters, enter a name (for example, Width) and click OK.

    Search and select the parameters and click OK.

    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:

    For example use Height URL and Width.

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.

  1. Open the Width item and navigate 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, it is recommended that you select this checkbox 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. For example, width.
  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 ControlDefinitions, select Fieldname, and select Width, Height, and URL items you created earlier.

    Note

    For convenience, you can copy and adjust already configured sections 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

    Add the reference to the CSS Class.

Create the field type item

Now you can create the custom field in Sitecore and tie it all together.

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 Pathspecify the path that points to the razor view file. For example, FormsDemo/Video.
    • Model Typespecify 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.

      In the Settings section, select the Property Editor.

  4. In the Appearance section, edit the following fields:
    • Icon – select the icon that will appear in the Forms elements pane. For example, OfficeWhite/32x32/videotape.png.

      Note

      To set the icon that appears in the Content Editor, make sure the Standard fields checkbox 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 Forms element pane:

    Your new element displays in the Forms elements pane.

Send feedback about the documentation to docsite@sitecore.net.