Highlight Sitecore Components with Rendering Chrome

a.k.a “Rendering Wrappers”

tl;dr; MVC HTML Helper and custom CSS styling to add chrome highlighting around renderings in Experience Editor mode.

I presented this module at the Sitecore User Group London on 12th January 2017. You can download the slides for that lightning talk here.

A few months ago I presented Session 4 of the Unofficial Sitecore Training sessions that Akshay “Be My Friend” Sura and Mike “Blog All The Things” Reynolds have been hosting. If you’re new to Sitecore or need a refresher course then I suggest you head on over and watch the videos on the series, there’s some really useful info in there from some seasoned Sitecore developers and gurus.

Anyhow, I decided presenting stuff and virtually pointing things out is hard so I added a fairly early version of some code that we had been using and experimenting with on our current project. This would make it easier to see components in Experience Editor mode and therefore easier for the audience to follow along with what I was doing. Some people noticed this at least πŸ™‚

It seems there really is more than one way to skin a cat, a number of people have blogged about this it seems (see additional links at the end). I’ve tried the method from Jason Wilkerson before on this project, but it didn’t work as expected for us. The problem with these other methods were that they inserted extra div elements into the DOM to allow them to be styled. There’s nothing wrong with doing this – Sitecore itself adds a whole bunch of markup in Experience Editor mode – the problem for us was that this project had already dealt with that “issue” and introducing additional levels of DOM elements would mean updating all our styling to cater for these.

Wrappers vs Mappers Attribute driven styling

So we came up with a different solution using CSS that would have no (or very little) effect on the markup. It’s similar to what we use for the Environment Styler module: using the CSS Content property except instead of specifying the text to display in the CSS content property, we use the attr() function which will insert the value of the specified attribute.

You can view a simple PoC of this in action in these CodePen examples. These demos are using Zurb Foundation 5, since that what our project is using.

The idea is simple, add some data attributes to the HTML markup and the use as a CSS selector and also to provide the text to display:

<div class="row" data-container-title="Four Column Container">
    ...
</div>

Add them into your markup as required and as you see fit. For example, we only add them to placeholder and components in the main content part of the site, leaving them off header/footer components.

MVC Helpers

The disadvantage of using this method over the wrappers method is you have to add the attributes. Not particularly a big deal to create a custom MVC helper, but you will need to add this to your markup to tell it where to output.

private static IHtmlString GetChromeAttribute(this SitecoreHelper helper, string title, string attribute)
{
    /* Earlier version of Sitecore? Use: Sitecore.Context.PageMode.IsPageEditorEditing */
    if (!Sitecore.Context.PageMode.IsExperienceEditorEditing)
        return null;

    if (string.IsNullOrWhiteSpace(title))
        title = helper.CurrentRendering.RenderingItem.DisplayName;

    if (Settings.GetBoolSetting(DisplayExtendedInfo, false))
        title += $" ({helper.CurrentRendering.Renderer})";

    string htmlString = $"data-{attribute}-title=\"{title}\"" + WrapperTitle(title);
    return new HtmlString(htmlString);
}

We extend the SitecoreHelper since this gives us access to details about the current rendering. We also have some overloaded methods to allow us to specify the text we want to display instead. You can also display extended details about the rendering, which will output the path of the View file or information about the Controller. A config setting exists to enable this, it was mainly added as a developer aid to figure out which file was being used for a particular component and proved to be very useful during a recent code refactor. As such did not make sense to enable this in Production and overload your content editors with too much information.

You can find all the code for the helper on Github.

CSS Styling

To style the components, we use CSS Attribute selectors. This gives us a simple border around the component we add the attribute to. In order to display the details of the component, we use the content property in combination with the attr() function. We also make use of nth-child even selector to style alternating containers with a different shade/colour.

/* -- default -- */
html.chromeRenderingHighlight *[data-container-title],
html.chromeRenderingHighlight *[data-widget-title] {
  border: 3px solid rgba(169, 169, 169, 0.7);
  padding-top: 1.1rem;
  position: relative;
  margin-top: 1px auto;
}

html.chromeRenderingHighlight *[data-container-title]::before,
html.chromeRenderingHighlight *[data-widget-title]::before {
  color: #fff;
  content: attr(data-container-title);
  background-color: rgba(169, 169, 169, 0.7);
  display: block;
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 1.1rem;
  font-size: 0.8rem;
  ...
}

If you’re looking at that wildcard and attribute selector and thinking “Jeez, that’s not best practice, that’s going to cause performance issues” then think again. Times have changed, computers have changed and browsers have changed. See links below for more reading. tl;dr; Reduce the amount of bloat you have in your CSS files and remove unused styles.

You can find all the code for the styling on Github. Your mileage will vary, update it to match the framework you are using and adjust to fit your requirements. As mentioned, we are using Aurb Foundation 5, I carried out some testing on Bootstrao (which Sitecore Habitat uses) and added an extra CSS selector to handle alternating column colouring. You may have to make changes for your own site.

Enable display of styling from the Ribbon

The problem with always adding this styling into the Experience Editor is that it spoils the WYSIWYG editor. However, since the styling is CSS driven, all we really need to do is control the addition of the top level CSS class – the chromeRenderingHighlight class on the html element.

To do so we add a custom checkbox into the View ribbon and hook up the Javascript to handle this.

Highlight Rendering Chrom - Ribbon Checkbox

The Sitecore Item for this checkbox is added to the core database, which you can either find in the TDS project or the serialisation folders if you are using 🌈 🐘

You can find all the code for the JavaScript on Github.

It’s worth noting the following line which is used to inject in the CSS file. You could forgo this and instead add the styles into your own CSS file for the site.

ExperienceEditor.Common.registerDocumentStyles(["/sitecore modules/RenderingChrome/chrome-styles.css"], window.parent.document);

Also, different versions of Sitecore reference the RequireJS dependencies differently at the top of the js file.

Usage

Add a reference to the Helper namespace in the web.config file in your Views folder (otherwise you’ll have to add a using statement into your views).

<pages pageBaseType="System.Web.Mvc.WebViewPage">
  <namespaces>
    ...
    <add namespace="ForwardSlash.SC.RenderingChrome.HtmlHelpers" />
  </namespaces>
</pages>

Call the helper on the components you want to Rendering Chrome to be added to, for example:

<div class="whatever-as-normal" @Html.Sitecore.ContainerChrome()>
   ... 
</div>

Two helpers are provided:

  • @Html.Sitecore().ContainerChrome() – Adds a grey border and uses component name as specified in Sitecore Item. Suggested usage around Placeholders.
  • @Html.Sitecore().WidgetChrome() – Adds a coloured border. Suggested usage around renderings/components.

You can call the overloaded methods and pass in the text to display instead if you need:

  • @Html.Sitecore().ContainerChrome("This is the custom container title")
  • @Html.Sitecore().WidgetChrome("This is the custom widget title")

Set “ in environments you do not wish to show extended information for components (the View/Controller details) i.e. on Production environment.

Download

You can take a look at the code and find installable Sitecore packages in this Github repo:
https://github.com/jammykam/Rendering-Chrome-for-Sitecore-Components

I presented this module at the Sitecore User Group London on 12th January 2017. You can download the slides for that lightning talk here.

London User Group Presentation – January 2017

Screenshots

Regular Experience Editor Mode

Highlight View Rendering Chrome

Highlight Controller Rendering Chrome

Highlight Rendering Chrome for Habitat

Highlight Rendering Chrome for Habitat - 2

Additional Links

Advertisements

One comment

  1. Alenka · 14 Days Ago

    Hmm, this looks very interesting and potentially incredibly helpful for page designers.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s