Customizing the Commerce Search Results rendering

Abstract

Overview of the Commerce Search Results rendering Scriban template, which you can customize by modifying the code.

The Commerce Search Results rendering variant includes an additional renderer in the form of a Scriban template. Scriban templates are available as renderers similar to, for example, field renderers, sections, or tags and can coexist with other renderers. Scriban templates can contain sophisticated logic that cannot be expressed using other renderers and can greatly reduce the complexity of rendering variants by including numerous renderers in one template. You can also use them to replace existing rendering variants.

Note

General documentation about the underlying templating language and the built-in functions is available on the Scriban GitHub repository.

Location of the Scriban template in the content tree

The Scriban template is responsible for rendering the markup for the individual product cards. It is executed within a loop in the corresponding MVC View that iterates over the product items. To change the markup generated for the product cards, you can modify the Scriban template. It is best to create a new custom rendering variant in this case so that the customization does not get overridden during software upgrades.

Note

For a demo of how to modify a Scriban template, see the Sitecore Experience Commerce video on Master Sitecore.

The following code shows the Commerce Search Results rendering Scriban template defined within the default rendering variant.

<div class="product-summary" data-id="{{ i_item.name }}">
    {{ displayName = i_item.display_name | html.escape }}
    <div class="product-photo">
        <a title="{{ displayName }}" href="{{ i_item.url }}">
            {{
                productImage = i_item.images.targets | array.first
                if productImage
                    sc_execute productImage "Responsive Image" 
                end
            }}
            <div data-bind="css: { 'promotion': promotion }" class="hidden">
                <span data-bind="text: promotion" class="savings-percentage"></span>
                <span class="savings-label">{{ sc_translate 'SAVINGS_LABEL' }}</span>
            </div>
        </a>
    </div>
    <div class="product-info">
        <a class="product-title" title="{{ displayName }}" href="{{ i_item.url }}">
            {{ displayName }}
        </a>
        <div class="product-brand">
            {{ i_item.brand }}
        </div>
        <div class="product-indicator">
            <label class="hidden" data-bind="css: { 'price-difference': hasDifferentPrice }">
                {{ sc_translate 'STARTING_FROM' }}
            </label>
            <label class="stock-status" data-bind="text: stockLabel"></label>
        </div>
        <div class="product-detail" data-bind="css: { 'on-sale': promotion }">
            <span data-bind="text: price" class="product-price"></span>
            <a class="product-link" title="{{ displayName }}" href="{{ i_item.url }}">
                {{ sc_translate 'DETAILS' }}
            </a>
        </div>
    </div>
</div>

You can customize the following Commerce Search Results rendering Items. The Commerce Search Results rendering is a clone of the SXA Search Results rendering specific to Commerce. It has its own default rendering variant root and default rendering variant (/sitecore/Content/<tenant>/<site>/Presentation/Rendering Variants/Commerce Search Results), which uses a Scriban template for generating the markup, JavaScript for retrieving the stock and price information (as an AJAX request), and the SXA Dictionary for label translation.

Note

You can change the labels used with the Commerce Search Results rendering.

The following table details the key properties of the Commerce Search Results Scriban template.

Property

Type

Description

Code

i_item

Item

The current item in the context of the rendering variant. Often, an equivalent to the i_datasource item, but in this case it is exposing catalog data for the individual items. In the default implementation, it is assumed that items are all of type products, but might be bundles, categories, and variants. The i_item item is used to store various types of data in this template. For example, the i_item.name property stores the Product ID and is assigned to a data attribute named id, and the i_item.url property stores the link to the product detail page and is assigned to the href attribute.

<div class="product-summary" data-id="{{ i_item.name }}">

displayName

Variable

Used in various contexts. For example, it is initialized to i_item.display_name, which stores the Display Name of the product. The variable is passed into the built-in function html.escape so that the returned string is escaped in HTML.

It is also assigned to the title attribute in the anchor tag. The i_item.url property, which stores the link to the product page, is assigned to the href attribute. The displayName variable is also assigned as text for the anchor tag.

 {{ displayName = i_item.display_name | html.escape }}

title

Attribute

The displayName variable is assigned to the title attribute in the anchor tag. The i_item.url property, which stores the link to the product page, is assigned to the href attribute.

<a title="{{ displayName }}" href="{{ i_item.url }}">

productImage

Variable

Initialized to i_item.images.target, which is an array of images of the product. The variable is passed into the built-in function array.first so that it returns the first element of the array.

Note

An if block checks if the productImage is not null. If it is not null, then the custom function sc_execute is called to render and run scaling of the image.

productImage = i_item.images.targets | array.first

Responsive Image

Responsive Image

A subitem of type Responsive Image that must be created under the Scriban item in the Content Editor (sitecore/Content/Sitecore/<tenant>/<site>/Presentation/Rendering Variants/Commerce Search Results/Default/Scriban/Responsive Image), as shown in the following figure:

ScribanResponsiveImage.png

This renderer runs when sc_execute is called to render and scale the image.

Note

On the Content tab, in the VariantDetails section, you can set the width field in pixels to change the dimensions to which the image is scaled.

if productImage             sc_execute productImage "Responsive Image" 
end

sc_translate

Embedded Function

Used to display items defined in the Dictionary Domain of the site (sitecore/Content/<tenant>/<site>/Storefront Dictionary) as shown in the following figure:

ScribanStorefrontDictionary.png
<span class="savings-label">{{ sc_translate 'SAVINGS_LABEL' }}</span>

i_item.brand

Property

Stores the brand name of the product and is displayed in the <div> element.

<div class="product-brand">
{{ i_item.brand }}
</div>