Gatsby source plugin for Silverstripe CMS

This library allows you to pull in Silverstripe CMS content into your Gatsby project. It maintains a high fidelity to the GraphQL schema that Silverstripe CMS provides using the alpha-release of silverstripe-graphql v4. It also uses a template inheritance system similar to SSViewer.

Requirements

You must install the silverstripe-gatsby module on your CMS.

Installation

$ yarn add gatsby-source-silverstripe

Getting started

The best way to get started using this plugin is to use the gatsby-starter-silverstripe Gatsby starter. It includes a setup script that will get everything configured for you using a default theme.

Configuration

Example configuration:

    {
      resolve: `gatsby-source-silverstripe`,
      options: {
        baseUrl: process.env.SILVERSTRIPE_CMS_BASE_URL,
        apiKey: process.env.SILVERSTRIPE_CMS_API_KEY,
        stage: process.env.SILVERSTRIPE_STAGE,
        concurrentRequests: 5,
        batchSize: 300,
        templatesPath: `src/templates`
      }
    },

There are several options available for configuration:

baseUrl

Required. The absolute base URL to your Silverstripe CMS installation, excluding the graphql suburl. It is recommended that you store this in an environment variable, as it will change depending on where the project is deployed, e.g. (localhost in dev).

apiKey

Required. The API key from your Silverstripe CMS member. Find this in the Security section, on the "Api keys" tab for the member you want to use for authentication (should be an administrator). It is strongly recommended you store this in an environment variable for security.

graphqlEndpoint

The pathname to your gatsby graphql server endpoint, e.g. __gatsby/graphql. Defaults to __gatsby/graphql.

batchSize

The number of records to fetch per network request. Defaults to 100.

concurrentRequests

The number of network requests to allow in flight at any given time. Defaults to 5. Values over 30 are likely to crash your server unless they are well provisioned.

Tweaking this setting along with batchSize are the primary levers available for speeding up builds.

typePrefix

The prefix to apply to all types that come from Silverstripe. Defaults to SS_.

stage

The stage to read (DRAFT | LIVE). Defaults to DRAFT.

templatesPath

The path where your page templates live.

hardCacheAssets

If true, cache the downloaded assets outside the Gatsby cache directory to prevent them from being redownloaded, even after clearing the Gatsby cache for a full build. Only works if your assets are colocated with your CMS instance. Do not use this option if you host your uploaded assets on a CDN. Defaults to true.

Usage

Setting up templates

The first thing you'll need to do is add at least one template. The source plugin uses the same template inheritance pattern as Silverstripe CMS, so it's a good idea to have a Page.js file as your fallback template.

Add a Page.js component to src/templates.

const Page = ({
  data: {
    ssSiteTreeInterface: {
      title,
      content,
    } 
  }
}) => (
  <PageLayout>
    <div className="container"> 
      <SEO title={title} />
      <h1>{title}</h1>      
      <div dangerouslySetInnerHTML={{__html: content }} />
    </div>
  </PageLayout>
);

export const query = graphql`
  query($id: String!) {
    ssSiteTreeInterface( id: {eq: $id }) {
        title
        content
    }
  }
`;

export default Page;

Where PageLayout is a component with all the wrapper content, e.g. main nav, footer, similar to your templates/Page.ss in Silverstripe CMS.

If you have a page type HomePage, you'll also want to create a src/templates/HomePage.js, and so on.

Querying data

The inheritance pattern we use in Sivlerstripe CMS is handled with interfaces in the GraphQL API. When making a polymorphic query, like readSiteTrees, you'll need to query the interface, and use inline fragments to capture fields that are specific to concrete types, like HomePage.

query {
    allSsSiteTreeInterface {
        nodes {
            title # common to all SiteTree
            link # common to all SiteTree
            ... on SS_HomePage {
                featuredProducts {
                    title
                    price
                }
            }
        }
    }
}

This pattern is particularly relevant to the Elemental module (content blocks), where most queries are abstractions.

query {
    allSsPageInterface {
        nodes {
            title
            elementalArea {
                elements {        
                    id # these fields are common to all SS_BaseElementInterface
                    showTitle              
                    title
                    ... on SS_ElementContent {
                        html # specific to this concrete type
                    }
                }
            }
        }
    }
}

In general, if you're quering for a type that has subclasses, use the interface. If you're quering for one specific type, e.g. HomePage, use a regular query, like this:

query {
    ssHomePage {
        title
        featuredProducts {
            title
            price
        }
    }
}

Dealing with files

Files get special handilng in Gatsby with the gatsby-source-filesystem plugin, but we also want to retain the Silverstripe CMS native File object for supporting realted data. For this, a localFile field is added to each Silverstripe File type that contains the native Gatsby file, which you can use for image manipulation and static path access.

  query {
    ssProductPage {
        title
        content
        products {
          id
          title
          price
          image {
            localFile {
              childImageSharp {
                gatsbyImageData(width: 200)
              }
            }
          }
        }
    }
  }

Navigation

Navigation is a complex problem to solve, and this is a work in progress. For some example code, see the gatsby-starter-silverstripe package.

Development

This package is written in typescript. To make changes, run yarn watch during development. To publish, use yarn format and yarn build.