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.
{% 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.
{% 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 %}menus
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.
{% 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.
{% 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.
{% 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.
{% 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.
<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 }}request
The current session active request context.
<!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>| Property | Type | Description |
|---|---|---|
get_host | String | Current host domain. |
path | String | Current url path. |
COUNTRY_CODE | String | Current active geo country code, see geo. |
CURRENCY_CODE | String | Current active currency code. |
LANGUAGE_CODE | String | Current active language code. |
settings
Theme settings object with stored theme settings values as properties. See theme settings docs.
<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.
<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>| Property | Type | Description |
|---|---|---|
address | object | The store address object see address. |
branding | object | The store branding object, see branding. |
name | String | General name of the store defined in settings. |
tagline | String | Store tagline defined in settings. |
legal_name | String | Legal name of the store. |
phone | String | Store phone number. |
email | String | Store email address. |
timezone | String | Store timezone. |
schema | String | Store schema, ie the store network subdomain. |
get_meta_title | String | Store SEO meta title. |
get_meta_description | String | Store SEO meta description. |
storefront_geos
Returns a list of configured markets, see geos.
{% 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> <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>
<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 }}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 }}Objects
Object have many properties that can be accessed in templates.
address
| Property | Type | Description |
|---|---|---|
line_1 | String | Address line 1. |
line_2 | String | Address line 2. |
city | String | Address City. |
state | String | Address State. |
postcode | String | Address Postcode. |
country | String | Address Country. |
branding
Store branding properties accessed through the store object to leverage within templates. Branding values are configured in the dashboard at Settings > Branding.
| Property | Type | Description |
|---|---|---|
logo | File | Store branding logo, use .url to access the file link. |
icon | File | Store branding icon, use .url to access the file link. |
primary_color | String | Store branding primary color, returns a HEX code. |
accent_color | String | Store branding accent color, returns a HEX code. |
currency
Currency object accessed through currencies.
| Property | Type | Description |
|---|---|---|
code | String | Name of the currency, ie USD. |
symbol | String | The symbol of the currency, ie $. |
country
Country object to access properties about a country, see storefront_geos for example usage.
| Property | Type | Description |
|---|---|---|
code | String | Two letter ISO 3166 country code. |
name | String | Full 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.
| Property | Type | Description |
|---|---|---|
currency | object | The currency object, see currency. |
country | object | The country object, see country |
language | String | Two letter ISO 639 language code. |
image
Product images, see example usage below.
{% 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 %}| Property | Type | Description |
|---|---|---|
original | File | The original image file, typically used when creating a thumbnail. |
url | String | The 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.
{% 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.
| Property | Type | Description |
|---|---|---|
active | Boolean | Indicates whether the link is currently active. |
child_active | Boolean | Indicates whether any child link of the current link is active. |
child_current | Boolean | Indicates whether the URL path matches the URL of a child link of the current link. |
current | Boolean | Indicates whether the current URL path matches the URL of the link. |
items | List | Contains the child items belonging to the current menu item. |
level | Integer | Specifies the hierarchical level of the current menu item. |
name | String | Represents the display name of the current menu item. |
url | String | Denotes 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.
| Property | Type | Description |
|---|---|---|
title | String | Page title. |
content | String | Page content. |
get_meta_title | String | Page SEO meta title. |
get_meta_description | String | Page 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.
{% 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 %}| Property | Type | Description |
|---|---|---|
num_pages | Integer | Number 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.
| Property | Type | Description |
|---|---|---|
number | Integer | Current page number. |
has_next | Object | Next page object. |
has_previous | Object | Previous page. |
next_page_number | Integer | Next page number. |
previous_page_number | Integer | Previous page number. |
post
Blog post properties available through global post context and the blog/post.html and blog/index.html templates.
| Property | Type | Description |
|---|---|---|
id | String | The post ID. |
featured_image | File | Blog post featured image file, use .url to access full file link. |
categories | List | List of related post categories, use .all to return a list of categories, see post_category. |
get_absolute_url | String | A full path link to the blog post. |
title | String | The post title. |
content | String | Post content. |
slug | String | Post url slug. |
get_meta_title | String | Post SEO meta title. |
get_meta_description | String | Post 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.
| Property | Type | Description |
|---|---|---|
id | String | Blog post category ID. |
name | String | Blog post category name. |
get_absolute_url | String | Blog post category canonical url link. |
product
Product configured in the store catalogue.
| Property | Type | Description |
|---|---|---|
id | String | Product ID. |
title | String | Product title. |
get_title | String | Product title. |
get_all_images | List | List of product images, see image. |
get_description | String | Product description. |
sku | String | Product stock keeping unit (sku). |
categories | List | List of product categories, use .all to return a list of categories, see product_category. |
parent | Object | Parent product if product is variant (child). |
is_child | Boolean | Product structure indicating this is a variant product. |
primary_image | File | Primary image of the product, use .url to access a full file link. |
get_absolute_url | String | Product canonical url link. |
num_approved_reviews | Integer | Count of approved product reviews. |
rating | Integer | Product rating as a number between 1 and 5. |
reviews | Integer | List of product reviews, see review. |
get_meta_title | String | Product SEO meta title. |
get_meta_description | String | Product SEO meta description. |
product_category
Product category object.
| Property | Type | Description |
|---|---|---|
id | String | Category ID. |
name | String | Category name. |
description | String | Category description. |
image | File | Category image, use .url to access image link. |
get_absolute_url | String | Category canonical url link. |
get_meta_title | String | Category SEO meta title. |
get_meta_description | String | Category SEO meta description. |
price
Product price object.
| Property | Type | Description |
|---|---|---|
currency | String | Price currency. |
price | String | Price that will be charged. |
price_retail | String | Suggested retail price. |
review
Product review object.
| Property | Type | Description |
|---|---|---|
id | String | Review ID. |
title | String | Review title. |
score | Integer | Review score. |
user | Object | The customer that created the review. |
voucher
Voucher object.
| Property | Type | Description |
|---|---|---|
title | String | Voucher title. |
code | String | Voucher 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.
{% 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
| Property | Type | Description |
|---|---|---|
exists | Boolean | Whether a price exists for this product. |
price | Decimal | The current selling price. |
price_retail | Decimal | The retail/compare-at price, if set. |
currency | String | The currency code for this price. |
excl_tax | Decimal | The price excluding tax. |
session.availability
| Property | Type | Description |
|---|---|---|
is_available_to_buy | Boolean | Whether 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.
{% 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.
{% 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:
| Property | Type | Description |
|---|---|---|
type | String | Filter type: 'price_range', 'boolean', or 'list'. |
label | String | Display label for the filter. |
active_values | List | List of currently selected filter values. |
url_to_remove | String | URL to remove this active filter. |
Price range filter properties:
| Property | Type | Description |
|---|---|---|
min_value.value | Decimal | Current minimum price value. |
min_value.param_name | String | Query parameter name for the minimum. |
min_value.label | String | Display label for the minimum input. |
max_value.value | Decimal | Current maximum price value. |
max_value.param_name | String | Query parameter name for the maximum. |
max_value.label | String | Display label for the maximum input. |
range_max | Decimal | Maximum possible range value. |
Boolean filter properties:
| Property | Type | Description |
|---|---|---|
true_value.param_name | String | Query parameter name for true selection. |
true_value.active | Boolean | Whether true is currently selected. |
true_value.count | Integer | Number of results matching true. |
false_value.param_name | String | Query parameter name for false selection. |
false_value.active | Boolean | Whether false is currently selected. |
false_value.count | Integer | Number of results matching false. |
List filter value properties:
| Property | Type | Description |
|---|---|---|
param_name | String | Query parameter name for this value. |
active | Boolean | Whether this value is currently selected. |
count | Integer | Number of results matching this value. |
value | String | The filter value. |
label | String | Display 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.
| Template | View-Specific Context |
|---|---|
templates/index.html | Global objects only. Use the where tag to query products and categories. |
templates/catalogue/product.html | product, variant_form, interval_count_choices |
templates/catalogue/index.html | products (paginated), paginator, page_obj |
templates/catalogue/category.html | category, products (paginated), filters, has_active_filter, paginator, page_obj |
templates/search.html | query, products (paginated), paginator, page_obj |
templates/blog/index.html | posts (paginated), paginator, page_obj |
templates/blog/post.html | post |
templates/pages/page.html | page |
templates/support/index.html | categories |
templates/support/category.html | category, articles |
templates/support/article.html | article |
templates/reviews/index.html | product, reviews (paginated), paginator, page_obj |
templates/reviews/form.html | product, form |
templates/reviews/review.html | product, 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 Variable | Dashboard Path | Description |
|---|---|---|
store.branding.logo | Settings > Branding | Store logo image. |
store.branding.icon | Settings > Branding | Store icon/favicon image. |
store.branding.primary_color | Settings > Branding | Primary brand color (HEX). |
store.branding.accent_color | Settings > Branding | Accent brand color (HEX). |
store.name, store.tagline | Settings > General | Store name and tagline. |
store.legal_name, store.address | Settings > General | Legal details and address. |
menus.{menu_key}.items | Storefront > Navigation | Navigation menu items (up to 3 levels). |
privacy_policy | Settings > Policies | Privacy policy content. |
terms_and_conditions | Settings > Policies | Terms and conditions content. |
subscription_terms_and_conditions | Settings > Policies | Subscription T&C content. |
settings.* | Storefront > Themes > Customize | Theme settings from settings_schema.json. |