The embedded functions for the Scriban template

Abstract

Learn more about Sitecore embedded functions for Scriban.

This topic describes the Sitecore embedded functions for the Scriban template.

Returns component decoration with styles, grid classes, and attributes required by Creative Exchange.

This helper function is an equivalent of the @Html.Sxa().Component() helper function from MVC Razor views. You can use this function to control your markup in the Scriban templates. If you use this function, your Razor view can be almost empty. You can call the rendering variant functionality and embed the sc_decorate helper function to add the styles and grid classes that your user chose in the rendering parameters.

Parameters

Type

Optional

Example

Purpose

string

yes

'hero promo'

Adds classes to the component decoration.

Example

The following example shows the Scriban template you could use for the Promo component, if you modified the Razor view to not provide any markup but fully delegate the rendering process to your variant instead. The template output with this markup is identical to the Default Promo variant. In the first line of the example, you can see how to use the sc_decorate function. You can add other attributes to the tag in the template directly.

<div {{ sc_decorate "promo" }} role="banner">
    <div class="component-content">
        <div class="field-promoicon">
            {{ i_item.PromoIcon }}
        </div>
        <div class="promo-text">
            <div>
                <div class="field-promotext">
                    {{ i_item.PromoText }}
                </div>
            </div>
            <div class="field-promolink">
                {{ i_item.PromoLink }}
            </div>
        </div>
    </div>
</div>

The first line will render in the following way for visitors:

<div class="component promo col-12" role="banner">

To enable class editing and importing styles for Creative Exchange:

<div class="component promo col-12 add-your-css-classes-here"
  data-pageid="{A25A4448-3319-4A52-93DE-B10A7A158DFD}"
  data-renderingid="{51C13F03-8364-4F61-B860-2EC6CA7439B3}"
  data-uniqueid="{8DED9C5D-5D8D-4C16-93A0-A78928B17656}"
  data-variantid="{D51080C1-C9A8-457A-88B1-EF3CF21DD6FF}"
  data-stylesfield="Styles"
  data-gridfield="GridParameters"
  data-renderingclass="promo"
  role="banner">

Renders the edit frame around an area of HTML and lets you specify a set of Experience buttons that help users edit the content within that area.

Parameters

Type

Optional

Example

Purpose

Item

no

i_item

Item for which the edit frame is rendered, enabling the editing of its fields.

string

no

'Gallery Image'

The name of the Edit Frame folder item under the /sitecore/content/Applications/WebEdit/Edit Frame Buttons/ path within the core database.

sc_endeditframe contains no parameters and is used to close the area around the wrapped edit frame.

Example

The following example replicates the Default Gallery component rendering variant, including edit frames. For the default setting go to: /sitecore/system/Settings/Foundation/Experience Accelerator/Rendering Variants/Rendering Variants/Gallery/Default

{{-
  if i_item.template_name == "Gallery Image"
    sc_editframe i_item 'Gallery Image' -}}
    <a class="field-image">
      <a title="{{ i_item.ImageTitle.raw }}" href="{{ i_item.Image.media_url }}">
      {{ i_item.Image }}
      </a>
    </a>{{
    sc_endeditframe
  end -}}

{{-
  if i_item.template_name == "Gallery Video"
    sc_editframe i_item 'Gallery Video'
    if (i_item.VideoID.raw ) == "" &amp;&amp; (i_item.VideoThumbnail.raw) == "" -}}
      <span>[Edit Gallery Video here]</span>{{
    else -}}
      <a title="{{i_item.VideoTitle.raw }}" href="http://www.youtube.com/watch?v={{ i_item.VideoID.raw }}">
      <img src="{{ o_model.thumbnail_url }}" alt="{{ i_item.VideoDescription.raw }}"
             data-title="{{ i_item.VideoTitle.raw }}" data-description="{{ i_item.VideoDescription.raw }}" ></img>
      </a>{{
    end
    sc_endeditframe
  end }}

Renders a dynamic placeholder with optional context switch.

Parameters

Type

Optional

Example

Purpose

string

no

'mykey'

The placeholder key.

Item

yes

i_item

Optional item to switch context to.

If the item is specified, components inside the placeholder behave as if they were rendered on i_item.

Example 1

The following example shows you how to render a dynamic SXA placeholder:

{{ sc_placeholder "mydynamic"  }}

Example 2

The following example shows you how to render a dynamic SXA placeholder and switch its context to a related i_product item. The components in that placeholder behave as if the page on which they were rendered was i_product.

{{
  i_product = i_page.RelatedProducts.target
  sc_placeholder "relatedproducts" i_product
}}

Executes a rendering variant field located beneath the Scriban template.

SXA lets you embed additional rendering variant fields underneath a Scriban template (similar to, for example, the rendering variant section), but unless you call them explicitly with sc_execute they will not get rendered.

When you runsc_execute i_item "Item below template", you tell the templating engine to render the Item below template in the hierarchy, and paste it where the sc_execute function is.

Parameters

Type

Optional

Example

Purpose

item

no

i_item

Item in the context where the rendering variant elements are executed.

string

no

'Responsive Image'

The name of the rendering variant field.

Example

You can render a responsive image renderer in your Scriban template by adding a rendering variant field of type Scriban to a rendering variant. For example, create a variant for your Promo component and name it Responsive Promo. Add a rendering variant field of type Scriban and name it Template. If you then add a rendering variant field of type Responsive image, pasting the following code in the Template rendering variant field will render a responsive image renderer:

<div class="field-promoicon">
    {{ sc_execute i_item.PromoIcon.target "Responsive Icon" }}
</div>
<div class="promo-text">
    <div>
        <div class="field-promotext">
            {{ i_item.PromoText }}
        </div>
    </div>
    <div class="field-promolink">
        {{ i_item.PromoLink }}
    </div>
</div>

Evaluates the rendering variant rule stored beneath the Scriban template and returns the evaluated value (true or false) based on the result of the rule execution.

Parameters

Type

Optional

Example

Purpose

Item

no

i_item

Item for which the rule is evaluated.

string

no

'Responsive Image'

The name of the rendering variant rule (stored under the Scriban template) that is evaluated during the rendering process.

Example

You can render a personalization rule in your Scriban template by adding a rendering variant field of type Scriban to a rendering variant. For example, create a variant for your Promo component and name it Personalized Promo. Add a rendering variant field of type Scriban and name it Template. If you then add a rendering variant field of type Rule, pasting the following code in the Template rendering variant field will render a personalization rule.

<div class="promo-text">{{
  if sc_evaluate i_datasource "Personalization" -}}
    <div>
      This will be shown when the personalization rule will evaluate to TRUE
    </div>{{
  else -}}
    <div>
      This will be shown when the personalization rule will evaluate to FALSE
    </div>{{
  end -}}
</div>

Retrieves the raw value of a field from an item.

Parameters

Type

Optional

Example

Purpose

Item

no

i_item

Item for which the value of the field is retrieved.

string

no

'FieldName'

The name of the field that you want to retrieve.

Example

<h1>{{ sc_raw i_page "Title" }}</h1>

Renders a Sitecore field that allows fall back when a field is empty and allows you to add parameters to tags for, for example, images or links.

Parameters

Type

Optional

Example

Purpose

Item

no

i_item

Item for which the value of the field is retrieved.

string or string[]

no

'FieldName'

Name of the field that is rendered.

Alternatively, you can provide an array of field names in which case the function checks the list from left to right and renders the first field that is not empty.

In Experience Editor, in Edit mode, the first field is always used, even if it is empty.

string[][]

no

[['attribute1','value1'], ['attribute2','value2']]

Array of name/value arrays of string allowing you to specify additional parameters to field renderers on fields, such as Link or Image.

Example

For example, use the following sample code to render a field on an item by calling the sc_field function:

{{ sc_field i_page 'Title' }}

Field fallback example

If you want to provide a field for authors to enter a value for, and make sure that field is not empty even if the author did not enter a value, you can use the field fallback functionality provided in the sc_field function:

{{ sc_field i_page ['NavigationTitle', 'Title', '__Display Name'] }}

The templating engine attempts to render 'NavigationTitle' , and if it does not find a value within it, it moves on to the 'Title' field to return the attempt and finally falls back to '__Display Name' if that fails as well.

Formatting and data attributes on link and image fields

When you want to augment the default rendering behavior of the link or image rendering fields, you can provide an additional name/value collection that will be passed to the Sitecore field renderer as the third parameter, as illustrated in the following examples.

Image renderer example

The following example renders an image with height and width set to 50 and an additional data attribute data-purpose:

{{ sc_field i_item 'PromoIcon' [['h', '50'], ['w', '50'], ['data-purpose', 'Promo Icon']] }}

The code above results in the following HTML rendered on your page:

<img src="/-/media/MyImage.jpg?h=50&amp;amp;iar=0&amp;amp;w=50" alt="" width="50" height="50" data-purpose="Promo Icon">

The following parameters will be used by the field rendered. Any additional parameters will be used as data attributes:

Parameter

Legal Values

Default Value

Description

as

true

false

Allow stretching the image beyond its original size?

bc

Color names (such as black or red) and HTML hex color codes (such as CE55E2)

black

Background color for the border added when an image is stretched beyond its original size (and allowStretch=false).

db

Any Sitecore database defined on the site.

content database of the current site

The name of the Sitecore to pull the image from.

dmc

true

false

Disable the media cache for this request? If true, the image will always be retrieved from the database, bypassing the media cache.

h

Any positive integer

The height of the image. You must include as=true if you want the height to be larger than its original size.

la

Any valid language name

Retrieve the image from a specific language version of the item.

mh

Any positive integer

Maximum height of the image to display.  Scale the image down to this size if necessary.

mw

Any positive integer

Maximum width of the image to display.  Scale the image down to this size if necessary.

sc

Any positive floating point number using a dot as a decimal point (such as 1.5, which corresponds to 150%)

Scale factor for the image displayed.  You must include as=true if you want to scale the image to larger than its original size.

thn

true

false

Display a thumbnail of the requested file. Useful for images as well as other media types, such as PDF, flash, and so on.

vs

Any positive integer

Retrieve the image from a specific version of the item.

w

Any positive integer

The width of the image. You must include as=true if the width will be larger than its original size.

Link renderer example

Similar to the link field renderer, with the link renderer you can add attributes depending on your needs. The following example uses the PromoLink target item’s title to add an ARIA accessibility label to your links:

{{ sc_field i_item 'PromoLink' [['aria-label', (i_item.PromoLink.Title.raw)]] }}

The above example can generate the following HTML:

<a href="/Page" aria-label="Page Title">Page</a>

Returns the item that is selected from a field and stores links to items. If the field can contain links to multiple items, the first item in the list is returned. If the field is empty, the function returns a null value.

Parameters

Type

Optional

Example

Purpose

Item

no

i_item

Item for which the value of the field is retrieved.

string or string[]

no

'FieldName'

Name of the field that links to items.

Note

You can also use the shorter i_item.target notation. If you do, be aware that i_item.target does not allow following links for fields that contain special characters, such as ‘.’, ‘,’, white spaces, and so on.

Example

To render more information about a product linked from a Promo component:

<h2>{{ sc_follow i_item "Promo Link" | sc_field "Title" }}</h2>

Returns an array of items selected in a field that can store link to items. If the field is empty, the function returns an empty list.

Parameters

Type

Optional

Example

Purpose

Item

no

i_item

Item for which the value of the field is retrieved.

string or string[]

no

'FieldName'

Name of the field that links to items.

Note

You can use the shorter i_item.targets notation. If you do, be aware that it does not allow following links for fields that contain special characters, such as ‘.’, ‘,’, white spaces, and so on.

Example

To render products related to the current product:

{{ for i_product in (sc_followmany i_page "Related Products") }}
  <h2>{{ sc_field i_product "Title" }}</h2>
  <b>Content</b>:{{ sc_field i_product "Content" }}
{{ end }}

Returns the URL string to the item provided as the parameter. If the item is null the function returns #.

Parameters

Type

Optional

Example

Purpose

Item

no

i_item

Item for which the link is generated.

Note

You can also use the shorter i_item.url notation. If you do, be aware that it does not allow following links for fields that contain special characters, such as ‘.’, ‘,’, white spaces, and so on.

Example

Render a link to the component Data Source using the Display name of the data source item as the text of the link:

<a href="{{ sc_link i_datasource }}">{{ i_datasource.display_name }}</a>

Returns the Media URL string to the item provided as the parameter. If the item is null the function returns #.

Function parameters

Type

Optional

Example

Purpose

Item

no

i_item

Media item for which the link is generated.

Note

You can also use the shorter i_item.media_url notation. If you do, be aware that it does not allow following links for fields that contain special characters, such as ‘.’, ‘,’, white spaces, and so on.

<a download href="{{ sc_follow i_datasource 'PromoIcon' | sc_medialink }}">{{ i_datasource.PromoIcon.name }}</a>

Executes a Sitecore query and returns the resulting items as an array.

Parameters

Type

Optional

Example

Purpose

Item

no

i_item

The item in the context of which the query is executed.

string

no

'query:./*'

The query to execute.

Example

{{ for i_child in (sc_query i_page 'query:./*') }}
  <h1>{{ i_child.Title }}</h1>
{{end}}

Retrieves the rendering parameter values.

Parameters

Type

Optional

Example

Purpose

string

no

ID

Name of the parameter for which the value is retrieved.

<div>This rendering is in the '{{ sc_parameter 'Placeholder' }}' placeholder.<div>

Returns the text according to the input string and the current language the page is rendered in. Translations are stored in a dictionary that is located at the root of your site item.

Parameters

Type

Optional

Example

Purpose

string

no

key

The key from the site dictionary.

string

yes

language

Provide the language code to force the text to be translated to the specific language instead of taking the language from the request context.

<button class="button cancel">{{ sc_translate 'Cancel' }}</button>