How Page Templates work in Gatsby


Page Templates in Agility CMS are how developers can differentiate the styles of certain types of pages, and define where on the page that editors can add Modules (functional components of the page that editors control).

Some sites may only have a single page template and this is re-used across the site, others may have other templates to allow for more flexible layouts.

Pages, Page Templates, Content Zones & Modules

Learn how pages are generated and rendered

What is in a Page Template?

When an editor creates a Page in the CMS, they must select which template to use.

A Page Template has a Name and Content Zones.

The Name should be a friendly representation of what the editor can expect from using the page template. For example, a site may have templates named One Column TemplateTwo Column Template, or Blog Template

Content Zone is an area defined in the CMS on the page template where an editor can add modules. A page template may have one or many Content Zones.

An Example

In the agility-gatsby-starter site, the Name of the Page Template is used to find a corresponding react component that matches the same name. If a match is found, that component is dynamically imported and rendered.

For example, if a Page Template has a reference name of OneColumnTemplate in the CMS, then while the page is being rendered by the gatsby-source-agilitycms plugin, it will look for ./src/pageTemplates/OneColumnTemplate.js in the ./src/pageTemplates directory.

Reviewing the example AgilityPage.js from our agility-gatsby-starter site, the <AgilityPageTemplate/> component will automatically take care of resolving and rendering the appropriate page template.


From AgilityPage.js:

import React from 'react'
import { graphql } from "gatsby"
import agilityUtils from './agility/utils'
import AgilityPageTemplate from './agility/components/AgilityPageTemplate'
//Some things we need for our layout
import LayoutTemplate from "./components/LayoutTemplate"
import PreviewBar from "./components/PreviewBar"
import GlobalHeader from './components/GlobalHeader'
import SEO from './components/SEO'

//Our query to get the our page data and check for a dynamic page item (agilityItem)
export const query = graphql`
  query($pageID: Int!, $contentID: Int!, $languageCode: String!) {
    agilitypage(languageCode: { eq: $languageCode }, itemID: { eq: $pageID }) {
    agilityitem(languageCode: {eq: $languageCode}, itemID: {eq: $contentID}) {
const AgilityPage = ({ pageContext, data }) => {
    const viewModel = agilityUtils.buildPageViewModel({ pageContext, data });
    return (
            <SEO title={} description={} />
            <PreviewBar isPreview={viewModel.isPreview} />
            <GlobalHeader />
            <main className="main">
                <AgilityPageTemplate {...viewModel} />
export default AgilityPage;

From OneColumnTemplate.js:

import React from 'react';
import ContentZone from '../agility/components/ContentZone'

const OneColumnTemplate = (props) => {
    return (
        <div className="one-column-template">
            <ContentZone name="MainContentZone" {...props} />
export default OneColumnTemplate;

How to Add a New Page Template

If you create a new page template in Agility CMS, then you'll need to create the corresponding React component for it within the ./src/pageTemplate directory.

If you don't have React component for your module, then nothing can be rendered for it in your Gatsby site.

How to Add a Content Zone

You can alter your content zones at any time, you'll simply have to utilize the <ContentZone /> component within your page template React component. This tells the gatsby build where to render the modules for this content zone in your code.

For example, this means that all modules in MainContentZone for a page are to be rendered here.

<ContentZone name="MainContentZone" {...props} />
2 out of 2 found this helpful



Please sign in to leave a comment.