Embed Renderings (Maps, Media, etc.) in Sitecore Rich Text Editor Fields

Introduction

This post describes one technique that you can use the Sitecore Web Content Management System to embed rendering in Rich Text Editor (RTE) fields. CMS users can position videos, maps, Flash resources, and other multimedia and dynamic items using the WYSIWYG editor. A snippet in the RTE allows the CMS user to insert markup representing a rendering control, and the renderField pipeline processes controls in RTE field values.

Embedding renderings in the RTE fields violates one of the primary principles of Web content management, which is to separate content from presentation. Neither Sitecore nor I explicitly support this enhancement, which could have unpredictable effects. I published this blog post without any significant testing, and only with XSL and Web controls (not sublayouts, especially considering code-behind). See the Additional Considerations at the end of this post before choosing to implement this technique.

Someone asked about this after my presentation at dreamcore 2010.

Check the HtmlEditor.SupportWebControls Setting

The first step is to ensure that the value of the HtmlEditor.SupportWebControls setting in the web.config file is true, which is the default for this setting.

Create a Media (or Any Other) Rendering

Create a rendering that outputs the required markup, such as the code to embed YouTube video or any other type of media. This rendering should typically retrieve all of the data it needs from its data source, such as the media file to render. I used the YouTube Integration Shared Source module, which most importantly gives me the URL of a flash resource in a field named Url. The base WebControl class exposes Width and Height properties.

Here is my prototype Web control:

namespace Sitecore.Sharedsource.Web.UI
{
  using System;
  using System.Web.UI;

  public class YouTube : Sitecore.Web.UI.WebControl
  {
    protected override void DoRender(HtmlTextWriter output)
    {
      Sitecore.Data.Items.Item youTube = this.GetItem();

      if (youTube == null
        || youTube.TemplateName.ToLower() != "youtube video"
        || String.IsNullOrEmpty(youTube["url"]))
      {
        return;
      }

      string markupTemplate = @"<object width=""{0}"" height=""{1}"">"
                              + @"<param name=""movie"" value=""{2}""></param>"
                              + @"<param name=""allowFullScreen"" value=""true""></param>"
                              + @"<param name=""allowscriptaccess"" value=""always""></param>"
                              + @"<embed src=""{2}"" type=""application/x-shockwave-flash"""
                              + @" allowscriptaccess=""always"" allowfullscreen=""true"""
                              + @" width=""{0}"" height=""{1}""></embed></object>";
      string markup = String.Format(
        markupTemplate,
        Sitecore.StringUtil.GetString(this.Width, "480"),
        Sitecore.StringUtil.GetString(this.Height, "385"),
        youTube["url"]);
      output.WriteLine(markup);
    }
  }
}

If needed, add the appropriate tag prefix to the web.config file. For example, I added the following within the /configuration/system.web/pages/controls element in my web.config file:

<add tagPrefix="ss" namespace="Sitecore.Sharedsource.Web.UI" assembly="assembly"/>

You can read more about ASP.NET tag prefixes in the Presentation Component Cookbook on the Sitecore Developer Network.

Register the Rendering Snippet

You can create a snippet to allow CMS users to insert the rendering in RTE fields. You can read more about snippets in the Client Configuration Cookbook on the Sitecore Developer Network.

To enable snippet in the default RTE profile:

1. In the Core database, copy the /Sitecore/System/Settings/Html Editor Profiles/Rich Text Full/Toolbar 1/Insert Snippet item to /Sitecore/System/Settings/Html Editor Profiles/Rich Text Default/Toolbar 1. To control who can insert snippets, you can apply access rights to the Insert Snippet command in the RTE to control who can insert snippets.
2. Within the /Sitecore/System/Settings/Html Editor Profiles/Rich Text Default item, insert an item named Snippets using the Common/Folder data template.
3. In the new /Sitecore/System/Settings/Html Editor Profiles/Rich Text Default/Snippets item, assign insert options to allow the user to create items using the System/Html Editor Profiles/Html Editor Snippet data template.

To create a snippet:

1. Use the Developer Center to drag the rendering onto a scratch sublayout or layout.
2. After adding, updating, or removing attributes as required, copy the control markup to the Windows clipboard.
3. In the Core database, under the /Sitecore/System/Settings/Html Editor Profiles/Rich Text Default/Snippets item, insert a snippet definition item named after the rendering (for example, YouTube) using the System/Html Editor Profiles/Html Editor Snippet data template. To control who can insert the individual snippet, you can apply access rights to the snippet definition item.
4. In the snippet definition item, set the Header field in the Data section to the text that the user should click to insert the snippet, such as the name of the rendering (YouTube).
5. In the snippet definition item, set the value of the Value field in the Data section of the snippet definition item to the markup previously copied from the Developer Center (<ss:youtube runat="server" />).

The appropriate Value to embed my YouTube rendering is as follows:

<ss:youtube runat="server" />

The following screen shot of the RTE shows what it looks like to use the snippet (the arrow to the right of the second toolbar command from the right):

The following screen shot of the RTE shows a rendering in the RTE with no parameters.

The renderField Pipeline

Sitecore uses the renderField pipeline to transform field values to runtime markup. You can add a processor to the renderField pipeline to transform renderings embedded in RTE fields to markup. Here is my processor prototype:

namespace Sitecore.Sharedsource.Pipelines.RenderField
{
  using System;

  public class GetRTEFieldValue
  {
    public void Process(Sitecore.Pipelines.RenderField.RenderFieldArgs args)
    {
      Sitecore.Diagnostics.Assert.ArgumentNotNull(args, "args");
      Sitecore.Diagnostics.Assert.ArgumentNotNull(args.FieldTypeKey, "args.FieldTypeKey");

      if (args.FieldTypeKey != "rich text"
        || String.IsNullOrEmpty(args.FieldValue)
        || Sitecore.Context.PageMode.IsPageEditorEditing
        || !Sitecore.Configuration.Settings.HtmlEditor.SupportWebControls)
      {
        return;
      }

      this.TransformWebControls(args);
    }

    protected void TransformWebControls(Sitecore.Pipelines.RenderField.RenderFieldArgs args)
    {
      System.Web.UI.Page page = new System.Web.UI.Page();
      page.AppRelativeVirtualPath = "/";
      System.Web.UI.Control control = page.ParseControl(args.Result.FirstPart);
      args.Result.FirstPart = Sitecore.Web.HtmlUtil.RenderControl(control);
    }
  }
}

I added this processor to the renderField pipeline definition in web.config immediately after the default GetDocxFieldValue processor using 6.2.0 100104:

<renderField>
  <processor type="Sitecore.Pipelines.RenderField.SetParameters, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.GetFieldValue, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.ExpandLinks, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.GetImageFieldValue, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.GetLinkFieldValue, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.GetInternalLinkFieldValue, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.GetMemoFieldValue, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.GetDateFieldValue, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.GetDocxFieldValue, Sitecore.Kernel"/>

  <processor type="Sitecore.Sharedsource.Pipelines.RenderField.GetRTEFieldValue, assembly"/>

  <processor type="Sitecore.Pipelines.RenderField.AddBeforeAndAfterValues, Sitecore.Kernel"/>
  <processor type="Sitecore.Pipelines.RenderField.RenderWebEditing, Sitecore.Kernel"/>
</renderField>

Rendering Parameters

The most important parameter for the media rendering is its data source. The CMS user can double-click on a rendering in the RTE field to access rendering properties:

To select a data source for the rendering, the user clicks Browse. The data source item should contain field values to meet the requirements of the media rendering.

By default, the user interface control that allows the user to select a data source is rooted at the /Sitecore/Content item. If your users need to select an item from another branch, such as the media library, then you will have to override this UI. To do so:

1. Copy the file /sitecore/shell/applications/item browser/item browser.xml to create /sitecore/shell/override/item browser.xml.
2. In /sitecore/shell/override/item browser.xml, set the Root attribute to the /control/ItemBrowser/FormDialog/DataContext element with value “/sitecore”:

<DataContext ID="DataContext" Root="/sitecore" />

If you know that the user must select a media item as the data source, then you could set Root to /sitecore/media library, but you may subsequently find that other applications that use this user interface expect the default. So /sitecore might be the most appropriate value for the Root attribute.

In rendering properties, the user can click the Attributes tab to specify rendering parameters. For example, the prototype I wrote supports Height and Width parameters.

Here’s a screen shot of an RTE field after selecting a data source and entering height and width parameters for two instances of the YouTube rendering:

Here is the item containing that field rendered within the Page Editor:

Additional Considerations

Be careful not to embed a rendering that invokes the renderField pipeline for RTE fields or you could end up in an infinite loop.

Renderings embedded in RTE fields do not experience the full ASP.NET component lifecycle. Most solutions invoke the renderField pipeline at the rendering stage in the ASP.NET page lifecycle. Renderings that you embed in RTE fields should only implement functionality within the rendering stage of the ASP.NET page lifecycle.

You might need to generate different markup for different devices.

Consider whether you can or should cache the output of renderings that output the values of RTE fields that contain renderings, and/or whether you can or should cache the output of each of those embedded renderings.

You shouldn’t process renderings in RTE fields while the user is in the Page Editor. To edit RTE fields containing renderings in the Page Editor, CMS users should click the Edit Text command for the field. You won’t see media controls when inline editing in the Page Editor (only when navigating).

If you try to use my example, be sure to publish the YouTube templates and items.

This solution does not support parameters templates – the user must know the names of properties such as Height and Width.

I thought about writing something like a publishItem processor to process Web controls in RTE values and store the result inline after publishing, but I am not sure of the best way to prevent Sitecore from assigning a new revision ID, which would confuse smart publishing. A replacer would probably be the right way. This should reduce publishing efficiency but increase delivery efficiency.

Update: How a Rendering Can Determine Its Order

Someone asked me how the YouTube video could determine its order in the RTE field value. This solution in the DoRender() method of the YouTube Web control seemed to work:

protected override void DoRender(HtmlTextWriter output)
{
  Control parent = this.Parent;
  int position = -1;

  if (parent != null)
  {
    int counter = 0;

    foreach(Control control in parent.Controls)
    {
      if (control is LiteralControl)
      {
        continue;
      }

      counter++;

      if (this == control)
      {
        position = counter;
        break;
      }
    }
  }

…

The key is to ignore instances of LiteralControl, which represent each HTML or text element in the field value.

Also, I didn’t test this, but to enable a sublayout instead of an Web control, I think the snippet markup would be:

<sc:sublayout runat=”server” path=”/layouts/file.ascx” />

And similar for an XSL rendering:

<sc:xslfile runat=”server” path=”/xsl/file.xslt” />