{Token} Replacement in Sitecore / by Derek Hunziker

Recently, I was asked how to replace tokens within a rich-text content field. This sort of functionality is common in many Content Management Systems, but sadly, it does not come out-of-the-box with Sitecore.

One popular approach is to perform the token substitution within the renderField pipeline. I think this is a pretty good solution, however, there are a number of key issues that it does not address:

  • Lack of referential integrity
    Over time, content may become littered with tokens that are both hard to locate and manage.
  • It requires specialized knowledge of the token format
    Authors must be aware of predefined tokens and specialized formatting. One could argue that this is a training issue, but I personally like to avoid burdening authors if at all possible.


This solution utilizes a custom link provider with some minor adjustments to the dynamic link functionality. If you’re not familiar with dynamic links, they are what Sitecore uses to build URLs between items. Here’s what one looks like before and after passing through the link provider.

<p>My <a href="~/link.aspx?_id=110D559FDEA542EA9C1C8A5DF7E70EF9&amp;_z=z">link</a></p>
<p>My <a href="/my-item">link</a></p>

For this solution, though, I am replacing the entire dynamic link with content from another item.

<p>My <a href="~/link.aspx?_id=110D559FDEA542EA9C1C8A5DF7E70EF9&amp;_z=z_token">link</a></p>
<p>My content from another item</p>


One of the main benefits of this approach is that Sitecore will automatically maintain references in the links database between the tokens and any items that use them. With a token item selected in the Content Editor, we can use the Navigate Links dialog to quickly navigate to any item that uses it. If we decide to delete a token, Sitecore will warn us that there are referring items that need to be sorted out first.


With some slight modifications to the insert link dialog, we can provide authors with a streamlined method of inserting tokens that does not require specialized knowledge of the available tokens or their format.

Within the Rich-Text editor, a bit of CSS will help us differentiate the token links from their internal link cousins.

a[href*=_token] {
    background: #F5F5F5 url('/~/icon/Software/16x16/component.png') no-repeat 3px center;
    opacity: .6;
    border: 1px dashed #d35400;
    border-radius: 3px;
    padding: 0 5px 0 20px;


The tokens themselves are entirely separate items, so you can create different token "types" that render according to your own business logic. For example, you can create a token type with multiple fields that are combined to form the rendered output. Or, the token can be contextually aware and vary it's output based on where it's used.

Lastly, you can nest tokens within each other to avoid content duplication. Below is an example of a Phone token nested within the main Address token.

Rendered output:


The contents of a token is only editable via the Content Editor. There may be a clever way to support Experience Editor by detecting the editing mode or perhaps using an Edit Frame, however, I have not explored this. There is also a potential of rendering invalid HTML with this approach, though, I think it can be avoided pretty easily by not going crazy with nesting or complex replacement values.


This was built on Sitecore 8 (Update-3) and was not thoroughly tested, so please exercise caution.