GatsbyJS

GatsbyJS + Drupal: Create Content Type Landing Pages

jflynn — Sun, 01 Dec 2019 22:30:00 +0000

GatsbyJS + Drupal: Create Content Type Landing Pages jflynn Sun, 12/01/2019 - 16:30

At NEDCamp I had the pleasure of seeing many wonderful people and sessions, but, as you may know, my favorite track at most events is the "Hallway Track". If you're not familiar, the Hallway Track is the time in-between sessions where some real magic happens. You have a chance to talk with some of the most amazing minds in the world about topics you're passionate about. You can share knowledge, bounce ideas, have epiphanies, and realize that your current problems (code-wise) are things that other people have run into. One such conversation happened that inspired me to think outside the box to solve a problem.

In my last post we went over how to create a related content section with references to entities that may have empty fields. Today, we're going to take that one step further and create landing pages for content types.

In Drupal, we would ordinarily build these by attaching a view to a content type based on contextual filters or similar in order to get a collection of all content of that content type. Since we don't have Views in GatsbyJS, we need another solution. There are a couple of options out there, including the recently released JSON:API Cross Bundles module, compliments of Centarro and Matt Glaman. However, at the time of this writing there is an issue with the JSON:API Cross Bundles conflicting with JSON:API Extras. So, if you're relying on JSON:API Extras, you'll need another solution.

The problem:

Out of the box, JSON:API does not create a route to retrieve all nodes with any ease. However, there's no need to fear. This post is here!

Now if you're not using JSON:API Extras, I strongly recommend looking into JSON:API Cross Bundles. It creates a route to all content and will simplify your life. If you are using JSON:API Extras, have I got something for you.

Let's dive in.

Scenario:

You're building a decoupled Drupal site and you want to have a reusable template for landing pages that display all content of a content type. This is easy enough to do in Drupal using Views, but we lose Views when going decoupled so we need another way. How do we accomplish this in a decoupled application using GatsbyJS as the front-end?

Solution:

Strap in folks, this one gets a little bumpy.

Drupal side:

We need to do some work on both sides of the application for this to work. First, we will setup a content type in Drupal to use for our Content Landing Pages. This is kind of a choose your own adventure scenario, but one thing that you absolutely must have is an Entity Reference field that references the Config Entity: Content Type with a cardinality of 1.

Select this field type:

And this is the entity type to reference:

Now that we have our field created, select any content type that will require a content landing page as an available option.

Whatever else you want to put on this page is up to you. Go wild. Want a hero image? Add a hero image. Want a dancing baby gif? That's your choice and I respect it. Once you've finished making the greatest landing page content type ever™ we can move on to the fun part in GatsbyJS.

GatsbyJS side:

JSON:API gives us something that can help us out a bit. It goes by the name allNodeTypeNodeType and it will let us workaround the lack of a base all-content route. If we explore this in GraphiQL we'll see that we can drill down a bit and get exactly what we need.

{
  allNodeTypeNodeType {
    nodes {
      relationships {
        node__article
        node__landing_page
        node__basic_page
      }
    }
  }
}

NOTE: I didn't drill down too far, but all fields are available here.

Let's first create our landing page template in Gatsby.

First, let's just create a simple, empty component for our Landing Page with a basic graphql query.

// src/components/templates/LandingPage/index.js
import React from 'react'
import { graphql } from 'gatsby'

function LandingPage({ data }) {
  return (
    <div>
      
    </div>
  )
}

export default LandingPage

export const query = graphql`
  query($LandingPageID: String!){
    nodeLandingPage(id: { eq: $LandingPageID }) {
      id
      title
    }
  }
`

Nothing too fancy here, right? Just a template that we can use to build our pages out without Gatsby yelling at us on build.

Next, we're going to add this template to gatsby-node.js so that we create our pages dynamically.

// gatsby-node.js

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions

  const LandingPageTemplate = require.resolve(`./src/components/templates/LandingPage/index.js`)

  const LandingPage = await graphql(`{
    allNodeLandingPage {
      nodes {
        id
        path {
          alias
        }
      }
    }
  }
  `)

  LandingPage.data.allNodeLandingPage.nodes.map(node => {
    createPage({
      path: node.path.alias
      component: LandingPageTemplate,
      context: {
        LandingPageID: node.id,
      }
    })
  })
}

This is pretty straightforward so far, right? Let's think about what we're going to need in order for this to work the way we want it to and pull all of a single content type into our landing page.

We're going to need:

The content type we want to build a landing page for.
A query to fetch all content a content type.
The landing page template with logic to display the content type.
Probably some other things, but we'll sort that out along the way. We're in this together, remember?

How are we going to get these things? Let's go down the list.

The content type we want to build a landing page from:

We have this from our Drupal side. Remember, we created the Content Type field on our Landing Page content type? This can be placed in our gatsby-node.js and passed to our query via the context option.

Let's add it in. First we need to update our graphql query to pull it in:

// gatsby-node.js
  const LandingPage = await graphql(`{
    allNodeLandingPage {
      nodes {
        id
        relationships { // <---- add from this line
          field_content_type {
            drupal_internal__type
            name
          }
        } // <---- to this line
      }
    }
  }
  `)

What we're doing here is looking at GraphiQL and exploring our data to see what we have available. If we drill down into allNodeLandingPage.nodes we can see that in relationships we have field_content_type with some useful things. Specifically, our drupal_internal__type and name values. Also, notice that we removed nodes.path.alias from the query.

By adding these to our query we can now pass the info through to our created pages. We're going to do a bit of data manipulation here to create our paths dynamically as well. I follow the convention that a landing page's path should reflect the content type that it's a landing page for. So, if we were making a landing page for "Articles" the path would be path-to-my.site/articles and articles would have that as a base path to path-to-my.site/articles/my-awesome-article. However, you can follow whatever convention you see fit.

To do this, we're going to manipulate the name from the content type into a URL-friendly string by using the JavaScript .replace() function and then pass that to the path option. Since we also want to query for the content type on our landing page, we're going to pass the drupal_internal__type through the context option.

Let's do that:

// gatsby-node.js
  LandingPage.data.allNodeLandingPage.nodes.map(node => {
    const pathName = node.relationships.field_content_type.name.toLowerCase().replace(/ /g, '-') // <---- New line
    createPage({
      path: pathName, // <--- Changed line
      component: LandingPageTemplate,
      context: { 
        LandingPageID: node.id,
        ContentType: node.relationships.field_content_type.drupal_internal__type, // <---- New line
      }
    })
  })

What does the the context option do? It passes data to our component as props. GraphQL already pulls the context data for the queries, which you can see in any query that has a variable for the filter. Usually this is the content ID so that it can build a page for a specific piece of content from Drupal, but we can leverage this to add more variables and more filtering however we see fit.

Our next step is going to be to actually USE this additional info to do something amazing with.

A query to fetch all content a content type:

Let's look back at our src/components/templates/LandingPage/index.js and see what we need to query. We know we want to get all nodes of a certain content type, and we know that we want to reuse this template for any landing pages with content listing. Since we've established that allNodeTypeNodeType gives us access to all content on available to Gatsby, let's query on that.

// src/components/templates/LandingPage/index.js

export const query = graphql`
  query($LandingPageID: String!, $ContentType: String!){
    nodeLandingPage(id: { eq: $LandingPageID }) {
      id
      title
    }
    allNodeTypeNodeType(filter: { drupal_internal__type: { eq: $ContentType }}) { // <---- New section
      nodes {
        relationships {
          node__article {
            id
            title
            path {
              alias
            }
          }
          node__page {
            id
            title
            path {
              alias
            }
          }
        }
      }
    }
  }
`

What we're doing here is using that variable we passed via the context option in gatsby-node.js and filtering to only return the content type we're wanting to see. One 'gotcha' here is that this query will also return the landing page that references the content type. However, if you're not creating a landing page of landing pages then you should be alright.

Since we're only creating landing pages for two content types, this is fine, although we're not getting a lot back. Most projects that I've worked on have had some kind of "teaser" display for these kinds of pages. I'm not going to cover the specifics of creating a teaser template here, but the TL;DR is: start with your full display and take out everything but what you want on the teaser. For this post, we're going to create the list of links using the titles.

Now, if the content types that we're creating landing pages for don't have any content, then you're going to have a bad time. In this case, go back to my previous post about empty entity reference fields and see if you can use that to create some default fields and prevent errors or just create some content of the missing type.

Next, let's flesh out our landing page template a bit.

The landing page template with logic to display the content type:

So far, our template, minus the query, is pretty empty and not doing a lot. Let's add in the title of this landing page.

// src/components/templates/LandingPage/index.js
function LandingPage({ data }) {

  const landingPage = data.nodeLandingPage

  return (
    <div>
      <h1>{landingPage.title}</h1>
      <div className='content-list'></div>
    </div>
  )
}

I like to clean up the variables a bit and rename data.nodeLandingPage to landingPage. It's a bit cleaner to me, but do what you want.

Alright, we have the title of this content, but what about the list of content we want to show on this page? Well, we're going to need to do some logic for that. First off, we need to know which content type we're looking for. Second, we need a way find it. Third, we need to clean this data into something usable. Finally, we need to display it.

We could just display everything returned from our allNodeTypeNodeType query, but there would be a lot of nulls and issues parsing the arrays. Here's an example of what that query returns before we massage the data, using the Drupal internal type article:

{
  "data": {
    "allNodeTypeNodeType": {
      "nodes": [
        {
          "drupal_internal__type": "article",
          "relationships": {
            "node__article": [
              {
                "id": "0e68ac03-8ff2-54c1-9747-3082a565bba6",
                "title": "Article Template",
                "path": {
                  "alias": "/article/article-template"
                }
              }
            ],
            "node__basic_page": null
          }
        }
      ]
    }
  }
}

Now, to get the content this way we could do some complex mapping and sorting and filtering, but I tried that and it wasn't fun. Fortunately, Gatsby is here to rescue us and make life easier. Our context option gets passed into our page component as props. If you're unfamiliar with the concept of Props in React, and therefore Gatsby, props are properties that are passed into components. The line

function LandingPage({ data }) {

could be rewritten as

function LandingPage(props) {
  const data = props.data

but we're using a concept called Destructuring to only pass in the prop that we need. This allows us to create variables from object keys without having to take the extra steps. Our page component props object also contains the key pageContext which is where anything in the context option gets stored to give the page template access to.

Let's bring that in:

// src/components/templates/LandingPage/index.js
function LandingPage({ data, pageContext }) {

  const landingPage = data.nodeLandingPage
  const nodeType = data.allNodeTypeNodeType
  const contentType = 'node__' + pageContext.ContentType

Since we set our ContentType in gatsby-node.js we're able to use that here. Note that we're concatenating the string node__ with our pageContext.ContentType. We're doing this because everything in Gatsby is a node, including content types. This allows us to do the next steps.

Next, we want to clear out all of the non-content type data from the allNodeTypeNodeType query. This is what it looks like if we were to console.log(nodeType.nodes):

Array(1)
  0:
    relationships:
      node__article: Array(1)
        0: {id: "0e68ac03-8ff2-54c1-9747-3082a565bba6", title: "Article Template", path: {…}, …}
        length: 1
        __proto__: Array(0)
      node__page: null

We only want the node__article array, so how do we get that? Well, we need to use .map() and a concept called currying. This is essentially creating a function that allows us to use a variable from outside of the .map() scope inside of the .map() callback. It allows us to break down a function into more functions so that we have more control over it, which is what we need here.

// src/components/templates/LandingPage/index.js
function LandingPage({ data, pageContext }) {

  const landingPage = data.nodeLandingPage
  const nodeType = data.allNodeTypeNodeType
  const contentType = 'node__' + pageContext.ContentType

  const getContentArray = (contentType) => { // <---- Curry function, but not as delicious
    return (node) => (node.relationships[contentType])
  }

  const contentArray = nodeType.nodes.map(getContentArray(contentType))

We created our curry function that takes our contentType as an argument. From within there, it completes the mapping and returns our desired array... almost.

Here's what we get back if we console.log(contentArray):

[Array(1)]
  0: Array(1)
    0: {id: "0e68ac03-8ff2-54c1-9747-3082a565bba6", id: 1, title: "Article Template", …}
    length: 1
    __proto__: Array(0)
  length: 1
  __proto__: Array(0)

We're almost there, but now we have an array of our content within another array. If only there were a function to help us out here...

Just kidding, there is! For this, we're going to use .flat(). The .flat() function flattens out a nested array into a single level. However, there's a gotcha with it, as mentioned in this Stack/Overflow question. We can get around this by using the array-flat-polyfill polyfill.

Add gatsby-plugin-polyfill-io to your project by installing with yarn or npm

npm install array-flat-polyfill
// or
yarn add array-flat-polyfill

and in your component file add the following within

import 'array-flat-polyfill'

So, let's flatten that array!

function LandingPage({ data, pageContext }) {

  const landingPage = data.nodeLandingPage
  const nodeType = data.allNodeTypeNodeType
  const contentType = 'node__' + pageContext.ContentType

  const getContentArray = (contentType) => {
    return (node) => (node.relationships[contentType])
  }

  const contentArray = nodeType.nodes.map(getContentArray(contentType))
  const contentArrayFlat = contentArray.flat()

And the resulting console.log(contentArrayFlat):

0:
  id: "0e68ac03-8ff2-54c1-9747-3082a565bba6"
  path: {alias: "/article/article-template"}
  title: "Article Template"
  length: 1
__proto__: Array(0)

Now we've got exactly what we wanted! The final step is to put this to work. We'll do that by creating a list of titles that link to the content. Your finished component should look like:

// src/components/templates/LandingPage/index.js
import React from 'react'
import { graphql, Link } from 'gatsby' // <--- added 'Link' here to use the link component
import 'array-flat-polyfill'

function LandingPage({ data, pageContext }) {

  const landingPage = data.nodeLandingPage
  const nodeType = data.allNodeTypeNodeType
  const contentType = 'node__' + pageContext.ContentType

  const getContentArray = (contentType) => {
    return (node) => (node.relationships[contentType])
  }

  const contentArray = nodeType.nodes.map(getContentArray(contentType))
  const contentArrayFlat = contentArray.flat()

  return (
    <div>
      <h1>{landingPage.title}</h1>
      <div className='content-list'>
        <ul>
          // One-liner to create the list of items.
          {contentArrayFlat.map((item, i) => <li key={i}><Link to={item.path.alias}>{item.title}</Link></li>)}
        </ul>
      </div>
    </div>
  )
}

export default LandingPage

export const query = graphql`
  query($LandingPageID: String!, $ContentType: String!){
    nodeLandingPage(id: { eq: $LandingPageID }) {
      id
      title
    }
    allNodeTypeNodeType(filter: { drupal_internal__type: { eq: $ContentType }}) {
      nodes {
        relationships {
          node__article {
            id
            title
            path {
              alias
            }
          }
          node__page {
            id
            title
            path {
              alias
            }
          }
        }
      }
    }
  }
`

And that's all there is to it. Hopefully you find this useful and it helps speed up your development with Gatsby a little bit. If I missed anything on here, please don't hesitate to let me know in the comments. Always feel free to reach out to me on Twitter or Slack or any way you want to.

Credit where credit is due: Shane Thomas (AKA @codekarate) and Brian Perry (AKA @bricomedy) helped me work through this issue at NEDCamp.

Patron thanks:

Thank you to my Patreon Supporters

David Needham
Tara King
Lullabot

For helping make this post. If you'd like to help support me on Patreon, check out my page https://www.patreon.com/jddoesthings

GatsbyJS + Drupal: Create Custom GraphQL Schema for Empty Fields

jflynn — Mon, 18 Nov 2019 20:40:00 +0000

GatsbyJS + Drupal: Create Custom GraphQL Schema for Empty Fields jflynn Mon, 11/18/2019 - 14:40

Stop me if you've heard this one...

A developer is trying to connect Drupal to Gatsby. Drupal says, "I've got a Related Content field that allows SEVEN different entity types to be referenced, but only THREE slots for content. What do you think?"

Developer says, "Sure, no problem, Drupal!"

Gatsby jumps in and says, "You better make sure that all seven of those entity types are in those three slots."

Developer and Drupal look at each other in confusion. Developer says, "Gatsby, that's not GREAT"

** Laughs go here **

What happened?

It turns out the way that Gatsby builds what it calls "nodes" is by querying the data available. This usually works perfectly, but there are occasions where all the data might not be present, so Gatsby doesn't build the nodes, or it builds the nodes, but doesn't create all of the fields. Any optional field can fall into this if there is no content in that field on a Drupal entity, and if you're building templates for your decoupled site, then you might just want some content in that field.

NOTE: A Drupal "node" and a GraphQL "node" are not the same thing. This may take some time to sink in. It definitely did for me! For the remainder of this post I will refer to GraphQL nodes as "nodes" and Drupal nodes as "entities". Everybody got that? Good, moving on.

Because the nodes with your hypothetical content have not yet been created, or the fields on your entity don't have anything in them, Gatsby just passes right over them and acts like they don't even exist.

Commonly, you'll see something like this pop up during gatsby build or gatsby develop:

Generating development JavaScript bundle failed


/var/www/gatsby/src/components/templates/homepage/index.js
  56:9  error  Cannot query field "field_background_media" on type "node__homepageRelationships".

This can be frustrating. And when I say "frustrating" I mean that it's table-flipping, head slamming into desk, begging for help from strangers on the street frustrating. The quick fix for this one is simple: ADD SOMETHING TO THE FIELD. In fact, you don't even have to add it to every instance of that field. You can get away with only putting some dummy content in a single entity and you'll have access to that field in Gatsby.

You could also make it a required field so that there MUST be something in it or else the author can't save. This is valid, but in the event that your project's powers-that-be decide that it should be optional, you may need another alternative. This is where GraphQL schema customization comes in.

GraphQL schema and Gatsby

First, a little primer on GraphQL schema. Outside of Gatsby, a system using GraphQL usually needs to define the schema for GraphQL nodes. Gatsby takes this out of the developer's hands and builds the schema dynamically based on the content available to it from its source, in this case gatsby-source-drupal. However, empty data in the source results in no schema in Gatsby.

Let's look at the fix for the optional image above and why it works:

In gatsby-node.js we build our schema through createPages, createPage, and GraphQL queries. This is also where we're going to place our code to help GraphQL along a little bit. This will live in a function called createSchemaCustomization that we can use to customize our GraphQL schema to prevent empty field errors from ruining our day.

The Gatsby docs outline this in the Schema Customization section, but it didn't really click there for me because the examples are based on sourcing from Markdown as opposed to Drupal or another CMS. Things finally clicked a little when I found this issue on Github that showed how to work around a similar problem when sourcing from WordPress.

Three scenarios and three solutions

Scenario 1: Empty field

This is by far the simplest scenario, but that doesn't make it simple. If you have a basic text field on a Drupal entity that does not yet have any content or at some point may not have any content, you don't want your queries to break your site. You need to tell GraphQL that the field exists and it needs to create the matching schema for it.

Here's how it's done:

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    type node__homepage implements Node {
      field_optional_text: String
  `
  createTypes(typeDefs)
}

Now, to walk through it a bit. We're using createSchemaCustomization here and passing in actions. The actions variable is an object that contains several functions so we destructure it to only use the one we need here: createTypes.

We define our types in a GraphQL query string that we lovingly call typeDefs. The first line of the query tells which type we're going to be modifying, in this case node__homepage, and then what interface we're implementing, in this case Node.

NOTE: If you're looking at GraphiQL to get your field and node names it may be a bit misleading. For example, in GraphiQL and in my other queries node__homepage is called as nodeHomepage. You can find out what the type name is by running a query in GraphiQL that looks like:

query MyQuery {
  nodeHomepage {
    internal {
      type
    }
  }
}

or by exploring your definitions in GraphiQL.

Next, we add the line field_optional_text: String which is where we define our schema. This is telling GraphQL that this field should exist and it should be of the type String. If there are additional fields, Gatsby and GraphQL are smart enough to infer them so you don't have to redefine every other field on your node.

Finally, we pass our customizations into createTypes and restart our development server. No more errors!

Scenario 2: Entity reference field

Suppose we have a field for media that may not always have content. We still want our queries to work in Gatsby, but if there's only one Drupal entity of this content type and it happens to not have an image attached, then our queries are going to break, and so will our hearts. This requires a foreign key relationship because the entity itself is a node to GraphQL.

Here's how it's done:

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    type node__homepage implements Node {
      relationships: node__homepageRelationships
    }
    type node__homepageRelationships {
      field_background_media: media__image @link(from: "field_background_media___NODE")
    }
  `
  createTypes(typeDefs)

Looks a little similar to the previous scenario, but there's a bit more to it. Let's look at the changes.

Instead of defining our custom schema under the type node__homepage implements Node { line, we reference our relationships field which is where all referenced nodes live. In this case, we tell GraphQL that the relationships field is of type node__homepageRelationships. This is another thing you can find using GraphiQL.

The next section further defines our relationships field. We declare that node__homepageRelationships should have the field field_background_media of type media__image, but what's that next part? That's where our foreign key link is happening. Since field_background_image is an entity reference, it becomes a node. This line links the field to the node created from the field. If you don't include the @link(from: "field_background_media___NODE) in your query you'll get a deprecation notice:

warn Deprecation warning - adding inferred resolver for field node__homepageRelationships.field_background_media. 
  In Gatsby v3, only fields with an explicit directive/extension will get a resolver.

Edit: This post was edited to reflect the deprecation notice instead of indicating that @link is optional.

Scenario 3: Related content field with multiple content types

This is the one that had me crying. I mean scream-crying. This is the widowmaker, the noisy killer, the hill to die upon. At least it WAS, but I am triumphant!

Like my horrible joke from the beginning of this post, I have a related content field that is supposed to allow pretty much any content type from Drupal, but only has three slots. I need to have queries available for each content type, but if one doesn't exist on the field, then GraphQL makes a fuss. I can't say for sure, but I've got a feeling that it also subtly insulted my upbringing somewhere behind the scenes.

Now, I'm here to save you some time and potentially broken keyboards and/or monitors.

Here's how it's done:

exports.createSchemaCustomization = ({ actions }) => {
  const { createTypes } = actions
  const typeDefs = `
    union relatedContentUnion =
      node__article
      | node__basic_page
      | node__blog_post
      | node__cat_food_reviews
      | node__modern_art_showcase
      | node__simpsons_references

    type node__homepage implements Node {
      relationships: node__homepageRelationships
    }
    type node__homepageRelationships {
      field_related_content: [relatedContentUnion] @link(from: "field_related_content___NODE")
    }
  `
  createTypes(typeDefs)
}

The biggest changes here are the union and the brackets around the type. From the GraphQL docs:

Union types are very similar to interfaces, but they don't get to specify any common fields between the types.

This means that any type in the union can be returned and they don't need to have the same fields. Sounds like exactly what we need, right?

So we define our union of our six content types and create the relationship using a foreign key link. We use the node created from our field, field_related_content___NODE as our foreign reference, and we get results. However, the brackets around the union are there, and they must do something. In fact they do. They indicate that what will be returned is an array of content in this union, meaning that there will be multiple values instead of one single value returned.

Summary

This seriously took me much longer than it should have to figure out. Hopefully, you don't suffer my same fate and find this post useful. One thing to note that almost destroyed me is that there are THREE, count them 1, 2, 3, underscores between the field name and NODE in the link. _ _ _ NODE. I only put two when I was fighting this and it cost me more time than I'm willing to admit on a public forum.

Special thanks to Shane Thomas (AKA Codekarate) for helping me sort through this and being able to count to 3 better than me.

Using Drupal Blocks in a Decoupled GatsbyJS Application

jflynn — Sun, 03 Nov 2019 18:40:45 +0000

Using Drupal Blocks in a Decoupled GatsbyJS Application jflynn Sun, 11/03/2019 - 12:40

One of the most useful components of Drupal is the Block system. This system allows for pieces of content to be created and reused throughout a site in various regions of the page structure. You can also select which bundles or content types this piece of content should appear on, making it so that a blog post gets a certain Call to Action section while an article gets something similar, but different.

When we use GatsbyJS for a decoupled front-end solution with a Drupal back-end, we lose out on quite a bit, if not everything, that the theme layer of Drupal provides. This means that Drupal regions mean nothing to Gatsby, nor does block placement. In fact, any functionality that would go into a .theme file is no longer available on the Drupal side.

Before I get into the "how" of using Drupal blocks in Gatsby, I want to cover a little bit of the "why".

Why Use Drupal Blocks for Content in a Gatsby Front End?

The main advantage of blocks in Drupal is that the content is created in one place, but can be placed in several spots. I have worked with solutions that use Paragraphs (from the Paragraphs contrib module) for similar functionality, but the problem remains where the content needs to be recreated on every new parent entity. For example, I can create a Call to Action (CTA) Paragraph and place fields that reference them on every content type, but the Paragraphs themselves remain separate. A Paragraph is more like a collection of fields to be filled out than a reusable entity, and that's okay.

In contrast, a Block can be created in one place, usually using the Block UI, and the content of the Block remains the same no matter where it is placed. A CTA block on a blog post will have identical content to the CTA block on an article. This makes content changes extremely fast compared to having to update every article and blog post if the wording or link need to change.

It is entirely possible to create these types of entities in Gatsby by defining a reusable component, however the editing experience doesn't really pan out. It may require a developer to go in and edit a React component, adding a middle-person to the process. Using reusable Drupal blocks can save time and budget when set up appropriately.

How to Use Drupal Blocks for Content in a Gatsby Front End

This section is going to make a few assumptions.

You have a basic understanding of Gatsby and React components.
You understand the Drupal theme layer.
You have a basic understanding of the Drupal block system.
Your decoupled application is already setup and pulling content from Drupal (not necessary, but it helps if you can try it out)
You have the JSON:API module enabled on Drupal
You're sourcing content from Drupal.

If you're having problems with any of these, feel free to reach out to me on Drupal Slack, I go by Dorf there.

Now the "how". We're going to start by creating a Custom Block Type. Let's keep going with the CTA theme and call it "CTA Block". We do this by logging into our site as someone with permissions to access the Block UI and going to admin/structure/block/block-content/types. Once there, select "Add custom block type".

Let's label this CTA Block and begin creation. After we create it, we need to add some fields, so let's add the following fields:

CTA Heading
- A plain text field, max 255 chars
CTA Link
- A Link field using URL and label, internal and external links, Label required.
CTA Content Types
- This is the field that will make all the difference. Create this field as Reference: Other... to begin with.
- Label it CTA Content Type.
- Under "Type of entity to reference" choose "Content type" from the select list, under Configuration.
- Set unlimited cardinality.
- Go through the remaining screens to create this field. Once you're back on the field list, select "Manage form display"
- From here, we're going to change the widget from Autocomplete to Check boxes/radio buttons.
- Save your changes

Now we're going to create a new block using this Custom Block Type. When we create the block under block/add/cta_block the form should look something like this:

Now, add whatever text you want to the fields, but only select a single content type in the CTA Content Type field. Save the block and spin up your Gatsby dev environment. We're going to switch over there for a bit.

Let's fire up our develop environment and take a look at GraphiQL to see what we have going on.

As you can see, we now have access to allBlockContentCtaBlock in GraphiQL, but what are we going to do with it? Well, we are first going to create the CTA Block React component. We'll do that by creating the file src/components/blocks/CtaBlock.js and adding the following:

import React from 'react'
import { graphql } from 'gatsby'

const CtaBlock = ({ data }) => {

  return <div class='ctaBlock'>
    <h3>CTA Heading</h3>
      <p>CTA Text goes here and here and here.</p>
      <a href="http://example.com">Link Text</a>
    </div>
}

export default CtaBlock

This is pretty simple and doesn't include anything having to do with our GraphQL query yet, but we have the structure in place. Now, let's look at the data we can pull from GraphQL. We want to get the heading, body, link, and content type, so our query is going to look something like this:

query MyQuery {
  allBlockContentCtaBlock {
    nodes {
      field_cta_heading
      field_cta_link {
        title
        uri
      }
      body {
        value
      }
      relationships {
        field_cta_content_type {
          name
        }
      }
    }
  }
}

Which will give us back:

{
  "data": {
    "allBlockContentCtaBlock": {
      "nodes": [
        {
          "field_cta_heading": "Heading for the CTA Block",
          "field_cta_link": {
            "title": "Learn more!",
            "uri": "http://google.com"
          },
          "body": {
            "value": "<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Vestibulum facilisis, purus nec pulvinar iaculis, ligula mi congue nunc, vitae euismod ligula urna in dolor. Aenean massa.</p>\r\n\r\n<p>Praesent nec nisl a purus blandit viverra. Nullam nulla eros, ultricies sit amet, nonummy id, imperdiet feugiat, pede. Phasellus dolor.</p>\r\n"
          },
          "relationships": {
            "field_cta_content_type": [
              {
                "name": "Blog Post"
              }
            ]
          }
        }
      ]
    }
  }
}

Perfect! Now I want you to notice a couple of things here. First, we're querying ALL of the CTA blocks here. Second, we're using the content type in the query. Let's get this into our component. Add in the query to our CtaBlock.

import React from 'react'
import { graphql } from 'gatsby'

const CtaBlock = ({ data }) => {

  return <div class='ctaBlock'>
    <h3>CTA Heading</h3>
      <p>CTA Text goes here and here and here.</p>
      <a href="http://example.com">Link Text</a>
    </div>
}

export default CtaBlock

export const CtaBlockQuery = graphql`
  allBlockContentCtaBlock {
    nodes {
      field_cta_heading
      field_cta_link {
        title
        uri
      }
      body {
        value
      }
      relationships {
        field_cta_content_type {
          name
        }
      }
    }
  }`

But wait, this isn't a page template, and it shouldn't be. What's the problem then? We have a query in a non-page template, and that's not good. What we need to do is figure out which of our templates are going to use this block and add it in there. Since we chose to have the block show on the blog post content type, we're going to use the blog post template. This will probably differ for your setup.

Let's open up our page template and take a look:

  import React from 'react'
  import { graphql } from 'gatsby'

  import Layout from '../layouts'

  const BlogPostTemplate = ({ data }) => {

    const blogBody = data.nodeBlogPost.body.value

    return <Layout>
      <h3>{data.nodeBlogPost.title}</h3>
      {data.nodeBlogPost.body.value}
    </Layout>
  }

  export default BlogPostTemplate

  export const query = graphql`
  query($BlogPostID: String!){
  nodeBlogPost(id: { eq: $BlogPostID }) {
    id
    title
    body {
      processed
    }
  }
}
`

Now let's update this to have the block appear.

import React from 'react'
import { graphql } from 'gatsby'

import Layout from '../layouts'
import CtaBlock from '../blocks/CtaBlock'

const BlogPostTemplate = ({ data }) => {

  const blogBody = data.nodeBlogPost.body.value

  return <Layout>
    <h3>{data.nodeBlogPost.title}</h3>
    {data.nodeBlogPost.body.value}
    <CtaBlock />
  </Layout>
}

export default BlogPostTemplate

export const query = graphql`
  query($BlogPostID: String!){
  nodeBlogPost(id: { eq: $BlogPostID }) {
    id
    title
    body {
      processed
    }
  }
}
`

But we still need to include the query for the block itself. To do this, we're going to make a few edits to both of our components. We'll start with the CtaBlock component and convert the query into a fragment that we can reuse in multiple places if need be.

import React from 'react'
import { graphql } from 'gatsby'

const CtaBlock = ({ data }) => {

  return <div class='ctaBlock'>
    <h3>CTA Heading</h3>
      <p>CTA Text goes here and here and here.</p>
      <a href="http://example.com">Link Text</a>
    </div>
}

export default CtaBlock

export const CtaBlockQuery = graphql`
  fragment CtaBlockQuery on block_content__cta_block {
  field_cta_heading
  field_cta_link {
    title
    uri
  }
  body {
    value
  }
  relationships {
    field_cta_content_type {
      name
    }
  }
}`

If you have a keen eye, you'll notice that we've removed the nodes section of the query. This is because we're now going to query for a single block. However, there is some risk to this. In the event that a content creator creates a new CTA block on Drupal for this content type instead of editing the existing one, the old one will remain in place because a single item query will only return a single item.

Now, let's move back over to our page template and use this fragment to query for our block.

import React from 'react'
import { graphql } from 'gatsby'

import Layout from '../layouts'
import CtaBlock from '../blocks/CtaBlock'

const BlogPostTemplate = ({ data }) => {

  const blogBody = data.nodeBlogPost.body.value

  return <Layout>
    <h3>{data.nodeBlogPost.title}</h3>
    {data.nodeBlogPost.body.value}
    <CtaBlock />
  </Layout>
}

export default BlogPostTemplate

export const query = graphql`
  query($BlogPostID: String!){
  nodeBlogPost(id: { eq: $BlogPostID }) {
    id
    title
    body {
      processed
    }
  }
  blockContentCtaBlock (relationships:
    {field_cta_content_types:
      {elemMatch:
        {name:
          {eq: "Blog Post"}
          }
        }
      }
    ){
    ...CtaBlockQuery
  }
}
`

Take a look at what we've done here. We've added in a query for the CtaBlock and we're filtering it by the content type it's attached to. After that, we're pulling in everything from the query on our component. This is exactly what we were wanting to do, but there's another step that we need to take to actually use the data on our component.

If you look at the JSX element for

<CtaBlock />

you'll notice we aren't passing anything to it, so we've got to make sure it has data to work with or we're going to end up rendering nothing. Edit that line to be

<CtaBlock data={data} />

In case you're not familiar, this is a React concept known as passing props, or properties, to a child component. We're passing the data object that was returned from our GraphQL query to the CtaBlock component so that it can use the included data. Since this is just a demo, we're passing the entire thing along, but it's easy enough to only pass the relevant parts of the object.

Now back in our CtaBlock component we can use the data to render out our block's content.

import React from 'react'
import { graphql } from 'gatsby'

const CtaBlock = ({ data }) => {

  return <div class='ctaBlock'>
    <h3>{data.blockContentCtaBlock.field_cta_heading}</h3>
      <p dangerouslySetInnerHtml= {{
        __html: data.blockContentCtaBlock.body.value}} />
      <a href={data.blockContentCtaBlock.field_cta_link.uri}>{data.blockContentCtaBlock.field_cta_link.title}</a>
    </div>
}

export default CtaBlock

export const CtaBlockQuery = graphql`
  fragment CtaBlockQuery on block_content__cta_block {
  field_cta_heading
  field_cta_link {
    title
    uri
  }
  body {
    value
  }
  relationships {
    field_cta_content_type {
      name
    }
  }
}`

Now we have our block based on content type rendering within our content type's Gatsby template. Note that I've left out a few things that should be noted for decoupled sites.

An internal link should us the Gatsby <Link /> component.
Drupal needs some love to pass the correct alias over for an internal link so that it renders correctly.
This is a very basic example. YMMV.

Anyway, I hope that this helps someone out there who ran into the same problems that I did. Please feel free to reach out to me on Twitter @jddoesdev, on Slack where I'm usually Dorf, or just leave a comment here if you have questions, concerns, comments, or just something nice to say.

Also, please feel free to support my efforts in speaking on mental health in tech or creating blog posts and tutorials like these by checking out my gofundme and patreon campaigns in the sidebar.

Thanks for reading!