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:
- an Oracle Content Management subscription
- an Oracle Content Management account with the Content Administrator role
- the completed tutorial to build a minimal site in Gatsby
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:
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:
The People asset is of type PeoplePage, and it contains subtypes of people. This is what it looks like:
This is what an example people asset looks like (note all the metadata in the Attributes panel):
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
.
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.
Use GraphQL with Gatsby and Oracle Content Management
F49443-01
December 2021
Copyright © 2021, Oracle and/or its affiliates.
Primary Author: Oracle Corporation