Use custom resources

Storefront Builder supports custom resources, such as images, which you can use to override default product images in certain situations. For example, you might want to use custom product images for sliders or backgrounds instead of the default product images, which appear on product profile pages.

To use custom resources, you must add the desired images to the theme and add some custom code to the appropriate macro HTML file to point to the images. The custom code consists of the r function, as well as the Nunjucks join filter (for concatenation). You can import the macro to other pages to show custom images for different products, as required.

You can use variables, such as productID or name, to build dynamic paths to custom resources, and then feed those paths to the r function. The examples in this topic demonstrate how to do so.

important

Follow these guidelines when you use custom resources:

• If you are replacing images in a product list (for example, for sliders), you must replace the images of all products in the list.
• When you import a macro that contains the r function, you must add with context to the end of the import line to ensure that Nunjucks passes the current context to the macro.

To use custom images

1. Identify the page and page element in which you want to include custom images, for example the hero slider on the home page.
2. Use the Data Viewer to view the IDs of the products whose images you want to replace.
3. Copy the desired images to the /_themeName_/assets/images folder.
4. Rename the images to use a standard naming convention, for example _productID_-slider-image.jpg.
5. Open the macro file that corresponds to the page element. Macro files are located in the /_themeName_/content/macros/ folder.
6. Replace the image source in the macro file with the r function and an expression to build the image file names. For example:
   r(["/assets/images/", product.id, "-slider-image.jpg"] | join)
   In this case, for a product with ID 100, the slider would display /assets/images/100-slider-image.jpg.
7. Save the file and refresh the page.

Example: Hero slider

The following example shows how to implement custom images in the hero slider macro file, /_themeName_/content/macros/sliders/hero.html.

<div class="hero__carousel__container">
  <div class="slider--items" tabindex="0">
    {% for product in products %}
      <div class="hero__item">
        <div class="hero__item_card">
          <div class="hero__item_image">
            <div class="id">
              <img aria-label="{{product.name}}" class="id--heroimg" alt="" **src="{{ r(["/assets/images/", product.id, "-slider-image.jpg"] | join) }}"**>
            </div>
          </div>
          <div class="hero__item_content">
            <a class="title__xxlarge" href="{{product.url}}">{{product.name}}</a>
            <p data-truncate="paragraph" title="Cognitive Enterprise Mobility Management">{{product.blurb}}</p>
            <a href="{{product.url}}" class="button button__emphasis button__large" type="button">{{i18n.learnMore}}</a>
          </div>
        </div>
      </div>
    {% endfor %}
  </div>
</div>

Example: Hero slider on custom pages

After you update the macro file, you can import the macro to use custom resources on custom pages. Add with context to the import:

{% from "/macros/sliders/hero.html" import hero with context %}

The following example shows how to use custom resources on a custom Special Offers page. As in the previous example, you would have to add custom images for each product in the livechat list.

{% extends "/layout/base.html" %}
{% from "/macros/sliders/hero.html" import hero with context %}
{% from "/macros/sliders/script.html" import sliderScript %}

{% block data %}

<data name="livechat" type="list" subcategories="2236" />

{% endblock %}

{% block content %}

<h2>Special Offers</h2>

{{ hero(productLists.customLists.livechat.products, i18n) }}

{{ sliderScript() }}

{% endblock %}