In this blog post I'll explain the general concepts on what tokens are and how you can create your own custom tokens in Sitecore.
So, what are those tokens all about?
Working with Sitecore you might have noticed that in some places there are field values that are set to $name, typically in __Standard Values. Moreover, you may also have noticed that when you are creating an item that has such a field value, the $name value magically turns into the name of the item.
The magic comes from the $name value, which is called a token in Sitecore, and is a way to have a field value dynamically resolved during item creation.
Similar to the $name token, Sitecore comes with a list of built-in tokens that can be used for dynamically resolving a range of different things, including:
$name: The name of the item$id: The id of the item$parentid: The id of the item's parent$parentname: The name of the item's parent$date: The current date$time: The current time$now: The current date and time
Using tokens to dynamically resolve field values during item creation has a lot of benefits. For example, if you want to create an item and have a certain field to always be set to the current date, this can be achieved by using the $date token.
That's all good, but Sitecore is missing the token I need
If you are like me, you look at the standard tokens provided by Sitecore and starts to think "Sure, that's nice, but there is not the specific token I need". No worries, because you can create your own custom tokens, and the best part is it is easy as pie.
When it comes down to creating your own custom tokens, there are basically two options to choose from:
- Extend the
MasterVariablesReplacerclass - Extend the
ExpandInitialFieldValueProcessorclass
The first option involves extending and overriding default functionality of the class, that provides the replacement mechanism for all the standard Sitecore tokens. This approach is explained in John West's blogpost on how to add custom standard value tokens to Sitecore. It should be noted, that extending from the MasterVariablesReplacer class requires some method overriding. Be aware, that since the class is not really meant for extending in the first place you'll have to duplicate a great amount of the private members into your own custom implementation.
The other option is extending from the ExpandInitialFieldValueProcessor class, which is my preferred way to create replacement mechanisms for custom tokens in Sitecore. Using the ExpandInitialFieldValueProcessor is really easy, as it only requires you to extend from the base class and implement the void Process(ExpandInitialFieldValueArgs args) method:
In the Process(...) method, you are able to implement your own custom logic for handling your custom token, where you have a handle to the item and it's fields. Once the token replacer is implemented, all that is left to do is to patch in the processor into the Sitecore pipeline config section for the expandInitialFieldValue pipeline:
A couple of examples
I've provided a couple of examples to show you some of the custom tokens I've recently been using, which you can use as a baseline for creating your own custom token implementations.
The first example is really neat, if you need to somehow calculate the next sort-order number of an item. Recently I needed to be able to do this, since the sort-order in Sitecore has a couple of pitfalls (like when inserting new items the sort-order is not explicitly set). On the solution I was working on, I had to be sure that newly created items always had a sort-order, and that it was the last element in the list of sorted items. In order to do so, I decided to implement my own custom token $nextsortorder which sets the sort-order of the item once created, to be the highest possible sort-order:
The next example I want to highlight can be really useful, if you want to perform queries against specific fields on either ancestors or descendants of a given item. I stumpled upon this gem while doing my initial research on Sitecore custom tokens, and as a result the following code is my refurbished version of the QueryToken implementation found in Reto Hugi's SitecoreExtension-TokenSet project:
What the QueryTokenReplacer allows you to do, is specifying a query, using standard Sitecore queries. If an item is found, it grabs a value from one of the item's fields and replaces the token with that value. The way such queries are specified follows this pattern:
$query(<SitecoreQuery>|<FieldName>)
where the <SitecoreQuery> parameter is replaced by the given query you want to use to query a given item, and the <FieldName> is replaced with the name of the field you want to extract from the item found by the query.
Now, where can this sort of token replacer give you benefit in your Sitecore solutions? In my case, I had a module (consisting of a rendering and a data source) that was created as part of a branch. When the different items was created from the branch, I needed to generate a dynamic query string for a link I had on the data source item, whereas I needed to grab the id of the parent's parent:
Trying to do this using the standard tokens in Sitecore will not work, since you only have the option to use the $parentid token, which would give me the id of the page content folder. Using the $query token I simply added the following to my link:
querystring="id=$query(./ancestor-or-self::*[@@templatename='TemplateName_Of_The_Item_I_Need_ID_From']|Id)"
Once the items were created from the branch, the token was next resolved, and the id was fetched from the item that I needed the id from.
On that note, this concludes our journey on Sitecore (custom) tokens. If you have any comments or questions related to this blogpost, please drop me a note in the comments section down below.