Walkthrough: Creating a custom rating element

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:

This walkthrough describes how to:

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.

4. Copy the following files: jquery.barrating.min.js and 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:

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

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"

title@Html.Sitecore().Field("title", new {
DisableWebEdit = true })/title

@Html.Sitecore().VisitorIdentification()

@Html.RenderFormStyles()

@Html.RenderFormScripts()

body

@RenderBody()

/body

/html


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.

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 --

!-- 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.