In the world of Sitecore Experience Accelerator (SXA), flexibility and reusability are the names of the game. When you are building multi-site or multi-tenant environments, hardcoding item paths in your datasource locations is a recipe for maintenance headaches. This is where Sitecore SXA query tokens become your most powerful ally.

By using tokens like $site or $home, you tell Sitecore to resolve paths dynamically based on the context of the current site. This allows you to share renderings across different sites while ensuring they always point to the correct local data. In this guide, you will learn about the standard tokens available in SXA, how to use search-specific tokens, and the steps to implement your own custom tokens to extend the platform's capabilities.

Understanding Standard SXA Resolve Tokens

When you look at the datasource location of an out-of-the-box SXA rendering, you will often see strings starting with query:. These are processed by the resolveTokens pipeline. Using these tokens ensures that your components are portable across different site structures.

Here is a comprehensive list of the standard tokens available in most modern SXA versions:

  • $site: Resolves to the path of the current site item.
  • $tenant: Resolves to the path of the current tenant item.
  • $home: Points to the start item (usually the Home item) of the current site.
  • $templates: Resolves to the path of the current site's local templates (typically /sitecore/templates/Project/Tenant).
  • $siteMedia: Resolves to the virtual media folder located under the site.
  • $theme: Points to the currently used theme for the site.
  • $compatibleThemes: Resolves the path to all themes available to the site.
  • $pageDesigns: Points to the root of the Page Designs folder.
  • $partialDesigns: Points to the root of the Partial Designs folder.
  • $currenttemplate: Resolves to the name of the current item's template.
  • $linkableHomes: Returns paths to home items from linkable sites, which is essential for cross-site linking scenarios.
  • $sharedSites: For multi-root fields, this resolves the shared site for the current tenant.
  • $xaRichTextProfile: Returns the value of the XA.Foundation.Editing.DefaultRichTextProfile setting.

Version-Specific Tokens (Sitecore 10.2+)

If you are working on Sitecore 10.2 or later, several new tokens were introduced to provide even more granular control over the context:

  • $sitelang: Resolves the context site language.
  • $lang: Resolves the current context language.
  • $vf: Resolves the virtual folder for the context site.

Utilizing Search Query Tokens

Beyond standard datasource resolution, SXA provides a specific set of tokens for search-related functionality. These are handled by the resolveSearchQueryTokens pipeline, defined in the Sitecore.XA.Foundation.Search.config file. These are particularly useful when configuring Search Results renderings or Gallery components.

Common search tokens include:

  • UnderCurrentPage: Filters results to only include items located beneath the current page in the content tree.
  • ExcludeCurrentPage: Ensures the current context page is not included in the search results.
  • ItemsOfTheSameTemplateAsTheCurrentPage: Automatically filters results to match the template of the page the user is currently viewing.
  • TaggedTheSameAsCurrentPage|SxaTags: Filters items that share the same SXA Tags as the current page.
  • ItemsWithTheSameValueInField|FieldName: A dynamic filter that matches items based on a specific field value shared with the current page.

How to Define Custom SXA Tokens

While the out-of-the-box tokens cover most scenarios, you may encounter unique business requirements where a custom token is necessary. For example, you might want a $globalData token that points to a specific shared repository outside of the current tenant.

To define your own token, you need to add a new processor to the resolveTokens pipeline. Here is the general approach:

1. Create the Processor Class

You will need to create a class that inherits from Sitecore.XA.Foundation.TokenResolution.Pipelines.ResolveTokens.ResolveTokensProcessor (or a similar base class depending on your specific SXA version).

using Sitecore.XA.Foundation.TokenResolution.Pipelines.ResolveTokens;

public class ResolveCustomTokens : ResolveTokensProcessor
{
    public override void Process(ResolveTokensArgs args)
    {
        if (string.IsNullOrWhiteSpace(args.Query))
        {
            return;
        }

        // Example: Replace $myCustomToken with a specific path
        if (args.Query.Contains("$myCustomToken"))
        {
            string customPath = "/sitecore/content/GlobalData/Settings";
            args.Query = args.Query.Replace("$myCustomToken", customPath);
        }
    }
}

2. Register the Processor via Config

Once your code is compiled, you must patch it into the Sitecore configuration. Place your processor within the resolveTokens pipeline:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <pipelines>
      <resolveTokens>
        <processor type="YourNamespace.ResolveCustomTokens, YourAssembly" 
                   patch:after="processor[@type='Sitecore.XA.Foundation.TokenResolution.Pipelines.ResolveTokens.ResolveSiteToken, Sitecore.XA.Foundation.TokenResolution']" />
      </resolveTokens>
    </pipelines>
  </sitecore>
</configuration>

Best Practices for Using Tokens

When working with tokens in SXA, keep these best practices in mind to ensure your solution remains performant and maintainable:

  1. Prefer Tokens over Paths: Always use $site or $home in rendering datasources if the data resides within the site structure. This makes site cloning and branching significantly easier.
  2. Use Query Notation Correctly: Remember that tokens are often used within a Sitecore query. Ensure your syntax follows the query:$token/ChildItem format.
  3. Validate for Multi-Language: When using tokens in multi-language environments, ensure your query accounts for language versions, or use the $lang token available in newer versions.
  4. Monitor Performance: Complex queries using multiple tokens can occasionally impact performance in the Content Editor. Keep your queries as shallow as possible.

Frequently Asked Questions

Can I use these tokens in standard Sitecore renderings without SXA?

No, these specific tokens are part of the SXA Foundation assemblies. While standard Sitecore supports some basic tokens (like $parentid or $home in certain contexts), the extensive list provided here is unique to the SXA resolveTokens pipeline.

Why isn't my custom token resolving in the Content Editor?

Ensure that your config patch is applied correctly by checking /sitecore/admin/showconfig.aspx. Also, verify that your processor logic handles null or empty query strings to avoid exceptions during the resolution process.

Wrapping Up

Sitecore SXA query tokens are essential for building scalable, multi-site digital platforms. By mastering the use of $site, $tenant, and search-specific tokens, you can create a highly flexible content architecture that adapts to your organizational needs. Whether you are using the robust out-of-the-box library or extending the pipeline with your own custom logic, these tokens are the key to a professional SXA implementation.