@jambaree/gatsby-theme-wordpress

🚀 Quick start

Use our starter project @jambaree/gatsby-starter-wordpress or just add the theme and page template components.

Install and add the theme to your gatsby-config.js

yarn add @jambaree/gatsby-theme-wordpress

Minimal gatsby-config setup

module.exports = {
  plugins: [
    {
      resolve: `@jambaree/gatsby-theme-wordpress`,
      options: {
        // the only required plugin option is the WordPress GraphQL url.
        url: process.env.WPGRAPHQL_URL || "https://gatsbystarter.wpengine.com",
      },
    },
  ],
}

Plugin Options

@jambaree/gatsby-theme-wordpress composes other themes and plugins inside of itself.

Notably, gatsby-theme-headless-wordpress and gatsby-source-wordpress.

You can pass options to any of the child themes or plugins like this:

{
  resolve: `@jambaree/gatsby-theme-wordpress`,
  options: {
    // the only required plugin option is the WordPress GraphQL url.
    url: process.env.WPGRAPHQL_URL || "https://gatsbystarter.wpengine.com",
    
    "gatsby-theme-headless-wordpress": {
      // pass any options to gatsby-theme-headless-wordpress here
      options: {
        excludedNodeTypes: ["MediaItem"],
        type: {
          product: {
            postsPerPage: 9999,
          },
        },
      },
    },
    
    "gatsby-source-wordpress": {
      // pass any options to gatsby-source-wordpress here
      options: {
        html: {
          createStaticFiles: true,
          useGatsbyImage: true,
        },
        type: {
          MediaItem: { createFileNodes: true },
        },
      },
    },
  },
},

Page Templates

Read up about where to create your page templates in the gatsby-theme-headless-wordpress docs.

Components

FlexibleContent

Whenever you are using flexible content acf fields in WordPress you can easily render different components for each item using the <FlexibleContent/> component.

Example page template using FlexibleContent

import React from "react"
import { FlexibleContent } from "@jambaree/gatsby-theme-wordpress"

import * as blocks from "../../components/blocks"

const MyPageTemplate = (props) => {

  const {
    data: {
      page: {
        title,
        uri,
        acfFieldGroupName: { flexibleContentField },
      },
    },
  } = props
  
  return (
    <FlexibleContent blocks={blocks} rows={flexibleContentField} />
  )

}

export default MyPageTemplate

export const MyPageQuery = graphql`
  query DefaultPage($id: String!) {
    page: wpPage(id: { eq: $id }) {
      title
      slug
      uri
      id
      acfFieldGroupName {
         flexibleContentField {
            __typename
            ... on WpPage_AcfFieldGroupName_FlexibleContentField_Hero {
              headline // each sub field is automatically passed to the component as a prop
            }
            ... on WpPage_AcfFieldGroupName_FlexibleContentField_Text {
              text
            }
         }
      }
    }
  }
`

FlexibleContent Props

| Prop | type | Description | default | |--------------- |--------- |--------------------------------------------------------------------------------------------------------------------------- |----------- | | blocks | object | An object containing all of your components with keys matching the row. | undefined | | rows | array | Array of your flexible content rows data queried from WordPress | undefined | | data | object | Additional data passed to each individual flexible content component. | undefined | | suspense | boolean | Opts-in to using suspense. Wraps each component with Suspense component. Allows you to use lazy imports. | false | | suspenseProps | object | Additional props to pass to your Suspense wrapper components. Example: { fallback: false, unstable_avoidThisFallback: true } | undefined |

blocks

The components you want to render for each of your flexible content rows.

Accepts an object. Easy way to use this is wildcard importing all of your flexible content components.

Example blocks.js:

// with default exports
import Hero from "./Hero"
import Text from "./Text"

export {
  Hero,
  Text
}

// with named exports
export { Hero } from "./Hero"
export { Text } from "./Text"

Example blocks.js using lazy imports with suspense:

import { lazy } from "react"

export const Hero = lazy(() => import("./Hero"))
export const Text = lazy(() => import("./Text"))

// you can mix and match lazy and regular imports
export const Hero = lazy(() => import("./Hero"))
export { Text } from "./Text"

The blocks prop can also accept an object with keys matching the field name of each individual flexible content row. Example

import MyHeroComponent from "./MyHeroComponent"

const blocks = {
  Hero: MyHeroComponent // matching by the last chunk of the __typename (WpPage_AcfFieldGroupName_FlexibleContentField_Hero)
}

<FlexibleContent blocks={blocks} />

Each sub field on the flexible content row is passed to the component as a prop. Example:

const MyHeroComponent = ({ headline }) => {
  return (...)
}

useMenuItems

| Prop | type | Description | default | |---------- |-------- |------------------------------------------------------------- |----------- | | location | string | WordPress menu location enum. example: "GATSBY_HEADER_MENU" | undefined | | slug | string | The menu slug. example: "main-menu" | undefined |

Example:

import React from "react"
import { useMenuItems } from "@jambaree/gatsby-theme-wordpress"
import { Link } from "gatsby"

const Navigation = () => {
  const menuItems = useMenuItems({ location: "GATSBY_HEADER_MENU" })
  
  return (
    <div>
      {menuItems?.map?.(({ label, url, childItems }, index) => (
        <Link key={index} to={url}>
          <li>{label}</li>
          {/* // map over childItems in a dropdown etc.. */}
        </Link>
      ))}
    </div>
  )
}