Implement tooltips for fields in Sitecore Forms

Posted 26 Mar 2024 by Marek Musielak

Improving your website's user experience often means giving clear guidance, especially for forms. In this blog post, I'll guide you through the process of integrating tooltips into Sitecore Forms. Tooltips are those small bubbles that give users helpful hints as they fill out forms. Adding tooltips brings big benefits: it makes forms easier to use and helps users understand them better, making your Sitecore-powered website more engaging.

The first task we need to address is making modifications to the core database. We'll begin by adding an item called Tooltip item:

/sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common

Then copy the Label item into that new folder, which is located in the Common/Details folder. Rename it to Tooltip text and update the following fields:

• FormLabel: Tooltip text
• BindingConfiguration: tooltipText

Now duplicate DetailsExpander item:

/sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Common/Sections/DetailsExpander

Call it TooltipExpander and update the HeaderText field:

The last thing we need to do in core database is duplicating item:

/sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Settings/SingleLineText/Details

call it Tooltip and in the ConfigurationItem and ControlDefinitions fields select 2 items you've created earlier:

After you completed all the steps above, if you open Sitecore Form Designer and select any Single-Line Text field, you will see a new section called Tooltip and if you expand it, you will see Tooltip text field inside the section:

Still, you will not be able to save the value of the field yet. We need to modify master database items first. Start with selecting

/sitecore/templates/System/Forms/Fields/Field

item and adding extra section called Tooltip with Tooltip text field inside it:

Now let's write some code. We need a class for the field model, that will inherit from StringInputViewModel class (or from StringInputViewWithBindingsTokenModel if you use Sitecore Forms Extensions) and contains TooltipText property:

using Sitecore;
using Sitecore.Data.Items;
using Sitecore.ExperienceForms.Mvc.Models.Fields;
using System.Web;

namespace MyAssembly.MyNamespace.Fields
{
    public class StringInputViewModelWithTooltip : StringInputViewModel, IWithTooltip
    {
        public string TooltipText { get; set; }

        protected override void InitItemProperties(Item item)
        {
            base.InitItemProperties(item);
            TooltipText = StringUtil.GetString(item.Fields["Tooltip Text"]);
        }

        protected override void UpdateItemFields(Item item)
        {
            base.UpdateItemFields(item);
            item.Fields["Tooltip Text"]?.SetValue(TooltipText, false);
        }
    }

    public interface IWithTooltip
    {
        string TooltipText { get; set; }
    }

    public static class WithTooltipExtensions
    {
        public static HtmlString Tooltip(this IWithTooltip fieldWithTooltip)
        {
            var tooltip = fieldWithTooltip.TooltipText;

            if (!string.IsNullOrEmpty(tooltip))
            {
                tooltip = $"<span title=\"{HttpUtility.HtmlEncode(tooltip)}\">&#x24D8;</span>";
            }

            return new HtmlString(tooltip);
        }
    }
}

We also need to modify cshtml file of the field, so let's create a file with the following code:

Views\FormBuilder\FieldTemplates\SingleLineText.cshtml

@using System.Web.Mvc.Html
@using MyAssembly.MyNamespace.Fields
@using Sitecore.ExperienceForms.Mvc.Html
@model MyAssembly.MyNamespace.Fields.StringInputViewModelWithTooltip

<label for="@Html.IdFor(m => Model.Value)" class="@Model.LabelCssClassSettings.CssClass">@Html.DisplayTextFor(t => Model.Title) @Model.Tooltip()</label>
<input id="@Html.IdFor(m => Model.Value)" name="@Html.NameFor(m => Model.Value)" class="@Model.CssClassSettings.CssClass" type="text" value="@Model.Value" @if (Model.MaxLength > 0)
                                                                                                                                                          {<text> maxlength="@Model.MaxLength"</text>} placeholder="@Model.PlaceholderText" data-sc-tracking="@Model.IsTrackingEnabled" data-sc-field-name="@Model.Name" data-sc-field-key="@Model.ConditionSettings.FieldKey" @Html.GenerateUnobtrusiveValidationAttributes(m => m.Value)/>
@Html.ValidationMessageFor(m => Model.Value)

The last thing we need to do is changing the value of the Model Type field on

/sitecore/system/Settings/Forms/Field Types/Basic/Single-Line Text

item to the new class we've created earlier:

After we complete the last step, we can go back to Sitecore Forms Editor, set tooltip for any of the Single-Line Text fields and check the form rendered on the page for the new tooltip text:

If you need to add tooltip text to any other type of the field:

• add tooltip section under chosen field type item in core database

  /sitecore/client/Applications/FormsBuilder/Components/Layouts/PropertyGridForm/PageSettings/Settings/

• create view model class for the field inheriting from IWithTooltip,
• use the new view model class on the field type definition item under /sitecore/system/Settings/Forms/Field Types item,
• and update cshtml file of the field to include @Model.Tooltip().

You can find the code of the tooltip for Sitecore Forms fields on my Github: Sitecore Forms - field tooltips.