Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub

gatsby-source-mozaik

Source plugin for pulling data from a Mozaik endpoint into Gatsby.

Install

  1. yarn add gatsby-source-mozaik or npm i gatsby-source-mozaik
  2. Add reference in your Gatsby config plugins section to gatsby-source-mozaik. See example below.
  3. Run gatsby develop

Usage

Make sure that gatsby-source-mozaik plugin is referenced in you gatsby-config.js:

plugins: [
  {
    resolve: `gatsby-source-mozaik`,
    options: {
      endpoint: `https://api.mozaik.io/[your-project-name]`,
      accessToken: `your-access-token`,
      query: `
        query documentsQuery($types: [DocumentContentTypeEnum] $pageSize: Int $page: Int) {
          documents(types: $types pageSize: $pageSize page: $page) {
            pagination {
              page
              pageCount
            }
            items {
              id
              contentType
              slug
            }
          }
        }
      `,
      variables: {
        types: [],
        pageSize: 20,
        page: 1
      },
      fragments: []
    },
  }
],

Plugin options

Key Value Required
endpoint Your mozaik api endpoint: https://api.mozaik.io/[your-project-name] Yes
accessToken The access token for authorizing against the api Yes
query The graphql query to execute. You should use the sample documents query and only amend it. Yes
variables Variables to use in the graphql query Yes
variables.types An array of string that defines the content types you want to get from the api Yes
variables.pageSize Number of items to download in one batch Yes
variables.page The page number Yes
fragments An array of string that defines the fields you want to query on each content type No

How to write a query

Let’s say you have created a blog project using the sample blog template on Mozaik. You will have 3 different content types (the enum name in your GraphQL schema):

  • Homepage (HOMEPAGE)
  • Post (POST)
  • Author (AUTHOR)

And you only implement the homepage and the post page components.

To create the query you have to add the following plugin options:

Variables

variables: {
  types: ['HOMEPAGE', 'POST'],
  page: 1,
  pageSize: 20
}

Query and Fragments

In Mozaik each document implements the DocumentInterface type, and because of this the result of the documents query returns an array of DocumentInterface object. To be able to query specific fields on each document, you have to define a fragment for each content type. Although you can do this by inlining the fragments in the query itself, we highly recommend to add every fragment in the fragments plugin option in you config. You can read more about interfaces and fragments in the GraphQL documentation

First let’s add the fragment definitions:

fragments: [
  `fragment HomepageDetails on HomepageDocument {
    title
    tagline
    headerImage {
      ...HeaderImageFragment
    }
    topPosts {
      items {
        ...PostDetails
      }
    }
  }`
  `fragment PostDetails on PostDocument {
    title
    slug
    date
    postContent {
      html
    }
    postAuthor {
      name
    }
    headerImage {
      ...HeaderImageFragment
    }
  }`,
  `fragment HeaderImageFragment on Asset {
    url
    thumbnailUrl
    caption
  }`
]

Update the default query to add the fragments above:

query documentsQuery($types: [DocumentContentTypeEnum] $pageSize: Int $page: Int) {
  documents(types: $types pageSize: $pageSize page: $page) {
    pagination {
      page
      pageCount
    }
    items {
      id
      contentType
      slug
      ...PostDetails
      ...HomepageDetails
    }
  }
}

And that’s it! You’re ready to run gatsby develop and load all your documents. If you open the graphql ide that comes with Gatsby you can query your Post documents by running the allPosts query (or the allHomepage query for the Homepage document).

Contributing

  1. cd to the Gatsby project you’ve set up in which you want to test your changes of the plugin code, or clone mozaikio/mozaik-gatsby-example
  2. If you cloned the example or previously installed the plugin through yarn or npm, run yarn remove gatsby-source-mozaik or npm r gatsby-source-mozaik
  3. mkdir plugins if it does not exist in your Gatsby project yet and cd into it
  4. The path should now be similar to this: ~/projects/mozaik-gatsby-website/plugins/
  5. run git clone https://github.com/mozaikio/gatsby-source-mozaik.git
  6. cd gatsby-source-mozaik
  7. run yarn or yarn && yarn watch in gatsby-source-mozaik plugin’s folder for auto-rebuilding the plugin after you make changes to it (you need to do this only during development)
  8. Make sure plugin is referenced in your Gatsby config (see above at Usage)
  9. From there you can cd ../.. && yarn && yarn develop to test
© 2023 Gatsby, Inc.