Note
Sourcing content from Gatsby with Agility CMS uses the gatsby-source-agilitycms plugin, however for an example of how this works in a real website, see the agility-gatsby-starter.Using the gatsby-source-agilitycms plugin will mean that all of your content, modules, sitemaps, and pages will be synchronized with your Gatsby site and available via GraphQL.
In this guide, we'll cover:
Configuring the Plugin
The plugin is registered in the gatsby-config.js file in your Gatsby site along with several configurable options that influence the behaviour of the plugin.
require("dotenv").config({
path: `.env.${process.env.NODE_ENV}`,
})
//configure your agility plugin with environment variables so that
//your agility api credentials stay secure
const agilityConfig = {
guid: process.env.AGILITY_GUID,
apiKey: process.env.AGILITY_API_KEY,
isPreview: process.env.AGILITY_API_ISPREVIEW
}
module.exports = {
plugins: [
{
//the name of the plugin
resolve: "@agility/gatsby-source-agilitycms",
//the options for our plugin
options: {
//your Agility Content Fetch API Guid
guid: agilityConfig.guid,
//your Agility Content Fetch API Key
apiKey: agilityConfig.apiKey,
//set this to true if you are using the preview API Key
isPreview: agilityConfig.isPreview,
//set this to true to see expanded traces in the build logs
debug: false,
//the languages you want to source content for
languages: [{
// The name of the language code
name: "English",
// The actual language code set in Agility CMS
code: "en-us",
// The name to be used in the URL path that represents the current language
path: "en"
}],
// The channels you want to include
channels: [{
// The reference name for the website channel as it is defined in Agility CMS
referenceName: "website"
}],
//the page template that will be used to render Agility CMS pages
masterPageTemplate: "./src/AgilityPage.js"
}
...
]...}
How Sourcing Content Works
The source plugin uses the @agility/content-sync npm package which ensures that only content that has changed is updated. It keeps things in-sync for you.
This means your first build will download all of your content, while subsequent builds only update what has changed. This enables incremental builds and results in bleeding-edge, fast build times.
Need to Resync?
If you want to force a full-resync (clears all cached/sourced content), you can run:
gatsby clean
The next time you run gatsby develop or gatsby build it will source and download all of your content again.
Accessing your Content
All of your content is downloaded and stored in the Gatsby GraphQL. You can explore all of the content in your GraphQL and auto-generate queries for you to use in your Gatsby site.
When running your site locally using gatsby develop, you can view the GraphQL Playground by navigating to http://localhost:8000/___graphql.
Rebuild to update Content
In order for content from the CMS to be refreshed, you need to re-build the site. You can do this locally by re-running gatsby develop
Querying Content
Content
To query content from Agility CMS, you would query allAgility<contentTypeName>, for example, allAgilityPost, then select what fields you want to retrieve for each item.
query MyPosts {
allAgilityPost {
nodes {
customFields {
details
title
image {
url
}
}
}
}
}
Modules
To query modules on pages from Agility CMS, you would query allAgility<moduleTypeName>, for example, allRichTextArea, then select what fields you want to retrieve for each item.
query MyRichTextAreaQuery {
allAgilityRichTextArea {
nodes {
customFields {
textblob
}
}
}
}
Pages
To query a page from Agility CMS, you would query allAgilitypage.
Note
Pages store information pertaining to which modules and their fields are on the page, so due to the dynamic nature of this data, there is only a single pageJson property that contains the page fields serialized into a string.
You can easily convert this into an object within the Gatsby site and pass each module's fields as props to your react components responsible for rendering each module. This is exactly how the agility-gatsby-starter site is configured.
query MyPageQuery {
allAgilitypage {
nodes {
pageJson
languageCode
itemID
}
}
}
Sitemap
To query a sitemap from Agility CMS, you would query allAgilitySitemapNode.
query MySitemapQuery {
allAgilitySitemapNode {
nodes {
name
pageID
path
languageCode
isFolder
contentID
}
}
}
Comments
Please sign in to leave a comment.