Walkthrough: Creating a custom rating element
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:
-
Go to
http://antenna.io/demo/jquery-bar-rating/examples/
-
On the site, scroll down to the bottom of the page and click the download link.
-
Download and unpack the files.
-
Copy the following files:
-
jquery.barrating.min.js
-
jquery.barrating.min.js.map
-
-
Go to
sitecore modules/Web/ExperienceForms/scripts
, create a barrating folder and paste in the two files. -
Go to
sitecore modules/Web/ExperienceForms/css
, create a barrating folder and a themes folder and then paste in the bars-1to10.css file.NoteTo use different themes, you must add them to the css folder.
-
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
). -
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
. -
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.RequestResponsexml@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:
-
Go to
/sitecore/System/Settings/Forms/Field Types/Lists
folder, right-click the Dropdown list item and click Duplicate. -
Rename the item and the display name to Rating.
-
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.
NoteTo 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.
NoteIf 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:
-
Go to
Website/Views/FormBuilder/FieldTemplates/Samples
and create a new razor file calledRating.cshtml
. -
Add the code. For example, for the rating element:
RequestResponseshell@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)
-
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.