Sitecore Experience Accelerator (SXA) Rendering Variants: Using Custom Tokens

We have learned the basics of SXA’s Rendering Variants feature, and have seen how useful the feature is in terms of changing the appearance of our Components. This is very helpful when we want to use the same rendering to display different fields and many other properties like CSS Classes, HTML wrapper element, Data attributes, Link Attributes, etc.
There are many out of the box renderings provided by SXA that support rendering variants. In this post, we will be using the Page Content rendering to display value from a custom token.
 
 

What Are Custom Tokens in SXA’s Rendering Variant?

 
Imagine a scenario where you want to have a Rendering Variant (RV) that can show data from a third-party API call. In this situation, we cannot use the simple RV as we do not have these values coming from a Sitecore Context item. Another case would be when we want to manipulate the existing field values before displaying it. For instance, adding a query parameter to a URL link. In cases like these, we can use Custom Tokens to display complex data that cannot be displayed with normal rendering variant items.
To achieve this, we would be adding our own Token processer to the resolveVariantTokens pipeline.

Create a Class for Your Custom Token Resolution

 
1. Add XA.Foundation.Variants.Abstractions to your project using NuGet package.
2. Create a CS file for your Token Processor and add a reference to XA.Foundation.Variants.Abstractions.Pipelines.ResolveVariantTokens namespace.
3. If you are facing an error that Sitecore.XA Namespace not found, then remove the following <IncludeAssets> line from the csproj file.
 

 
4. Make your class inherit from ResolveVariantTokensProcessor as shown in the image below.
 

 
5. As you can see in the image, we will be overriding Token property to provide our custom token name.
6. Our custom Token will now display “Hello World!! This is value from SXA Token” when used in a Rendering Variant.

Register Token Processor with resolveVariantTokens Pipeline Using Config Patch

XM Cloud Roadmap Guide

XM Cloud is the future of enterprise content management offerings. The new sites, pages, and components tools offer an efficient content author experience that is not available with other CMS systems.

Get the Guide

 
1. Create a patch file to register your processor with the resolveVariantTokens pipeline as below.
 

 
2. Publish your solution and load Sitecore. Our next step is to create a Rendering Variant item with token variant field.
 

Create a Rendering Variant Definition Item

 
1. Navigate to /sitecore/content/Main/Website/Presentation/Rendering Variants/Page Content.
2. Right-click on Page Content node and add a Variant Definition item and name it Custom Test Token.
3. Now it’s time to add a Token Variant field to our Rendering Variant Definition item. Right-click on the Custom Test Token node and add Token type item named Test Token.
5. Now, in the Token field of our Test Token item, put $testtoken as this is the same value that we provided to the Token property in our ResolveTokenValue processor class.
 

Verify the Changes

 
1. Now, use the Experience Editor to drop the Page Content Rendering into your page and select the Custom Test Token Variant from the Variant Dropdown on the Toolbar.
2. You will see that the Token field now displays the string provided in the ResolveToken method of our processor class.
 

Use of ASP.NET Server Controls for Custom Token

 
1. We can use any valid ASP.NET server control for rendering data.
 

 
2. I used LiteralControl, but you can also add HtmlAnchor to the ResultControl for Links.

Changing Outer <span> for Custom Token

 
1. We can also change ResultControl to change outer <span> to any other element as Token by default use <span> tag to render. Although it is not necessary, sometimes we may have issues with HTML structure and CSS if we have any <div> inside <span>.
 

 
2. ResultControl is of type HtmlGenericControl. So, we can change it by doing the following to change the <span> to any other element.
 

 
3. This will change the <span> to <div>.
 

 
 
This concludes our post on using Custom Token in our Rendering Variants. We hope you enjoyed this series on Rendering Variants with Sitecore SXA. Leave a comment below if this was helpful and let us know what Sitecore blogs you want to see next.