Next Commerce
ThemesTemplates

Object Reference

Objects are template variables you can use to dynamically populate templates in your storefront theme. See documentation below and details of available template objects and their properties.

Global Objects

Global objects are available across all templates and pages enabling theme developers to create dynamic custom pages powered by the store data.

currencies

Returns a list of active storefront currencies you can iterate over, see currency.

Example Storefront Change Currency Form
{% if currencies and currencies|length > 1 %}
<li>
    <form action="{% url 'core:set-currency' %}" method="post" id='set-currency' class="px-2">
        {% csrf_token %}
        <select class="form-select form-select-sm" name="currency">
            {% for currency in currencies %}
            <option value="{{ currency.code }}" {% if request.CURRENCY_CODE == currency.code %} selected {% endif %}>
                {{ currency.symbol }} {{ currency.code }}
            </option>
            {% endfor %}
        </select>
    </form>
</li>
{% endif %}

languages_active_storefront

Returns a list of active storefront languages you can iterate over, see language.

Example Storefront Change Language Form
{% if languages_active_storefront %}
<li>
    <form action="{% url 'set_language' %}" method="post" id='set-language' class="px-2">
        {% csrf_token %}
        <input name="next" type="hidden" value="{{ language_neutral_url_path }}">
        <select class="form-select form-select-sm" aria-label="language" name="language">
        {% for language_code, name in languages_active_storefront %}
            <option value="{{ language_code }}" {% if request.LANGUAGE_CODE == language_code %} selected {% endif %}>
                {{ name }}
            </option>
        {% endfor %}
        </select>
    </form>
</li>
{% endif %}

Allows you to access a menu's items by its code to iterate over to generate a menu from the backend, see menu items. Menus are configured in the dashboard at Storefront > Navigation.

Example Dynamic Menu
{% for item in menus.header_menu.items %}
    {% if item.level > 0 %}
        <li class="nav-item dropdown">
            <a class="nav-link dropdown-toggle {% if item.child_active %}active{% endif %}" href="{{ item.url }}">{{ item.name|title }}</a>
            <ul class="dropdown-menu">
                {% for child_item in item.items %}
                    {% if child_item.level > 0 %}
                        <li>
                            <a class="dropdown-item dropdown-toggle {% if child_item.child_active %}active{% endif %}" href="{{ child_item.url }}">{{ child_item.name|title }}</a>
                            <ul class="dropdown-menu dropdown-submenu">
                                {% for grandchild_item in child_item.items %}
                                <li>
                                    <a class="dropdown-item {% if grandchild_item.current %}active{% endif %}" href="{{ grandchild_item.url }}">
                                    {{ grandchild_item.name|title }}
                                    </a>
                                </li>
                                {% endfor %}
                            </ul>
                        </li>
                    {% else %}
                        <li>
                            <a class="dropdown-item {% if child_item.current %}active{% endif %}" href="{{ child_item.url }}">
                                {{ child_item.name|title }}
                            </a>
                        </li>
                    {% endif %}
                {% endfor %}
            </ul>
        </li>
    {% else %}
        <li class="nav-item">
            <a class="nav-link {% if item.current %}active{% endif %}" href="{{ item.url }}">{{ item.name|title }}</a>
        </li>
    {% endif %}
{% endfor %}

Storefront Menus can be up to 3 levels, ensure your custom menu supports 2 nested menu item levels, see child and grandchild above.

products

Returns a list of products you can iterate over, see product.

Example Storefront Products Query and Loop
{% where products 'title' 'contains' 'featured' as products_filtered %}
{% for product in products_filtered %}
<div class="col">
    <div class="card h-100">
        {% with image=product.primary_image %}
        {% image_thumbnail image.original "350x350" crop="center" upscale=True as thumb %}
        <a href="{{ product.get_absolute_url }}">
            <img src="{{ thumb.url }}" alt="{{ product.get_title }}" class="card-img-top">
        </a>
        {% endwith %}
        <div class="card-body d-flex flex-column">
            <div class="card-title">
                <a href="{{ product.get_absolute_url }}" title="{{ product.get_title }}">{{ product.get_title|truncatewords:4 }}</a>
            </div>
            <div class="mt-auto">
                <div class="d-block">
                    {% purchase_info_for_product request product as session %}
                    {% if session.price.exists %}
                        {{ session.price.price|currency:session.price.currency }}
                    {% else %}
                </div>
            </div>
        </div>
    </div>
</div>
{% endfor %}

product_categories

Returns a list of product categories you can iterate over, see product_category.

Example Storefront Product Categories Query and Loop
{% where product_categories 'id' 'exact' 1 as homepage_categories %}
{% for category in homepage_categories  %}
<div class="col">
    <div class="card bg-light h-100">
        {% with image=category.image %}
        {% if image %}
        {% image_thumbnail image "350x350" crop="center" upscale=True as thumb %}
        <a href="{{ category.get_absolute_url }}">
            <img  src="{{ thumb.url }}" alt="{{ category.name }}" class="card-img-top">
        </a>
        {% endif %}
        {% endwith %}
        <div class="card-body">
            <h5 class="card-title">{{ category.name }}</h5>
            {{ category.description|safe }}
            <a href="{{ category.get_absolute_url }}" class="card-link">Shop now</a>
        </div>
    </div>
</div>
{% endfor %}

posts

Returns a list of blog posts you can iterate over, see post.

Example Storefront Recent Blog Posts Query and Loop
{% for post in posts|slice:"3" %}
<div class="col">
    <div class="card border-0 shadow-sm h-100  d-flex flex-column">
        {% with image=post.featured_image %}
            {% if image %}
            {% image_thumbnail image "400x250" upscale=False crop="top" as thumb %}
                <a href="{{post.get_absolute_url}}"><img src="{{ thumb.url }}" alt="{{ post.title }}" class="card-img-top"></a>
            {% endif %}
        {% endwith %}
        <div class="p-3">
            <div class="card-text text-muted fs-7">{{post.posted_date|date:"M d, Y"}}</div>
            <div class="card-title fs-5"><a href="{{post.get_absolute_url}}">{{ post.title }}</a></div>
            <div class="text-muted">{{ post.content|striptags|truncatechars_html:140  }}</div>
        </div>
    </div>
</div>
{% endfor %}

post_categories

Returns a list of post categories you can iterate over, see post_category.

Example Storefront Post Categories Query and Loop
<ul>
{% for cat in post_categories %}
    <li><a href="{{ cat.get_absolute_url }}">{{ cat.name }}</a></li>
{% endfor %}
</ul>

privacy_policy

Content from store Privacy Policy settings, typically used in a "Privacy Policy" page to automatically pull content in from settings.

Store policies are configured in the dashboard at Settings > Policies. The content entered there is automatically available as global template variables.

privacy_policy
{{ privacy_policy }}

request

The current session active request context.

Example Request Object Usage
<!DOCTYPE html>
<html lang="{{ request.LANGUAGE_CODE|default:'en' }}" class="{% block html_class %}{% endblock %}">

<head>
    <link rel="alternate" hreflang="{{ request.LANGUAGE_CODE }}" href="https://{{ request.get_host }}{{ request.path }}" />
</head>
PropertyTypeDescription
get_hostStringCurrent host domain.
pathStringCurrent url path.
COUNTRY_CODEStringCurrent active geo country code, see geo.
CURRENCY_CODEStringCurrent active currency code.
LANGUAGE_CODEStringCurrent active language code.

settings

Theme settings object with stored theme settings values as properties. See theme settings docs.

Example Colors Styles From Theme Settings
<style>
:root {
    --primary-color: {{ settings.theme_primary_color }};
    --accent-color: {{ settings.theme_accent_color }};
}
</style>

store

Returns the store object with general information about the store and the contact details.

Example Store Object Usage
<address>
{{ store.legal_name }}<br>
{{ store.address.line_1 }}<br>
{% if store.address.line_2 %}{{ store.address.line_2 }}<br>{% endif %}
{{ store.address.city }}, {{ store.address.state }} {{ store.address.postcode }}<br>
{{ store.address.country }}
</address>
<p><a href="mailto:{{ store.email }}">Email Support</a></p>
PropertyTypeDescription
addressobjectThe store address object see address.
brandingobjectThe store branding object, see branding.
nameStringGeneral name of the store defined in settings.
taglineStringStore tagline defined in settings.
legal_nameStringLegal name of the store.
phoneStringStore phone number.
emailStringStore email address.
timezoneStringStore timezone.
schemaStringStore schema, ie the store network subdomain.
get_meta_titleStringStore SEO meta title.
get_meta_descriptionStringStore SEO meta description.

storefront_geos

Returns a list of configured markets, see geos.

Example Storefront Geo Switcher
{% if storefront_geos and storefront_geos|length > 1 %}
<li class="nav-item dropdown">
    <a class="nav-link has-icon dropdown-toggle" id="langCurrencyDropdown" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">
        <span class="flag-icon flag-icon-{{ request.COUNTRY_CODE|lower }} me-2 me-md-0"></span>&nbsp;<span class="d-md-none">Language/Currency</span>
    </a>
    <ul class="dropdown-menu dropdown-menu-end" aria-labelledby="langCurrencyDropdown">

        <form action="{% url 'core:set-storefront' %}" method="post" id='set-storefront'>
            {% csrf_token %}
            <input name="country" type="hidden" value="" />
            <input name="language" type="hidden" value="" />
            <input name="currency" type="hidden" value="" />
            <input name="next" type="hidden" value="{{ language_neutral_url_path }}">
            {% for geo in storefront_geos %}
                <a class="dropdown-item" href="#" data-country="{{ geo.country.code }}" data-language="{{ geo.language }}" data-currency="{{ geo.currency.code }}">
                    <span class="flag-icon flag-icon-{{ geo.country.code|lower }}"></span>
                    &nbsp;&nbsp;
                    <span> {{ geo.country }}</span>
                </a>
            {% endfor %}
        </form>
    </ul>
</li>
{% endif %}

subscription_terms_and_conditions

Content from store subscription terms and conditions settings, typically used in a "Subscription Terms & Conditions" page to automatically pull content in from settings.

subscription_terms_and_conditions
{{ subscription_terms_and_conditions }}

terms_and_conditions

Content from store terms and conditions settings, typically used in a "Terms & Conditions" page to automatically pull content in from settings.

terms_and_conditions
{{ terms_and_conditions }}

Objects

Object have many properties that can be accessed in templates.

address

PropertyTypeDescription
line_1StringAddress line 1.
line_2StringAddress line 2.
cityStringAddress City.
stateStringAddress State.
postcodeStringAddress Postcode.
countryStringAddress Country.

branding

Store branding properties accessed through the store object to leverage within templates. Branding values are configured in the dashboard at Settings > Branding.

PropertyTypeDescription
logoFileStore branding logo, use .url to access the file link.
iconFileStore branding icon, use .url to access the file link.
primary_colorStringStore branding primary color, returns a HEX code.
accent_colorStringStore branding accent color, returns a HEX code.

currency

Currency object accessed through currencies.

PropertyTypeDescription
codeStringName of the currency, ie USD.
symbolStringThe symbol of the currency, ie $.

country

Country object to access properties about a country, see storefront_geos for example usage.

PropertyTypeDescription
codeStringTwo letter ISO 3166 country code.
nameStringFull name of the country.

geo

A geo is a combination of a language and currency typically associated with a market, see full example in storefront_geos.

PropertyTypeDescription
currencyobjectThe currency object, see currency.
countryobjectThe country object, see country
languageStringTwo letter ISO 639 language code.

image

Product images, see example usage below.

image
{% with all_images=product.get_all_images %}
{% for image in all_images %}{% image_thumbnail image.original "100x100" crop="center" as thumb %}
    <div id="{{ image.id }}">
        <img src="{{ thumb.url }}" alt="{{ product.get_title }}" class="img-fluid">
    </div>
    {% endfor %}
</div>
{% endif %}
{% endwith %}
PropertyTypeDescription
originalFileThe original image file, typically used when creating a thumbnail.
urlStringThe full CDN link to render the image.

items (menu)

A menu item has properties to support creating dynamic menus configured through the dashboard menu editor.

Example Dynamic Menu
{% for item in menus.header_menu.items %}
    {% if item.level > 0 %}
        <li class="nav-item dropdown">
            <a class="nav-link dropdown-toggle {% if item.child_active %}active{% endif %}" href="{{ item.url }}">{{ item.name|title }}</a>
            <ul class="dropdown-menu">
                {% for child_item in item.items %}
                    {% if child_item.level > 0 %}
                        <li>
                            <a class="dropdown-item dropdown-toggle {% if child_item.child_active %}active{% endif %}" href="{{ child_item.url }}">{{ child_item.name|title }}</a>
                            <ul class="dropdown-menu dropdown-submenu">
                                {% for grandchild_item in child_item.items %}
                                <li>
                                    <a class="dropdown-item {% if grandchild_item.current %}active{% endif %}" href="{{ grandchild_item.url }}">
                                    {{ grandchild_item.name|title }}
                                    </a>
                                </li>
                                {% endfor %}
                            </ul>
                        </li>
                    {% else %}
                        <li>
                            <a class="dropdown-item {% if child_item.current %}active{% endif %}" href="{{ child_item.url }}">
                                {{ child_item.name|title }}
                            </a>
                        </li>
                    {% endif %}
                {% endfor %}
            </ul>
        </li>
    {% else %}
        <li class="nav-item">
            <a class="nav-link {% if item.current %}active{% endif %}" href="{{ item.url }}">{{ item.name|title }}</a>
        </li>
    {% endif %}
{% endfor %}

Storefront Menus can be up to 3 levels, ensure your custom menu supports 2 nested menu item levels, see child and grandchild above.

PropertyTypeDescription
activeBooleanIndicates whether the link is currently active.
child_activeBooleanIndicates whether any child link of the current link is active.
child_currentBooleanIndicates whether the URL path matches the URL of a child link of the current link.
currentBooleanIndicates whether the current URL path matches the URL of the link.
itemsListContains the child items belonging to the current menu item.
levelIntegerSpecifies the hierarchical level of the current menu item.
nameStringRepresents the display name of the current menu item.
urlStringDenotes the URL path for the menu item's href link.

page

Storefront Page object details available in the pages/page.html template and custom page templates.

PropertyTypeDescription
titleStringPage title.
contentStringPage content.
get_meta_titleStringPage SEO meta title.
get_meta_descriptionStringPage SEO meta description.

paginator

The paginator object is available on "list views" where the items to display are paginated from the backend, works in tandem with page_obj.

paginator
{% if paginator.num_pages > 1 %}
<div class="my-3">
    <nav class="store_pagination" role="navigation" aria-label="store pagination">
        <ul class="pagination">
            {% with ''|center:paginator.num_pages as range %}
                {% for _ in range %}
                    <li class="page-item {% if forloop.counter == page_obj.number %}active{% endif %}" {% if forloop.counter == page_obj.number %}aria-current="page"{% endif %}><a class="page-link" href="?page={{ forloop.counter }}">{{ forloop.counter }}</a></li>
                {% endfor %}
            {% endwith %}
            {% if page_obj.has_next %}
            <li class="page-item"><a href="?page={{ page_obj.next_page_number }}" class="page-link">{% t "navigation.pagination.next" %}</a></li>
            {% endif %}
        </ul>
    </nav>
</div>
{% endif %}
PropertyTypeDescription
num_pagesIntegerNumber of pages in pagination set.

page_obj

The page_obj object is available on "list views" where the items to display are paginated from the backend, works in tandem with paginator.

PropertyTypeDescription
numberIntegerCurrent page number.
has_nextObjectNext page object.
has_previousObjectPrevious page.
next_page_numberIntegerNext page number.
previous_page_numberIntegerPrevious page number.

post

Blog post properties available through global post context and the blog/post.html and blog/index.html templates.

PropertyTypeDescription
idStringThe post ID.
featured_imageFileBlog post featured image file, use .url to access full file link.
categoriesListList of related post categories, use .all to return a list of categories, see post_category.
get_absolute_urlStringA full path link to the blog post.
titleStringThe post title.
contentStringPost content.
slugStringPost url slug.
get_meta_titleStringPost SEO meta title.
get_meta_descriptionStringPost SEO meta description.

post_category

Blog post category properties available through global post_categories context and the blog/post.html and blog/index.html templates.

PropertyTypeDescription
idStringBlog post category ID.
nameStringBlog post category name.
get_absolute_urlStringBlog post category canonical url link.

product

Product configured in the store catalogue.

PropertyTypeDescription
idStringProduct ID.
titleStringProduct title.
get_titleStringProduct title.
get_all_imagesListList of product images, see image.
get_descriptionStringProduct description.
skuStringProduct stock keeping unit (sku).
categoriesListList of product categories, use .all to return a list of categories, see product_category.
parentObjectParent product if product is variant (child).
is_childBooleanProduct structure indicating this is a variant product.
primary_imageFilePrimary image of the product, use .url to access a full file link.
get_absolute_urlStringProduct canonical url link.
num_approved_reviewsIntegerCount of approved product reviews.
ratingIntegerProduct rating as a number between 1 and 5.
reviewsIntegerList of product reviews, see review.
get_meta_titleStringProduct SEO meta title.
get_meta_descriptionStringProduct SEO meta description.

product_category

Product category object.

PropertyTypeDescription
idStringCategory ID.
nameStringCategory name.
descriptionStringCategory description.
imageFileCategory image, use .url to access image link.
get_absolute_urlStringCategory canonical url link.
get_meta_titleStringCategory SEO meta title.
get_meta_descriptionStringCategory SEO meta description.

price

Product price object.

PropertyTypeDescription
currencyStringPrice currency.
priceStringPrice that will be charged.
price_retailStringSuggested retail price.

review

Product review object.

PropertyTypeDescription
idStringReview ID.
titleStringReview title.
scoreIntegerReview score.
userObjectThe customer that created the review.

voucher

Voucher object.

PropertyTypeDescription
titleStringVoucher title.
codeStringVoucher code.

View-Specific Objects

View-specific objects are available in the templates rendered by their corresponding views. See Template Contexts below for which objects are available in each template.

session

The session object is returned by the purchase_info_for_product and purchase_info_for_line template tags. It contains pricing and availability information for a product in the current user's currency.

Example Product Price with Session
{% purchase_info_for_product request product as session %}
{% if session.price.exists %}
    {% if session.price.price_retail %}
        <span class="text-muted text-decoration-line-through">
            {{ session.price.price_retail|currency:session.price.currency }}
        </span>
    {% endif %}
    <span class="price">{{ session.price.price|currency:session.price.currency }}</span>
{% endif %}

{% if not session.availability.is_available_to_buy %}
    <span class="text-danger">Out of Stock</span>
{% endif %}

session.price

PropertyTypeDescription
existsBooleanWhether a price exists for this product.
priceDecimalThe current selling price.
price_retailDecimalThe retail/compare-at price, if set.
currencyStringThe currency code for this price.
excl_taxDecimalThe price excluding tax.

session.availability

PropertyTypeDescription
is_available_to_buyBooleanWhether the product can be purchased.

variant_form

The variant selection form object available on product detail pages (catalogue/product.html). Used to render variant attribute selectors (size, color, etc.) for products with variants.

Example Variant Selection
{% if variant_form %}
<div class="variant-options">
    {% for field in variant_form %}
        <div class="mb-3">
            <label>{{ field.label }}</label>
            {% render_field field class+="form-select" %}
        </div>
    {% endfor %}
</div>
{% endif %}

filters

The filters object is a list of product filter/facet objects available on category pages (catalogue/category.html). Filters allow customers to narrow product listings by attributes like price, color, size, etc. The has_active_filter boolean indicates whether any filter is currently applied.

There are three filter types: price_range, boolean, and list. Each type has different properties for rendering the appropriate UI.

Example Category Filters
{% if filters %}
<div class="filters">
    {% for filter in filters %}
    <div class="filter-group">
        <h6>{{ filter.label }}</h6>

        {% if filter.type == 'price_range' %}
            <input type="number" name="{{ filter.min_value.param_name }}" value="{{ filter.min_value.value }}" placeholder="{{ filter.min_value.label }}">
            <input type="number" name="{{ filter.max_value.param_name }}" value="{{ filter.max_value.value }}" placeholder="{{ filter.max_value.label }}">

        {% elif filter.type == 'boolean' %}
            <label>
                <input type="checkbox" name="{{ filter.true_value.param_name }}" {% if filter.true_value.active %}checked{% endif %}>
                Yes ({{ filter.true_value.count }})
            </label>

        {% else %}
            {% for value in filter.values %}
                <label>
                    <input type="checkbox" name="{{ value.param_name }}" {% if value.active %}checked{% endif %}>
                    {{ value.label }} ({{ value.count }})
                </label>
            {% endfor %}
        {% endif %}
    </div>
    {% endfor %}

    {% if has_active_filter %}
        {% for filter in filters %}
            {% for active in filter.active_values %}
                <a href="{{ active.url_to_remove }}">Remove {{ active }}</a>
            {% endfor %}
        {% endfor %}
    {% endif %}
</div>
{% endif %}

Common filter properties:

PropertyTypeDescription
typeStringFilter type: 'price_range', 'boolean', or 'list'.
labelStringDisplay label for the filter.
active_valuesListList of currently selected filter values.
url_to_removeStringURL to remove this active filter.

Price range filter properties:

PropertyTypeDescription
min_value.valueDecimalCurrent minimum price value.
min_value.param_nameStringQuery parameter name for the minimum.
min_value.labelStringDisplay label for the minimum input.
max_value.valueDecimalCurrent maximum price value.
max_value.param_nameStringQuery parameter name for the maximum.
max_value.labelStringDisplay label for the maximum input.
range_maxDecimalMaximum possible range value.

Boolean filter properties:

PropertyTypeDescription
true_value.param_nameStringQuery parameter name for true selection.
true_value.activeBooleanWhether true is currently selected.
true_value.countIntegerNumber of results matching true.
false_value.param_nameStringQuery parameter name for false selection.
false_value.activeBooleanWhether false is currently selected.
false_value.countIntegerNumber of results matching false.

List filter value properties:

PropertyTypeDescription
param_nameStringQuery parameter name for this value.
activeBooleanWhether this value is currently selected.
countIntegerNumber of results matching this value.
valueStringThe filter value.
labelStringDisplay label for this value.

Template Contexts

All templates receive the Global Objects (store, settings, currencies, languages_active_storefront, menus, products, product_categories, posts, post_categories, privacy_policy, terms_and_conditions, subscription_terms_and_conditions, request, storefront_geos). The table below lists additional view-specific context variables passed to each template.

TemplateView-Specific Context
templates/index.htmlGlobal objects only. Use the where tag to query products and categories.
templates/catalogue/product.htmlproduct, variant_form, interval_count_choices
templates/catalogue/index.htmlproducts (paginated), paginator, page_obj
templates/catalogue/category.htmlcategory, products (paginated), filters, has_active_filter, paginator, page_obj
templates/search.htmlquery, products (paginated), paginator, page_obj
templates/blog/index.htmlposts (paginated), paginator, page_obj
templates/blog/post.htmlpost
templates/pages/page.htmlpage
templates/support/index.htmlcategories
templates/support/category.htmlcategory, articles
templates/support/article.htmlarticle
templates/reviews/index.htmlproduct, reviews (paginated), paginator, page_obj
templates/reviews/form.htmlproduct, form
templates/reviews/review.htmlproduct, review

Use the purchase_info_for_product tag in any template to get pricing and availability for a product. Use cart_form on product pages to generate add-to-cart forms.

Cart and user data must use the Storefront GraphQL API. All storefront pages are fully cached per language and currency combination. Per-user data (cart contents, authentication state, wishlists) rendered in server-side templates would be cached and served to other visitors. Use client-side JavaScript with the GraphQL API for all cart and user interactions.

Dashboard Cross-Reference

Some template variables are populated from dashboard settings. Use this reference to understand where data originates when building or debugging templates.

Template VariableDashboard PathDescription
store.branding.logoSettings > BrandingStore logo image.
store.branding.iconSettings > BrandingStore icon/favicon image.
store.branding.primary_colorSettings > BrandingPrimary brand color (HEX).
store.branding.accent_colorSettings > BrandingAccent brand color (HEX).
store.name, store.taglineSettings > GeneralStore name and tagline.
store.legal_name, store.addressSettings > GeneralLegal details and address.
menus.{menu_key}.itemsStorefront > NavigationNavigation menu items (up to 3 levels).
privacy_policySettings > PoliciesPrivacy policy content.
terms_and_conditionsSettings > PoliciesTerms and conditions content.
subscription_terms_and_conditionsSettings > PoliciesSubscription T&C content.
settings.*Storefront > Themes > CustomizeTheme settings from settings_schema.json.

On this page