Walkthrough: Creating a custom rating element

Last updated Tuesday, October 31, 2017 in Sitecore Experience Platform for Developer
Keywords: Configuration, Forms

Sitecore Forms includes default form elements that you can drag and drop 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:

Example view of the bar rating.

This walkthrough describes how to:

Download and prepare the source files

This walkthrough uses an example of a rating element. To execute the steps on your local installation, you must download and prepare the source files.

To work with the jQuery Bar rating:

  1. Navigate 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. Navigate to sitecore modules/Web/ExperienceForms/scripts/barrating and paste the files.
  6. This walkthrough only uses the bars-1to10.css theme. To use this theme, in the barrating folder, create a themes folder and paste the bars-1to10.css file:

    Paste the theme.

    Note

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

  7. In the Content Editor, navigate to /sitecore/templates/Systems/Forms/Form and select the _Standard values item.
  8. In the Settings section, in the Scripts field, add |barrating/jquery.barrating.min.js

    In the scripts field add the barrating javascript file name.

  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.

    @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. Navigate 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. Navigate 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:
    @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, navigate 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.

    The form element is now available

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