Walkthrough: Creating a custom rating element

Current version: 9.2

Sitecore Forms includes default form elements that you can drag onto 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. If you want additional settings for your element, you can decide to add a property editor.

This walkthrough describes how to implement a rating control element using an existing plugin called jQuery Bar Rating and covers:

  • Download and prepare the files

  • Create the field type item

  • Create the razor view file

Download and prepare the files

To work with the jQuery Bar rating:

  1. Go to http://antenna.io/demo/jquery-bar-rating/examples/

  2. On the site, scroll down to the bottom of the page and click the download link.

  3. Download and unpack the files.

  4. Copy the following files:

    • jquery.barrating.min.js

    • jquery.barrating.min.js.map

  5. Go to sitecore modules/Web/ExperienceForms/scripts, create a barrating folder and paste in the two files.

  6. Go to sitecore modules/Web/ExperienceForms/css, create a barrating folder and a themes folder and then paste in the bars-1to10.css file.

    Bar rating .css file shown in the tree view
    Note

    To use different themes, you must add them to the css folder.

  7. In the Content Editor, go to /sitecore/Templates/Systems/Forms/Form and, on the Content tab, in the Advanced section, in the Standard values field, select the _Standard values item (sitecore/Templates/System/Form/_Standard Values).

  8. In the content tree, with the _Standard Values item selected, on the Content tab, in the Settings section, in the Scripts field, add |barrating/jquery.barrating.min.js.

    Scripts field on the Content tab
  9. To load the form scripts and styles, they must be in an outer file layout. Therefore, add the @Html.RenderFormStyles() and @Html.RenderFormScripts() statements to your outer layout.

    RequestResponse
    @using Sitecore.Mvc
    @using Sitecore.ExperienceForms.Mvc.Html
    @using Sitecore.Mvc.Analytics.Extensions
    
    @{
     Layout = null;
    }
    
    <!DOCTYPE html>
    <html lang="en" xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>@Html.Sitecore().Field("title", new { DisableWebEdit = true })</title>
        @Html.Sitecore().VisitorIdentification()
        @Html.RenderFormStyles()
        @Html.RenderFormScripts()
    </head>
    <body>
        @RenderBody()
    </body>
    </html>

Create the field type item

A Sitecore item defines each form element. For a custom element to appear in the Form elements pane, you must create a new item. You can create a new item or duplicate an existing item.

Because the jQuery bar rating plugin uses a select field, it is convenient to use the list element as the basis.

To create the field type item by duplicating an existing item:

  1. Go to /sitecore/System/Settings/Forms/Field Types/Lists folder, right-click the Dropdown list item and click Duplicate.

  2. Rename the item and the display name to Rating.

  3. In the Appearance section, edit the following fields:

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

      Note

      To set the icon that appears in the Content Editor, make sure the Standard fields checkbox is selected.

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

    • Sortorder – to make the rating element appear last in the List section of the Form elements pane, set the sort order to 1200.

      Note

      If you do not see a field as expected, on the ribbon, on the View tab, select the Standard Fields check box. This shows all the fields from the Standard template on every item that you open.

Create the razor view file

The next step is to create the razor view file:

  1. Go to Website/Views/FormBuilder/FieldTemplates/Samples and create a new razor file called Rating.cshtml.

  2. Add the code. For example, for the rating element:

    RequestResponse
    @using Sitecore.ExperienceForms.Mvc.Html
    @model Sitecore.ExperienceForms.Mvc.Models.Fields.DropDownListViewModel
    
    !-- reference the bar rating css theme file --
    <link rel="stylesheet" href="/sitecore modules/Web/ExperienceForms/css/barrating/themes/bars-1to10.css"/>
    
    !-- initialize the bar rating plugin -- 
    <script type="text/javascript">
    	$(function()
    	{
    		var $el = $("#@Html.IdFor(m => Model.Value)");
    		if (typeof $el.barrating === "function") 
    		{$el.barrating({
    		theme: "bars-1to10",
    		showValues: false,
    		showSelectedRating: true,
    		reverse: false,
    		deselectable: @((Model.ShowEmptyItem && !Model.Required).ToString().ToLowerInvariant()),
    		allowEmpty: @Model.ShowEmptyItem.ToString().ToLowerInvariant(),
    		hoverState: true
    		});
    	}
    	});
    </script>
    
    !-- the element definition for the rating --
    <label for="@Html.IdFor(m => Model.Value)" class="@Model.LabelCssClass">@Html.DisplayTextFor(t => Model.Title)</label>
    <select id="@Html.IdFor(m => Model.Value)" name="@Html.NameFor(m => Model.Value)" data-sc-tracking="@Model.IsTrackingEnabled" data-sc-field-name="@Model.Name"> @Html.GenerateUnobtrusiveValidationAttributes(m => m.Value)
        @if (Model.ShowEmptyItem)
        {
            <option label=""></option>
        }@foreach (var item in Model.Items)
        {
            <option value="@item.Value" selected="@item.Selected">@item.Text</option>
        }
    </select>
    @Html.ValidationMessageFor(m => Model.Value)
  3. To point the new rating field to the razor view file, go to /sitecore/System/Settings/Forms/Field Types/Lists/Rating and in the View Path field, add the location of the razor view file, in this example, FieldTemplates/Samples/Rating.

    The Rating element is now available in the Form elements pane.

    Lists in the Form elements pane

Do you have some feedback for us?

If you have suggestions for improving this article,