When you’re working with Sitecore Experience Accelerator (SXA), there’s a big chance that you’re using Scriban. Scriban is a lightweight scripting language and engine for .NET, and is used when you define a Template Variant field in any Rendering Variant.
Within plain Scriban it is possible to use includes, which allows you to render another Scriban template where you call the include. This makes sure you can re-use parts of your templates, and makes sure you can define your templates in a modular way. For example, when you have a primary button which only differs by text and URL, you define a generic Scriban template called primary-button.html. The contents of this file may be as follows:
<a href="{{ $.url }}" class="primary">
{{ $.text }}
</a>
Now when you want to re-use that primary button, all you have to do, is to call the include which is shown in the example below.
{{ include 'primary-button.html' text:'My button' url: 'https://maartenwillebrands.nl' }}
The example above will lead to the following HTML
<a href="https://maartenwillebrands.nl" class="primary">
My button
</a>
Great, now how do i do this in SXA?
Well, you can’t, not just yet. SXA does not offer the include function out of the box, but luckily for us, there are enough extensions points. I’ve developed a SXA module called Sitecore Scriban Extensions, which makes it possible to use includes within SXA. All the code and Sitecore items that are needed are located on this GitHub page, and you can download a Sitecore Installation Package as well.
How to use the Sitecore Scriban Extensions
1. Install the Sitecore Scriban Extensions
Either build Siteocre Scriban Extensions yourself using the code from GitHub, or download the Sitecore Installation Package and install it through the Package Installation Wizard.
2. Install the Sitecore Scriban Extensions module to your site
First of all, make sure that you install the Sitecore Scriban Extensions module on your SXA website. You can do this by navigating to your SXA Site item, go the the Modules field, and add the Sitecore Scriban Extensions module by adding it to the “Selected column”. The module can be found beneath Feature\Sitecore Scriban Extensions, and you have to select Sitecore Scriban Extensions Site Setup.
After saving your Site item, Sitecore will execute the Site Setup that is defined in the module. This will create a new folder within the Presentation node in your site, called Scriban Includes, located at /sitecore/content/Your Tenant/Your Site/Presentation/Scriban Includes.
3. Define one or more Scriban Includes
Scriban Includes can be defined within the folder that is automatically created in step 1. Each Scriban Include consists out of a Key field, which is used as the name for your include, and the Template field where you can define your Scriban template. To follow the plain Scriban example which i’ve showed above, we create a Scriban Include as follows:
You might have noticed that i’ve replaced the $.text and $.url by se_param $ ‘url’. The current version of Scriban which is shipped within SXA 10 has a bug that causes named arguments not being accessible on the normal way. I’ve created a helper function for this that allows you to easily get the value of your named argument, which is called se_param. The first argument should be the argument object $, and the second parameter is the name of the named argument, for which you’d like the value.
4. Use the Scriban Include in your Rendering Variant
Using the Scriban Include within SXA is exactly the same as using it in plain Scriban. Just add the following to your Scriban template within your Rendering Variant
{{ include 'primary-button' text:'My button' url: 'https://maartenwillebrands.nl' }}
5. Additional information
Shared Sites
Scriban Includes can also be defined on a Shared Site. All includes that you define on a Shared Site, can be used in any Rendering Variant, as long as it has access to the Shared Site.
Settings
There are two settings defined within the Sitecore Scriban Extensions module, which can be found within the Custom.XA.Feature.ScribanExtensions.config file.
Custom.XA.Feature.ScribanExtensions.Includes.CacheSize
This setting defines how big the Cache should be where all the Scriban Includes are stored. If you define a cache size that is too small, Sitecore will have to fetch the Scriban Include items multiple times.
Custom.XA.Feature.ScribanExtensions.Includes.OutputMissing
If true, this setting will make sure a message is rendered when you include a Scriban Include within any of your templates, that doesnt exist.
Sitecore / SXA version
This has been tested on Sitecore 10.0.1 and 10.1, however it should work on previous versions of SXA where Scriban is included.