StorefrontStencilThemesPage Context

Front Matter Reference

Front matter defines which store resources are available to be rendered within a Stencil template. Front matter is declared at the top of each template and uses YAML syntax. For more information, see Declaring Front Matter Objects.

Supported templates

You can use YAML front matter for templates in the templates/pages/ directory. Injecting objects in the front matter of templates/pages/page.html will make the objects available to custom templates. Also, you can add front matter in the custom folder (i.e., templates/pages/custom).

You cannot use front matter for templates in the following directories:

  • templates/components/
  • templates/layout/

Global attributes

Global attributes are available on all pages.

customer:                         
  returns: true                     # show product return requests for this customer
  wishlists:     
    limit: 10                       # limit the number of wishlists to 10
  orders:
    limit: 10                       # limit the number of orders displayed to 10
  recently_viewed_products: true    # display recently viewed products
PropertyDescription
customerCustomer attributes are always included and are available when an active shopper logs in.
returnsBoolean indicating whether to retrieve product return requests for this customer. No filtering available.true: Retrieve requests. null or false: Do not retrieve requests.
wishlistsIf null, wishlists are displayed. If limit is not specified, it retrieves every wishlist.
ordersIf null, no orders are displayed. Displays complete and incomplete orders. If limit is not specified, it displays 20 orders.
recently_viewed_productsBoolean indicating whether to display recently viewed products. No filtering available.
limitThe maximum number of the entity to display.
products:
  featured:
    limit: 5   #limits the number of featured products to 5
  new:
    limit: 5   #limits the number of new products to 5
  top_sellers: 
    limit: 5   # limits the number of top sellers to 5
PropertyDescription
productsWhen filtering/limiting, products’ default sorting is by order id, from lowest to highest.
featurednull: No featured products displayed. If not set, defaults to 4 products.
newnull: No new products displayed. The maximum allowable value is 25. If not defined, defaults to 8 products.
top_sellersnull: No top-selling products displayed. If not defined, defaults to all top sellers.
carousel: true    # displays carousel on the storefront unless set to null
PropertyDescription
carouselBoolean indicating whether to display a carousel on a storefront. No filtering available.
blog:	
  recent_posts:
    limit: 5    # limits recent blog posts to 5
    summary: 100  # displays 100 character summary of blog post
PropertyDescription
blogDefault sorting is by published_date, from most recent to earliest. This sorting does not work on the blog page. See Blog Attributes.
recent_postsnull: No recent blog posts displayed. If not defined, defaults to the maximum of 20 blog posts.
summarySets the number of characters to display in each blog post summary. If not defined, it displays 100 characters.
cart: true    # show cart data
PropertyDescription
cartBoolean indicating whether to retrieve cart data. false: Do not return cart data.
categories: true      # displays category tree
  description: true   # displays category description
PropertyDescription
categoriesBoolean indicating whether to retrieve the category tree during an AJAX request. false: Do not retrieve the category tree.
descriptionBoolean indicating whether to retrieve category descriptions dynamically from the database. Set to true for themes that must display category descriptions when pages render.
shop_by_brand: true   # displays brand list
  limit: 10           # limits brands to 10
PropertyDescription
shop_by_brandTypically used in a footer or sidebar. null: Do not display this brand list. If not defined, it returns 10 brands, ordered by the number of products per brand.

Category attributes

Category attributes are available in the context of a category.

category:	
  shop_by_price: true   # displays shop by price controls
  products:
    limit:  10          # limits products per page for this category to 10
PropertyDescription
shop_by_priceBoolean indicating whether to display Shop-by-Price controls.
productsDefines the number of products displayed per page for this category. The range of possible values is 1–100 products.

Blog attributes

Blog attributes are available in the context of a blog.

blog: 
  posts:
    limit: 10        # limits number of blog posts to 10
    pages: 5        # displays 5 pages in pagination links
    summary: 250    # displays 250 character summary of blog post
PropertyDescription
postsDefault sorting is by published_date, from most recent to earliest.
limitnull: No blog posts displayed. The maximum is 20 blog posts per page.
pagesnull: No pagination. If not defined, defaults to five pages.
summarysets the number of characters to display in each blog-post summary. If not defined, it displays 250 characters.

Product attributes

Product attributes are available in the context of a product.

product:
  videos:
    limit: 5           # limits videos to 5
  images:
    limit: 5           # limits images to 5
  reviews:
    limit: 250         # limits reviews to 250
  related_products:
    limit: 10          # limits related products by name to 10
  similar_by_views:
      limit: 10        # limits similar products by views to 10

Note: The similar_by_views property is not currently active.

PropertyDescription
productWhen filtering/limiting, products’ default sorting is by order id, from lowest to highest.
videosIf product.videos is not defined, you will not return videos. If you define product.videos, the default behavior is to return all videos. If you define product.videos.limit, this sets the maximum number of videos returned.
imagesIf product.images is not defined, you will not return images. If product.images is defined, you must also define product.images.limit, which throttles the number of images returned. The maximum allowable value for this parameter is five images.
reviewsBoolean indicating whether to display product reviews. If product.reviews is present and is not explicitly set to false, reviews will appear. If not defined, defaults to 10 reviews. When filtering/limiting reviews, the default sorting is by review id, from lowest to highest. If a product has over 250 reviews, you can fetch the rest using the GraphQL Storefront API. See the example GraphQL query below.
related_productsDisplays products that are related by name. If limit absent or undefined, the default behavior is to display all related products. Inserting limit with no integer will display 0 products.
similar_by_viewsDisplays products similar to those displayed in the current page context. If limit absent or undefined, the default is to display four products. Currently disabled on the platform.

Sample GraphQL query for product reviews over the limit.

# Fetch product reviews for a product
query reviewsByProductId(
  $productId: Int!
  $cursor: String
  # Use GraphQL Query Variables to inject your product ID
) {
  site {
    product(entityId: $productId) {
      reviews(first:250, after:$cursor) {
        pageInfo {
          endCursor
          hasNextPage
        }
        edges {
          node {
            rating
            title
            text
            createdAt {
              utc
              }
            }
          }
        }
      }
    }
  }

Brand attributes

brand:
  products:
    limit: 50   # limits products displayed for this brand to 50
PropertyDescription
productslimit defines the number of products displayed per page for this brand. The range of possible values is 1–50 products.

Brand list attributes

brands:
  limit: 50   # limits number of brands displayed in the list to 50
PropertyDescription
brandsWhen retrieving a collection of brands, the default sorting is by brand id, from lowest to highest. limit sets the number of brands displayed in the list. If limit is not defined, returns all brands, up to a maximum of 50.

Search attributes

search: 
  product_results:
    limit: 16   # limits product results to 16
PropertyDescription
product_resultslimit defines the number of product search results displayed per page. The range of possible values is 1–100 products.

GraphQL attributes

You can add GraphQL Storefront API queries to your theme using the front matter block in a template file. For example, you can request a product’s variants by augmenting the existing product.html template:

1product:
2 videos:
3     limit: {{theme_settings.productpage_videos_count}}
4 reviews:
5     limit: {{theme_settings.productpage_reviews_count}}
6 related_products:
7     limit: {{theme_settings.productpage_related_products_count}}
8 similar_by_views:
9     limit: {{theme_settings.productpage_similar_by_views_count}}
10gql: "query productById($productId: Int!) {
11 site {
12   product(entityId: $productId) {
13     variants(first: 25) {
14       edges {
15         node {
16           sku
17           defaultImage {
18             url(width: 1000)
19           }
20         }
21       }
22     }
23   }
24 }
25}"

Note: The similar_by_views property is not currently active.

We suggest testing GraphQL Storefront API queries using the playground to refine them before adding them to your template. If your query contains double quotes ", add the escape character to the double-quotes \". You can launch the playground from your store by going to Settings > API > Storefront API Playground in your store control panel.

Once you have added a query to your template’s front matter block, execution happens automatically when the page loads. The data returned by the query will be returned in the page’s context and made available to the handlebars under the gql key. For example, you can retrieve the variant data from the above query in product.html like this:

{{#if gql.data.site.product}}
{{#each gql.data.site.product.variants.edges}}
  {{#with node}}
    {{sku}} {{! - - sku code from each variant from GQL response}}
  {{/with}}
{{/each}}
{{/if}}

If the GraphQL query is invalid, Stencil returns an errors object with locations and message properties similar to the following example:

{
  "gql": {
    "errors": [
      {
        "locations": [
          {
            "column": 1,
            "line": 1
          }
        ],
        "message": "Syntax error while parsing GraphQL query."
      }
    ]
  }
}

On some pages, you can inject special variables into your query to fetch data relevant to that page. For example, using the $productId variable on product pages injects the product ID associated with the current page.

The following is the complete list of available variables:

  • category.html: $categoryId
  • product.html: $productId
  • brand.html: $brandId
  • page.html: $pageId
  • contact-us.html: $pageId
  • blog-post.html: $blogPostId

You can also query data without using variables. The following query returns the product category tree as a JSON object:

gql: "query CategoryTree3LevelsDeep {
  site {
    categoryTree {
      ...CategoryFields
      children {
        ...CategoryFields
        children {
          ...CategoryFields
        }
      }
    }
  }
}
fragment CategoryFields on CategoryTreeItem {
  name
  path
  entityId
}"

The example query returns the following JSON object:

{
  "data": {
    "site": {
      "categoryTree": [
        {
          "name": "Apparel",
          "path": "/apparel/",
          "entityId": 25,
          "children": [
            {
              "name": "Shirts",
              "path": "/apparel/shirts/",
              "entityId": 27,
              "children": []
            },
            {
              "name": "Hoodies",
              "path": "/hoodies/",
              "entityId": 28,
              "children": []
            },
            {
              "name": "Caps",
              "path": "/caps/",
              "entityId": 29,
              "children": []
            }
          ]
        }
      ]
    }
  }
}