Use GraphQL with Gatsby and Oracle Content Management

Introduction

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.

In this tutorial, we’ll show how to use GraphQL with Gatsby connected to Oracle Content Management. In particular, we’ll focus on the existing ‘People’ page on the Gatsby minimal sample site by querying the necessary data using GraphQL connected with the Gatsby Source GraphQL plugin. The other pages (‘Home’ and ‘Contact Us’) are currently using a REST API connected with the Gatsby Source OCE plugin.

Prerequisites

Before proceeding with this tutorial, we recommend that you read the following information first:

To follow this tutorial, you’ll need:

What We’re Building

With the minimal site built in Gatsby, you can easily retrieve images and other content from your Oracle Content Management repository.

To take a look at what we’re building, here’s the end state of our tutorial, a basic Gatsby minimal site that consumes content from Oracle Content Management:

https://headless.mycontentdemo.com/samples/oce-gatsby-minimal-sample

This tutorial will focus solely on the ‘People’ page of this site.

This is what the People page will look like at the end of this tutorial:

This image shows the contact us page for an Gatsby minimal site.

To proceed, you’ll need to have an active subscription to Oracle Content Management and be logged in with the Content Administrator role.

Task 1: Understand the People Page Taxonomy

The downloadable asset pack contains an asset called Minimal Main GraphQL with the slug ‘minimalmaingraphql’.

The Minimal Main GraphQL asset contains a page of type PeoplePage called People. This is what it looks like:

This image shows the Minimal Main GraphQL taxonomy.

The People asset is of type PeoplePage, and it contains subtypes of people. This is what it looks like:

This image shows the People page taxonomy.

This is what an example people asset looks like (note all the metadata in the Attributes panel):

This image shows the people taxonomy.

Task 2: Connect to the Gatsby Source GraphQL plugin

To query these assets from Oracle Content Management, we need to configure the Gatsby Source GraphQL plugin in the gatsby-config.js file. This plugin should be added to the dependencies in the package.json file.

The following is the code for that configuration in gatsby-config.js.

    {
          resolve: 'gatsby-source-graphql',
          options: {
            // This type will contain remote schema Query type
            typeName: 'OCM',
            // This is the field under which it's accessible
            fieldName: 'ocm',
            // URL to query from
            url: `${process.env.SERVER_URL}/content/published/api/v1.1/graphql`,
          },
        },

The endpoint for the GraphQL API is the server URL concatenated with /content/published/api/v1.1/graphql.

Note that the typeName and fieldName are used to contain the remote schema query type and the field under which it’s accessible, respectively. The naming here isn’t too important as long as it’s consistent in the query.

Task 3: Run and Process the GraphQL query

The following is a section from the gatsby-node.js file. It routes the page with slug ‘people’ to the proper path with component and context using the createPage method in Gatsby. Notice how we pass in the page data, slug, and channelToken in the context.

} else if (page.slug.localeCompare('people') === 0) {
        createPage({
            path: '/people',
            component: peopleTemplate,
            context: {
                page,
                slug: 'people',
                channelToken: process.env.CHANNEL_TOKEN,
            },
        });

After being routed to the People page template, the following query is run to obtain all the data for the People page. A slug and channelToken are needed to access the GraphQL API for this page.

More information about how to query data using Oracle Content Management can be found in the documentation.

query ($slug: String!, $channelToken: String!) { 
      ocm {
        getPeoplePage(
          slug: $slug
          channelToken: $channelToken
        ) {
          id
          slug
          name
          fields {
            announcement {
              id
              fields {
                type: fieldType
                heading
                body
                actions
                image {
                  ... on OCM_image {
                    id
                    name
                    fields {
                      renditions {
                        file {
                          url
                        }
                      }
                    }
                  }
                }
              }
            }
            people {
              id
              fields {
                fullname
                title
                biodata
                file {
                  metadata {
                    width
                    height
                  }
                }
                renditions {
                  name
                  format
                  file {
                    url
                    metadata {
                      height
                      width
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

Notice how the top-level query has ocm in it and the typeName on the image is OCM_Image. This must be consistent with the typeName and fieldName associated with the options provided in gatsby-config.js.

The returned result is then processed to create the HTML to display the People page. To see the output of the query, you can go to the GraphQL explorer, which can be found at http://localhost:8000/___graphql after calling npm run develop on the terminal. Also, the GraphQL IDE is available at http://your_instance/content/published/api/v1.1/graphql/explorer.

This image shows the explorer.

Conclusion

In this tutorial, we added a ‘People’ page to the Gatsby minimal sample site using GraphQL to obtain the data for that page. The data obtained from GraphQL with Gatsby was connected to Oracle Content Management using the Gatsby Source GraphQL plugin. The other pages (‘Home’ and ‘Contact Us’) still use the REST API connected with the Gatsby Source OCE plugin. Both the Gatsby Source OCE plugin and the Gatsby Source GraphQL plugin are valid ways to obtain data from Oracle Content Management.

Additional information on GraphQL in Oracle Content Management can be found in the documentation.