Skip to main content

Sitecore

Scribing Scribans in SXA

Person writing and fire comes out of the pen

Salutations! So you seek to assemble the science of scribing scribans in SXA? Look no further, for here in this four-part guide I will detail the amazing power and control that scribans in SXA offer.

The Four-Part Guide

Part 1 – What are scribans, cloning the promo, adding a scriban
Part 2 – Basic functions, some Do’s and Don’ts, and helpful links (TBD)
• Part 3 – More scriban and Sitecore functions, including looping and rendering pages from a folder (TBD)
• Part 4 – Advanced scriban logic and visual shenanigans (TBD)

What are Scribans in SXA?

While I will detail a brief overview of them, I highly recommend this fantastic guide from Ramakant Chandel on what scribans are.

In short, scribans are available as definitions for rendering variants, where you specify your own custom HTML structure and define how and where the data from your template are handled.
Scribans have a specific language and syntax for pulling data from the data source and combining logic plus html/css/js in one file. (You can in fact put all three in the same file, I’ll go ahead and recommend against that in most cases).

The SXA Basics

In the first two parts, we will learn to build a card that looks like this:

Default / Hover

Green Matrix Code

Default Card State

 

Card Content Screenshot

Card state on hover

 

 

 

 

 

 

 

Let’s knock out the basic Sitecore aspects first. We will clone the Promo component to get the scaffolding. To do that, navigate to the Promo rendering template, right click, and select clone.

Sitecore Navigation Screenshot

When cloning:
• Name the rendering whatever you’d like, I’m naming it Card Demo
• The css name you give it will be the top-level class name the div element receives
• I am locating it at the Sitecore default location

Sitecore Navigation Screenshot

• Make a copy of the Rendering Template

Sitecore Navigation Screenshot

• Make a copy of the Datasource template

Sitecore Navigation Screenshot

• Keep the cshtml file the same. We will not need to touch it in typical SXA fashion (and because ~scribans~)

Sitecore Navigation Screenshot

Once this is done, you should have the bare fundamentals for the component. For now, I am just renaming a few of the fields on the data template, but that is not necessary, just make sure you reference them properly in the scriban.

With that out of the way, we turn to our rendering, where the superb simplicity of scribans shall save us much scribbling.

Before that, however, it’s time to format an editor of your choice such that with it you can edit scribans. By default, Sitecore provides a small text box with a plethora of code features like:

• This

• That

• And this

which will not suffice. I will demonstrate how to set up Visual Studio Code to edit scribans, which I highly recommend.

Optional Setting Up VSCode for Scribing Scribans in SXA

Select the extension icon in the sidebar, and search “scriban”.

I recommend installing both Xoofx’s scriban extension, and Adam Najmanowicz’s scriban extension.

Scriban SXA VSCode extension

Once you have those installed and enabled, create a file and give it the “.scriban-html” extension. Try pasting the following lines in to see if it works:

<div class="wrapper ">
     {{ if (o_pagemode.is_experience_editor_editing) }}
          <div class="edit-mode">

Since the extension is installed, it should appear in a color pattern like this:

Code Screenshot

Which will make it much easier to see what we are doing.

Adding the Scriban Variant In SXA

Now, navigate to the rendering variant. You should be able to find it via a path looking like this: /sitecore/Content/[tenant]/[site]/Home/Presentation/Rendering Variants.

Insert a new variant:

SXA Navigation Screenshot

Edit the compatible renderings so that this variant definition is compatible with the Card Demo template:

Sitecore Navigation Screenshot

Sitecore Navigation Screenshot

Sitecore Navigation Screenshot

Now add a variant definition:

Sitecore Navigation

And add the scriban:

Insert scriban

As an aside, it is often useful to name uniquely, as content control systems like unicorn will name the yml file after it. Looking through a giant list of “Scriban.yml” or “Default.yml” is not particularly helpful.

Now we are ready. Check out how to use scriban functions and manage the Experience Editor experience in Part 2!

 

Links

Scribing Scribans in Sitecore according to Sitecore

The Scriban Language

Thoughts on “Scribing Scribans in SXA”

  1. Great post. Love the recommend for the Scriban extension, I’ll have to try that one out!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Drew Taylor, Technical Consultant

Drew is a technical consultant at Perficient. He enjoys writing code and books, talking AI, and advocating accessibility.

More from this Author

Follow Us
TwitterLinkedinFacebookYoutubeInstagram