Support and Documentation

How to use Brightspot GraphQL Preview

This guide will show you how you can still leverage Brightspot's preview functionality even when going headless.

Configuring GraphQL Preview
  1. In Brightspot, navigate to Menu > Admin > Sites > Settings, and select your site in the left pane.

  2. Scroll down to the Preview cluster, and under Preview Types add a GraphQL Preview.

  3. Add a Name for your GraphQL Preview and set the Preview URL to the URL where your application is running.

  4. Set the Default Preview Type to the name of your GraphQL Preview and click Save.

Configuring CORS

Make sure that CORS settings are properly configured on your endpoint for the domain in which your application is running. For more information, see Cross-Origin Resource Sharing.

Configuring the front-end application

An application may only expect user input to result in resolution of a URL path to utilize in a data query. However, Brightspot's view system will actually send your application a preview ID, instead of a path, which is used to fetch the preview data for the Brightspot user's current content form. Therefore, your application must accept an id input for any top-level query field. Note that the id input can be used for preview IDs as well as normal record IDs.

Consider the following example GraphQL query:

query getPage($path: String) {
    Page(path: $path) {
        __typename
        ... on ArticlePage {
            headline
        }
        ... on SectionPage {
            title
        }
    }
}

To enable preview functionality, the query should be modified to accept an id input as well.

query getPage($id: ID, $path: String) {
    Page(id: $id, path: $path) {
        __typename
        ... on ArticlePage {
            headline
        }
        ... on SectionPage {
            title
        }
    }
}

The preview ID is sent to the application's URL via an HTTP previewId parameter on a request. Consider the following example Javascript example for handling a Brightspot preview request:

const previewId = new URLSearchParams(window.location.search).get('previewId')
const variables = previewId != null ? { id: previewId } : { path: window.location.pathname }

Your application can now supply the proper variables for the GraphQL query whether it is processing a preview request or not.

Verification

Open an Article in the CMS and click the "eye" icon to open the preview pane. You should see the name of your GraphQL Preview as the selected Preview type. When you make changes to the headline field of the Article, the preview will automatically update to reflect these changes.