Creating Custom Tokens With Token Manager

So you want to inject something custom into a rich text editor, the Token Manager is the right tool for the job.  It was designed with the thought that anything should be inject-able.  So it is as open ended as possible.

There are three main steps to create your own token, they are as follows

Create a template for your token

Your token needs a template.  When you create your token template, you need to inherit from the Token Base template found here: /sitecore/templates/System/Token Manager/System/Token Base

There are two types of data that a token can consume

  1. Sitecore template data
    1. these are fields set up in the tokens sitecore template and are the same for every instance used of a particular token that uses the same datasource item.
  2. Data stored with the token itself
    1. these are fields stored in the markup that the Token Manager will use when expanding the token.  These can differ per usage of a particular token item, even if they are using the datasource item.

So you need to decide what fits your use cases best.  If it’s something that will be set up once and used in several places, using template fields would be the most sensible choice.  Likewise if it’s information that will likely be different in every usage of the token and having a datasource item for each use case would inhibit the effective management of the tokens, you’ll likely want to use data stored on the token itself.

Of course you’re not pidgin holed into one way or the other, you can just as easily utilize a hybrid approach if some data is more constant and other data is more dynamic.

Create your source code file

Create a class and inherit SitecoreBasedToken found in the TokenManager assembly.

	public abstract class SitecoreBasedToken : IToken
	{
		protected string TokenName;
		protected ID BackingId;
		public SitecoreBasedToken(string name, ID backingId)
		{
			BackingId = backingId;
			TokenName = name;
		}

		public string Token => TokenName;
		public abstract string Value(NameValueCollection extraData);
		public abstract IEnumerable<ITokenData> ExtraData();
		public virtual string TokenIdentifierText(NameValueCollection extraData)
		{
			return "{0} > {1}".FormatWith(extraData["Category"], extraData["Token"]);
		}

		public virtual string TokenIdentifierStyle(NameValueCollection extraData)
		{
			return TokenKeeper.CurrentKeeper.TokenCss;
		}

		public ID GetBackingItemId()
		{
			return BackingId;
		}
	}

You will need to implement the Value method and the ExtraData method. Value is the markup that’s returned by the token.  ExtraData is how you can apply data specific to the token.

Imagine the example of an image with a caption under it

For example here I’m setting up a token with the extra data to be stored on the token of an ID, string, and two integers.

		public override IEnumerable<ITokenData> ExtraData()
		{
			yield return new IdTokenData("Image item", "image", true, "{C4A10B5B-6410-4C1E-806D-8F8CCFACFD28}");
			yield return new StringTokenData("Caption", "caption", "Enter the text that will be displayed as the caption", true);
			yield return new IntegerTokenData("Image Width", "width", false);
			yield return new IntegerTokenData("Image Height", "height", false);
		}

Which gets rendered like this, after a content author selects the particular token datasource item (created from the template in the first step)

captionimageextradata

For template fields, you should simply store the backing id in your token, then during rendering the value, take the context database and get the fields you need from your datasource item.

Additionally you can override the default way the token is displayed in the content editor by overriding the method TokenIdentifierText (which can contain markup) and TokenIdentifierStyle which is what styles are applied to the root token node.  Using these two methods you can achieve something like this.

imagecaptiontokeneditmode.png

Register your token

This step is simple, we need to inform Token Manager where to find the first two steps.  This is done in the config patch (Tokens.config by default).

configPatch