How do I display content blocks on the storefront?

The structure of the views for the block items is shown below. If you are creating your own theme or custom storefront, you must ensure these files are present in order for the content blocks to display correctly:

└─ resources
    └─ views
        └─ blocks
            └─ html.twig
            └─ image.twig
            └─ link.twig
            └─ menu.twig
            └─ text.twig

Block Items

A single block item

To show a single block item, use block_item twig function, passing the block's key:

{{ block_item('product-page.confidence-builder') }}

This will show the first available block item in the block.

To show a different block item, provide the position as the second parameter:

{% if block_exists('homepage.brand-heroes') %}
    <div class="flex w-full flex-wrap">
        <div class="w-full md:w-1/2">
            {{ block_item('homepage.brand-heroes', 0) }}
        </div>
        <div class="w-full md:w-1/2">
            {{ block_item('homepage.brand-heroes', 1) }}
        </div>
    </div>
{% endif %}

A collection of block items

To show all block items in a content block, use the block_items twig function, passing the block's key:

{{ block_items('product-page.confidence-builders') }}

If you need to limit the number of items returned in the collection, pass a limit as the second parameter:

{{ block_items('product-page.confidence-builders', 3) }}

If the block items need to be wrapped in elements to style their position, the following approach can be used:

{% if block_exists('homepage.main-hero') %}
    {% set main_hero = block_items('homepage.main-hero', null, {
        sizes: {
            small: { width: 360, height: 360 },
            medium: { width: 660, height: 560 },
            large: { width: 1280, height: 600 }
        }
    }) %}
    <div class="flex w-full flex-wrap">
        {% for hero in main_hero %}
            <div class="w-full">{{ hero | raw }}</div>
        {% endfor %}
    </div>
{% endif %}

You must use the raw filter to ensure the block item HTML isn't escaped.

Passing data

In some cases (as seen in the previous example), a block item may need data to be passed from the theme.

This is especially useful for themes, which dictate the image dimensions:

{{ block_item('listings.loyalty-banner', 0, {
    sizes: {
        small: { width: 400, height: 200 },
        medium: { width: 600, height: 260 },
        large: { width: 1024, height: 300 },
    },
    options: ['contain', {quality: 90}],
}) }}