A CSS-only Approach to Tooltip Icons for Help Text in Episerver

I was working through cleaning up the interface for my latest Episerver project the other day - clearly defining names, adding icon attributes to pages, adding helpful descriptions - and I saw a Tweet buzz across the wire for an article on adding icons to properties with Help Text (Description). The article is actually really good, and it got picked up by a couple colleagues of mine who implemented the solution in it. It's by Ted Nyberg and you should check it out here: https://tedgustaf.com/blog/2016/icon-for-property-help-texts-in-episerver/.

It sparked a memory for me, though, of another article I had bookmarked a short while back by Alf Nilsson, on how to expose the Help Text (Description) alongside the property name in the UI, eliminating the need to hover. Again, it's another good article and you should read it as well: https://talk.alfnilsson.se/2014/12/18/display-help-text-in-on-page-editing/.

Both of these articles touch on a pain point of mine, and various other Episerver developers, around how the Help Text (Description) is displayed for properties in the UI, and it got me thinking of another approach to address this issue, essentially combining these two ideas.

The Issue

The issue both of these articles address is how intuitive the Episerver interface is, or actually isn't, when it comes to the Help Text (Description). And while we're here, let me just address my use of "(Description)" after Help Text, so I can stop that. 

For anyone who is new to Episerver, you have probably seen the [Display(Name = "My Property")] attribute used in numerous places. If you don't use it, the UI will display the name of your property as it is defined in code. Using the DisplayAttribute, you can define a more intuitive Name for your property to display in the editing interface, and using the Description parameter, you can define Help Text for that property as well.

So, then, the issue around the Help Text is that there is no real indicator of where you get it. When I first started using the product, my initial reaction to the Description parameter was, "Okay, so what does this do?" I eventually hovered over a property name in the UI and a tooltip appeared with the Description value in it. Then my reaction was, "Oh, okay. And how is a typical user supposed to know that's there?"

That's why Ted and Alf wrote their articles: to fill a void left by the Episerver interface. 

I like different things about both approaches, though:

• Alf's approach puts the Help Text right in front of you just using CSS. However, if you use long descriptions, or have a bunch of properties in a tab, the interface can get cluttered.
  
• Ted's approach keeps the UI clean by still requiring the hover action and just adding an icon, but he takes you into the world of Dojo, albeit to a minor extent, and injects extra markup, which I avoid if possible.
  

My Solution

I decided to combine the two approaches, and I came up with a third method. Using similar CSS selectors as Alf, we can create an icon for properties to indicate a hover action without touching Dojo. One catch is that the Help Text is displayed using a "title" attribute, and it's there even when there is no value. However, with a little creative CSS, we can account for that.

The CSS

The first step is to create a CSS file. To each their own, but I named mine "helpText.css", and I saved it in the "ClientResources/shell" folder. If you don't have a ClientResources folder in your project, go ahead and create one. Also, the folder name inside can be anything you want, but make it intuitive; you'll reference it later.

Next, you need to add CSS to the file. The selectors in Alf's article are for Episerver versions lower than version 8, but a quick Inspect of the property label in the UI will give you the updated one. I added both to my CSS in case I wanted to use it in older versions, however highly unlikely that may be (upgrades are pretty simple and they like you to be current).

[pre class="brush:css"]
.Sleek .dijitTabPaneWrapper .epi-formsRow label[title]:after,   /* for Episerver < v8 */
.Sleek .dijitTabPaneWrapper .epi-form-container__section__row label[title]:after {  /* For Episerver v8+ */
     background-color: #C9C9C9;
     border-radius: 10px 10px 10px 10px;
     border: 1px solid #ACACAC;
     color: #FFFFFF;
     content: "?";  /* make this whatever you want */
     cursor: help;
     display: inline-block;
     font-size: 1em;
     font-weight: bold;
     height: 14px;
     line-height: 14px;
     margin: 0 0 0 5px;
     text-align: center;
     width: 14px;
}

[/pre]

As you can see, this creates a "?", and surrounds it with a rounded border to give it the look of an icon. You can play around with this easily enough to change it. Oh, and this icon comes complete with a Help indicator cursor, for added effect.

As I mentioned earlier, the "title" attribute exists on labels even without the value filled, so we also need to account for that, to avoid confusing the user by showing an icon where Help Text doesn't appear. The following CSS does that by targeting empty "title" attributes:

[pre class="brush:css"]
.Sleek .dijitTabPaneWrapper .epi-formsRow label[title=""]:after,
.Sleek .dijitTabPaneWrapper .epi-form-container__section__row label[title=""]:after {
     display: none;
}

[/pre]

For an added effect, one of my PMs thought a slight change in color on hover would be a nice touch, so I added it using the ":hover" pseudo-class:

[pre class="brush:css"]
.Sleek .dijitTabPaneWrapper .epi-formsRow label[title]:hover:after,
.Sleek .dijitTabPaneWrapper .epi-form-container__section__row label[title]:hover:after {
     background-color: #A9A9A9;
     border: 1px solid #9F9F9F;
}

[/pre]

All of this is pretty straight forward CSS, and I like that. 

Adding a Module

After creating the CSS file, we need to tell Episerver to load it in the Shell. This is done using the module.config file, and there may be one already in your site root. If not, you can create one. The module.config is where you can define plugins and extras for the Episerver interface (read more: http://world.episerver.com/documentation/Items/Developers-Guide/Episerver-CMS/9/User-interface/dashboard-gadgets2/configuring-shell-modules/). 

To register the CSS file you created, you need to add a new "clientResource". This is done using the following:

[pre class="brush:xml"]
<module>
  <clientResources>
    <!--you can just add this to your existing module.config-->
    <add name="epi-cms.widgets.base" path="shell/helpText.css" resourceType="Style" />
  </clientResources>
</module>

[/pre]

Note that I excluded the "ClientResources" folder from my path. That's because it's the default directory for "clientResources".

Grand Finale

That's all there is. Go refresh your Episerver Editing interface, and look for properties that have Description values.

Oh, I left my icon just spaced off the text, but you could "float:right" to create the appearance from Ted's article.