Multiple page templates

Integrating your storefront with Headless CMS

Multiple page templates allow the creation of flexible layouts for Product Details and Product Listing Pages (PDPs and PLPs) in Headless CMS. This feature allows you to create and manage pages hierarchically, leveraging product information, user context, product type, brand specifications, and template hierarchy.

This document outlines the implementation details, usage instructions, and template hierarchy logic for integrating the templates into your FastStore project.

Before you begin

To benefit from this feature, follow the steps below:

Update your store’s @faststore/core package to the v3.0.17 by running the following command:


_10yarn add @faststore/core@3.0.17

Update the @faststore/cli package to the latest version, v.3.0.24:


_10yarn add -D @faststore/cli@3.0.24

Run yarn dev to apply the changes to your project.
After updating the @faststore/core, run the following command in your terminal to sync the changes from the Headless CMS:


_10faststore cms-sync

After the sync, you can start creating the templates.

Creating a multiple page template

To add multiple templates to your FastStore project, follow the steps below:

Go to the VTEX Admin and navigate to Storefront > Headless CMS.
Select your FastStore project.
Click Create Document and choose between Product Page and Product List Page.
Now that you have created the template, check the [Template hierarchy logic] section to learn how to use and edit the template.

Check the Managing pages in the Headless CMS guide to learn how to edit the name, publish, duplicate, or delete the template.

Template hierarchy logic

Both PDPs and PLPs use a similar logic for selecting the appropriate template to render. This logic prioritizes templates based on various criteria, starting with the most specific and moving to more generic templates, like department or generic PDP/PLP.

Here's the difference between Product Details and Product Listing Page template hierarchy:

Feature	PDP hierarchy logic	PLP hierarchy logic
Matching Criteria	Slug, Subcategory, Category, Department, Generic.	Slug (subcategory, category, department implied), Generic.
Reliance on Product Information	Considers product details (subcategory, category, department).	Ignores product details beyond the slug.

Product Details Page (PDP) template selection criteria

The template selection process follows a specific hierarchy, starting with the most specific template and progressing towards a generic one if no exact match is found.

FastStore checks for templates in the following order:

The system first searches for a template named after the product slug. For example, if the product slug is /blue-shirts/p, FastStore will look for a template named /blue-shirts/p.

If an SKU template is available, it takes precedence over the product template. For example, if a template is available for slugs containing the SKU ID (e.g., /blue-shirts-99988212/p), this template will take precedence over a more generic product template for /blue-shirts/p.
If no SKU template is available, the system searches for one template based on the product slug.
If no template matches the slug, FastStore searches for a template based on the product subcategory. For example, if the subcategory is summer clothing, the system might look for /clothing/shirts/summer-clothing/.
Following the subcategory, the system checks for a template matching the product category. For example, if the category is shirts, the system might look for /clothing/shirts/.
If no match is found at the category level, FastStore searches for a template based on the product department. For example, if the department is clothing, the system might look for /clothing/.
If none of the above criteria match, the generic Product Page template is used. This template has an empty Template section value in the settings.

${"base64":" ","img":{"width":2490,"height":1010,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":220218,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/pdplist___d6f00d8bcfc23aecc477c97d487eebca.png"}}$

Product Listing Page (PLP) template selection criteria

PLPs adhere to the following template selection logic:

FastStore prioritizes templates based on the slug information. This can include the combined department and category (department/category) or just the department (department).
If no slug match is found, the generic PLP template is used.

For example:

Slug: /office/chairs - matches department and category.
Department template: /office alternative for products within a department, ignoring category.
Generic PLP template: Used if no other matches are found.

Using Rewrites with PLP template

FastStore allows you to create custom routes using Next.js rewrites. It is possible to enable the multiple page template feature for the custom route as well by adding your rewrites function into the discovery.config.js file as suggested in the Next.js documentation:

Add your rewrite function to discovery.config.js:


_10async rewrites() {
_10  return [
_10    {
_10      source: '/my-office',
_10      destination: `/office`,
_10    },
_10  ]
_10},

This rewrites the URL /my-office to the existing route /office, effectively using the /office template without modifying the displayed URL. This allows you to map the template in the Headless CMS to the /office route.

Alternatively, use the extended format:


_12async rewrites() {
_12  return {
_12    beforeFiles: [
_12      {
_12        source: '/my-office',
_12        destination: `/office`,
_12      },
_12    ],
_12    afterFiles: [],
_12    fallback: [],
_12  }
_12},

This format offers more flexibility for advanced rewrite scenarios.

From version 3.0.61 of the @faststore/core package, it's also possible to use the source route in the Headless CMS to map the template. To update your store's @faststore/core package to the 3.0.61, run the following command:


_10yarn add @faststore/core@3.0.61

Main difference between PDP and PLP template selection criteria

To sum up, here's the difference between the two template hierarchies:

Feature	PDP Hierarchy logic	PLP Hierarchy logic
Matching Criteria	Slug, Subcategory, Category, Department, Generic.	Slug (subcategory, category, department implied), Generic.
Reliance on Product Information	Considers product details (subcategory, category, department).	Ignores product details beyond the slug.

Examples

In this section, we'll delve into different scenarios for selecting PDP and PLP templates.

PDP template selection example

For this example, we will explore three template scenarios to render in Headless CMS for the Apple Magic Mouse product:

Slug: Matches the product slug, e.g., /apple-magic-mouse/p. It offers the highest level of specificity.
Department: Applies to products within a specific department category, such as /technology/, if no slug template is defined.
Generic Product Page Template: Fallback template used if no other specific template matches.

Rendering within a slug

When using PDPs, this type of page template is recognized by the slug pattern. In the example, we will use the Apple Magic Mouse product page, which has the slug /apple-magic-mouse/p.

${"base64":" ","img":{"width":1956,"height":748,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":127265,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/pdpslug___95ada5a5b24e23e34c04f4837d11ade7.png"}}$

Adding the slug to this template makes it specific, prompting FastStore to prioritize it for rendering on the product page.

Rendering within a `department`

Products in catalog fall under a category tree, typically /department/category/subcategory/. For example, the product we’ve been using is in the Technology department, allowing you to create a department-specific template.

${"base64":" ","img":{"width":1952,"height":728,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":123617,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/pdpdepartment___387cf641f675d05666afeafc65a3e56b.png"}}$

If this product is under a subcategory, you can create a corresponding template. The category tree is used in the template input, separated by slashes.

${"base64":" ","img":{"width":2404,"height":740,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":144953,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/pdpsubcategory___566be1fd3bba2db777dd18881933292c.png"}}$

You can also see the category hierarchy through the breadcrumb.

${"base64":" ","img":{"width":2658,"height":1832,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":1378886,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/breadcrumb___c9c12da51f685572dfb3a9403168b26a.png"}}$

Rendering the generic Product Page template

If no matches are found for the slug or department, the generic template will be used to render the PDP. In this case, create a Headless CMS document with the Product Page option, leaving the Template field empty in the Sections tab.

${"base64":" ","img":{"width":2392,"height":788,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":121611,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/pdpgeneral___cdeeaf6060b529aea029e2e5814efc50.png"}}$

Product Listing Page (PLP) template selection example

For PLPs, we will go over the following possible templates:

Slug
Product Listing Page generic template.

When using PLPs, this type of page template is recognized by the slug pattern. In the example, we will use the office/chairs slug to render the PLP template.

Rendering within slugs

Products in the catalog are organized within a category tree, structured as /department/category/subcategory. If a slug template exists for any of these options, it will be rendered accordingly.

For example, if you want to render a specific template for products inside a department without considering the category or subcategory, you can create a Department template /office.

${"base64":" ","img":{"width":2078,"height":738,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":109256,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/plpdepartment___4c520237721ca14a722215a93e8cd4c7.png"}}$

If this product were under a subcategory, it would still be possible to create a template representing this scenario. The category tree is used in the template slug input, as in the image below.

${"base64":" ","img":{"width":2380,"height":698,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":124747,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/plpsubcategory___ac973acd0b5d1745e848f1a0a94c5988.png"}}$

Keep in mind that if a more specific template, such as /office/chairs, exists, it will take precedence when the slug matches the same pattern.

Rendering the generic Product Listing Page

If no matches are found for the slug, the generic template will be used to render the PLP. In this case, create a Headless CMS page with the Product List Page option, leaving the Template field empty in the Sections tab.

${"base64":" ","img":{"width":2030,"height":736,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":102881,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/plpgeneral___d5ecb7ef0a45bb0bfa6280ec719d9b80.png"}}$