Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 61 ยท Liquid Basics

The Global Objects You Use Most

Meet the Shopify Liquid objects you will use daily: shop, request, routes, settings, template, page_title, localization, customer, cart, content_for_header and layout, and where each is available.

So far you have printed values from objects such as product and cart without asking where they come from. In Shopify, every request fills a set of objects with the store's data and hands them to your Liquid code. Some objects are available almost everywhere (the shop's name, the cart), some exist only on certain pages (product on a product page), and two special ones exist only in the layout file.

Knowing which object is available where explains many early bugs: a product that prints nothing in the footer, a customer that is nil for visitors, a content_for_header that is missing and breaks apps. This lesson introduces the objects you will use most, in three groups: global objects, page-specific objects, and layout objects. The objects and properties here target current Online Store 2.0 themes; the Liquid reference lists every property, and you should check it for details such as the properties of customer.

The real objects exist only on Shopify's servers, so the theme snippets here are read-only. The runnable examples use mock data and a small resolver written in JavaScript. They show the idea of availability and layout assembly, but they are not Shopify's implementation, and the mock objects have far fewer properties than the real ones.

Three kinds of objects

flowchart TD
    G["Global objects<br/>shop, request, routes, settings,<br/>template, localization, customer, cart"] --> ANY["Available in layouts, templates<br/>and sections"]
    P["Page objects<br/>product, collection, article,<br/>blog, page, search"] --> PAGE["Available on the matching template<br/>and its sections"]
    L["Layout objects<br/>content_for_header,<br/>content_for_layout"] --> LAY["Only in layout files,<br/>such as theme.liquid"]
    S["Scoped objects<br/>section, block, forloop, paginate"] --> SC["Only inside the file or tag<br/>that creates them"]

Where an object exists depends on the kind of object it is.

Snippets are special. A snippet you pull in with the render tag starts with an empty scope (as you will see in Snippets and the render Tag), so the safe habit is to pass in every object a snippet needs, for example {% render 'product-card', product: product %}.

shop: the store itself

shop describes the store: shop.name, shop.url, shop.description, shop.email, shop.currency and shop.address, plus store-level metafields. Use it for the header logo's alt text, structured data, and the copyright line.

LIQUID
<a href="{{ routes.root_url }}">{{ shop.name }}</a>
<small>&copy; {{ 'now' | date: '%Y' }} {{ shop.name }}</small>

request: facts about this page view

request carries details of the current request. The ones you will reach for are:

  • request.design_mode: true inside the theme editor, false for real visitors. Use it to show helpful placeholders for merchants.
  • request.page_type: a string such as product, collection, cart or index.
  • request.path and request.host: the URL path and the domain.
  • request.locale: the language of this request.
LIQUID
{% if request.design_mode and section.blocks.size == 0 %}
  <p class="editor-hint">Add a block to get started.</p>
{% endif %}

routes: URLs that never break

routes holds the URL for the store's built-in pages: routes.root_url, routes.cart_url, routes.search_url, routes.account_login_url, routes.account_register_url, routes.account_url, routes.collections_url and the Ajax cart endpoints like routes.cart_add_url. Stores can live under a market or language prefix (/fr/cart), so never hard-code /cart:

LIQUID
<a href="{{ routes.cart_url }}">Cart ({{ cart.item_count }})</a>
<form action="{{ routes.search_url }}" method="get">โ€ฆ</form>

settings: global theme settings

settings returns the values from the theme settings that merchants edit under Theme settings (config/settings_schema.json defines them, config/settings_data.json stores them). For example settings.accent_color or settings.show_announcement. Section-level settings are different: they live on section.settings and block.settings. Both are covered in Global Theme Settings.

template and page_title

  • template tells you which template renders the page: template.name is product, collection, index, cart and so on, template.suffix is the alternate name (for product.landing, the suffix is landing), and template.directory is the folder for customer templates. Prefer template.name to older string tricks such as template contains 'product'.
  • page_title is the text for the page's <title>, already assembled by Shopify from the product, collection or page. Print it inside <title> in the layout. Related: page_description, canonical_url and request.page_type help with metadata (see SEO in Themes).

localization

localization knows the visitor's language and country (market): localization.language.iso_code, localization.language.endonym_name, localization.country.iso_code, localization.country.currency.iso_code, and lists such as localization.available_languages and localization.available_countries. Language and country selectors are built from them, and the layout uses it for the lang attribute. See Translations, Markets and Localization.

customer

customer is nil for visitors who are not signed in, so {% if customer %} is the standard login check. When someone is signed in, you can read fields such as customer.first_name, customer.email, and (on classic account pages) customer.orders and customer.addresses. Which properties are filled depends on the store's account system, so check the current documentation before relying on a field. See Customer Accounts and Account Pages.

cart

cart is the visitor's current cart, available on every page: cart.item_count, cart.items, cart.total_price (in cents), cart.note, cart.attributes and so on. The cart is updated without a page reload by JavaScript, so code that reads it in Liquid is correct only at the moment the page was rendered. Real-time updates come from the Ajax Cart API (see The Ajax Cart API).

Try it: which object exists where?

The stand-in below holds mock data for four page contexts and resolves a list of expressions against each one. Notice that product.title is nil everywhere except the product page, that customer.first_name appears only for the signed-in context, and that request.design_mode flips in the theme editor. Change the mock data or add expressions and run it again.

JS Which objects exist on which page?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What is real and what is not? The rule that product exists only on product pages, that customer is nil for guests and that request.design_mode is true only in the editor mirrors Shopify. The data, the resolver and the table are made up for this lesson.

content_for_header and content_for_layout

Two objects exist only in layout files such as layout/theme.liquid, and every layout must output both:

  • {{ content_for_header }} goes inside <head>. Shopify and installed apps use it to inject scripts and styles (analytics, the theme editor's tooling, app embeds). Never remove it, edit its output or try to parse it: apps and the editor stop working without it.
  • {{ content_for_layout }} goes inside <body>. It is the already-rendered HTML of the current template and its sections. This is why the template renders first, and the layout wraps it afterwards. Layouts are the topic of Layouts and theme.liquid.
JS Assembling a page from template and layout

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The stand-in does the same two steps with string replacement: first the template, then the layout. The injected scripts in the head are invented; real content_for_header content is generated by Shopify and changes between requests.

Quick reference

Object Where Typical use
shop everywhere store name, URL, currency
request everywhere design_mode, page_type, path
routes everywhere links to cart, search, account
settings everywhere global theme settings
template everywhere which template is rendering
page_title pages the <title> text
localization everywhere language, country, currency
customer storefront pages login check, greeting
cart storefront pages item count, totals
product, collection, ... matching templates page content
section, block inside sections section and block settings
content_for_header, content_for_layout layout files only required outputs

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A visitor is not signed in. What is the value of customer?

    customer is nil for visitors who are not signed in, which is why {% if customer %} works as a login check.
  2. 2. Why should you output routes.cart_url instead of writing /cart?

    Stores can serve pages under prefixes such as /fr. The routes object always returns the correct URL for the current context.
  3. 3. Where must content_for_header be output?

    content_for_header carries the scripts and styles that Shopify and apps inject. It belongs in the head of theme.liquid, and removing it breaks apps and the theme editor.
  4. 4. Which value tells your code it is running inside the theme editor?

    request.design_mode is true in the theme editor. It is a good place to show a placeholder for merchants.

Summary

  • Global objects (shop, request, routes, settings, template, localization, customer, cart) are available on most pages; page objects such as product exist only on their template; section and block only inside sections.
  • Use routes for built-in URLs, request.design_mode for editor-only hints, and {% if customer %} for the login check.
  • content_for_header (in the head) and content_for_layout (in the body) are required in every layout and exist only there.
  • The template renders first and its HTML becomes content_for_layout.
  • Pass the objects a snippet needs explicitly when you render it.

Next: Snippets and the render Tag