Sourcing and Querying Content in Gatsby

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:

1. Configuring the Plugin
2. How does Sourcing Content Work
3. Querying Content

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 === "true"
}
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.jsx"
      }
...
]...}

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.

gatsby clean

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.

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
        }
      }
    }
  }
}

Page 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.

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
    }
  }
}