Skip to content

Commit 1a87a8a

Browse files
TylerBarnesTylerBarnes
authored
docs(gatsby-source-wordpress): document content sync (#32768)
* document new preview loader for WP
1 parent 417df15 commit 1a87a8a

File tree

3 files changed

+65
-70
lines changed

3 files changed

+65
-70
lines changed

‎packages/gatsby-source-wordpress/docs/features/preview.md

Lines changed: 5 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Preview
22

3-
This plugin supports [Preview](https://www.gatsbyjs.com/preview/) and has been designed to replicate the normal WordPress admin preview experience as closely as possible.
3+
This plugin supports [Preview](https://www.gatsbyjs.com/preview/) and has been designed to make the WordPress admin preview experience as seamless as possible.
44

55
## How Preview works
66

@@ -10,35 +10,14 @@ When configured properly by a developer, preview should function almost identica
1010

1111
You can find our tutorial on setting up WPGatsby [here](../tutorials/configuring-wp-gatsby.md#setting-up-preview). Part-way down the page there are instructions you can follow on setting up Preview.
1212

13-
## File System Route API
13+
## Debugging the build process of Previews
1414

15-
The [File System Route API](https://www.gatsbyjs.com/docs/reference/routing/file-system-route-api/) is not currently supported with WP Previews because it does not call the `onCreatePage` API which this plugin relies on. Follow [this issue](https://github.com/gatsbyjs/gatsby/issues/29361) for updates or [vote for this feature](https://gatsby.canny.io/gatsby-cloud/p/support-filesystem-route-api-alongside-gatsby-source-wordpress).
15+
If you enable the plugin option `options.debug.preview` by setting it to `true`, you will see additional logging through the Preview build process with information such as the contents of the webhook body that was sent to Gatsby, the preview node data, and the list of preview actions that were pulled from WordPress. See the [plugin options](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/docs/plugin-options.md#debugpreview) documentation for more info.
1616

1717
## Gutenberg and ACF
1818

1919
Note that if you use these two together, you cannot preview ACF data. This is a core WordPress Gutenberg issue. Follow https://github.com/WordPress/gutenberg/issues/16006 for more information. If you use ACF and would like to preview data changes, use the Classic Editor plugin for now.
2020

21-
## Template safety
22-
23-
Be sure to guard against missing data in your templates using optional chaining so that missing data doesn't cause template errors. Trying to access properties on undefined will break your preview. For example, if you try to access `wpPost.acfFieldGroup.hero.content` but your Preview template receives `null` for `wpPost.acfFieldGroup`, your preview template will break.
24-
25-
To guard against this you can use optional chaining by writing `wpPost?.acfFieldGroup?.hero?.content` instead.
26-
27-
## Debugging Previews in React
28-
29-
Since a Previewed post might have a lot less data attached to it than what you're testing with during development, you might get errors in previews when that data is missing. You can debug your previews by running Gatsby in preview mode locally.
30-
31-
- Run Gatsby in refresh mode with `ENABLE_GATSBY_REFRESH_ENDPOINT=true gatsby develop`
32-
- Install ngrok with `npm i -g ngrok`
33-
- In a new terminal window run `ngrok http 8000`
34-
- In your WP instance's GatsbyJS settings, set your Preview instance URL to `https://your-ngrok-url.ngrok.io` and your Preview webhook to `https://your-ngrok-url.ngrok.io/__refresh`
35-
36-
Now when you click the preview button in `wp-admin` it will use your local instance of Gatsby. You can inspect the preview template to see which Gatsby page is being loaded in the preview iframe and open it directly to do further debugging.
37-
38-
## Debugging the build process of Previews
39-
40-
If you enable the plugin option `options.debug.preview` by setting it to `true`, you will see additional logging through the Preview build process with information such as the contents of the webhook body that was sent to Gatsby, the preview node data, and the list of preview actions that were pulled from WordPress. See the [plugin options](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/docs/plugin-options.md#debugpreview) documentation for more info.
41-
4221
## Common gatsby-node.js problems that break previews
4322

4423
### 1. When querying for nodes, the previewed node is filtered out
@@ -85,42 +64,7 @@ exports.createPages = async ({ graphql }) => {
8564
}
8665
```
8766

88-
### 2. Not including the node id in pageContext
89-
90-
It is currently a hard requirement that the node id is added to pageContext.
91-
92-
```js
93-
exports.createPages = async ({ graphql, actions }) => {
94-
const graphqlResult = await graphql(/* GraphQL */ `
95-
query {
96-
allWpPost {
97-
edges {
98-
node {
99-
id
100-
uri
101-
}
102-
}
103-
}
104-
}
105-
`)
106-
107-
graphqlResult.data.allWpPost.edges.map(({ node }) => {
108-
actions.createPage({
109-
path: node.uri,
110-
component: require.resolve(`./src/components/dog.js`),
111-
context: {
112-
id: node.id, // if this is not included, previews will not work.
113-
},
114-
})
115-
})
116-
}
117-
```
118-
119-
### 3. Context stuffing
120-
121-
Some sites circumvent using page queries by querying for all data in `gatsby-node.js` and passing the result as page context data when calling `createPage`. This breaks previews and incremental builds and is discouraged. You should only make GraphQL queries for page data in [page queries](https://www.gatsbyjs.com/docs/recipes/querying-data#querying-data-with-a-page-query).
122-
123-
### 4. Using createPagesStatefully
67+
### 2. Using createPagesStatefully
12468

12569
The correct Node API for creating pages is [`createPages`](https://www.gatsbyjs.com/docs/reference/config-files/gatsby-node/#createPages), using `createPagesStatefully` will prevent previews from working.
12670

@@ -180,7 +124,7 @@ The preset (as found in src/models/gatsby-api.ts) is:
180124

181125
## How Preview works behind the scenes
182126

183-
When the WP "preview" button is pressed, a JWT is generated (with an expiry time of 1 hour) and POST'ed to the Gatsby Preview instance webhook. The Preview instance then uses this short-lived JWT to request a list of pending previews for all users. Gatsby starts processing each pending preview. At the same time, WordPress automatically opens the WP preview template which has been overridden by WPGatsby. Within the WP preview template you will see the admin bar at the top of the page as usual. The WordPress preview template displays a loader and waits for Gatsby to send back the preview status for the preview you're observing - it will receive a response when the preview has been processed on the Gatsby side. On the Gatsby side, it matches up the node being previewed with the Gatsby page that was created from it, once that page has been updated or created, it sends back the Gatsby page path for that page. WordPress then starts watching for the changed page to be deployed. Once it's deployed, the WordPress preview template loads the right Gatsby page in an iframe and removes the loader. In the case that there are errors on the Gatsby side, or no page is created for the node that's being previewed, Gatsby will send back an appropriate status and WPGatsby will display an error in the browser with instructions on how to resolve the issue.
127+
When the WP "preview" button is pressed, a JWT is generated (with an expiry time of 1 hour) and POST'ed to the Gatsby Preview instance webhook. The Preview instance then uses this short-lived JWT to request a list of pending previews for all users. Gatsby starts processing each pending preview. At the same time, WordPress automatically opens the WP preview template which has been overridden by WPGatsby to redirect to Gatsby Cloud's Content Sync service. This service handles the loading/error states and will redirect the user to the right page when it's been built.
184128

185129
## Preview Security Considerations
186130

‎packages/gatsby-source-wordpress/docs/tutorials/configuring-previews-legacy.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
## Setting Up Preview
2+
3+
Once configured in the GatsbyJS settings page in wp-admin, Previews will work out of the box as long as your Gatsby pages have the corresponding node id as part of their pageContext. See [this starter's gatsby-node.js](https://github.com/gatsbyjs/gatsby/blob/master/starters/gatsby-starter-wordpress-blog/tree/master/gatsby-node.js) for an example of how to set up your Gatsby pages. See the [feature page on Preview](../features/preview.md) for more information about how Preview works, considerations you should keep in mind while writing Preview-ready templates, and how to debug Preview templates.
4+
5+
### Connecting Preview
6+
7+
To get started, set up a Preview instance on [Gatsby Cloud](https://www.gatsbyjs.com/) or set up your [self-hosted Preview instance](https://www.gatsbyjs.org/docs/running-a-gatsby-preview-server/). If you want to try out Preview but aren't sure whether you want to subscribe to Gatsby Cloud or self-host, you can start a free 2 week Gatsby Cloud trial with no credit card to help you make up your mind!
8+
9+
#### WordPress Settings
10+
11+
Navigate to your GatsbyJS WordPress settings by visiting this path in your WP instance `/wp-admin/options-general.php?page=gatsbyjs` or by hovering on "Settings" in the WordPress admin menu and clicking on "GatsbyJS".
12+
13+
You will see 4 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Preview Instance", "Preview Webhook", and "Preview JWT secret".
14+
15+
If you don't see this settings page, or you don't see these 4 fields, make sure the latest version of [WPGatsby](https://github.com/gatsbyjs/wp-gatsby) is installed in your WordPress instance.
16+
17+
![wp-gatsbyjs-preview-settings](../../docs/assets/wp-gatsbyjs-preview-settings.png)
18+
19+
#### 1. Check the "Enable Gatsby Preview?" Checkbox
20+
21+
When this checkbox is checked, WPGatsby will override the functionality of the WordPress "preview" button in the page/post edit screen. Clicking "preview" will open the regular WordPress preview template, but the WP frontend will be replaced with your Gatsby Preview instance.
22+
23+
#### 2. Fill the "Preview Instance" Field
24+
25+
This field should be filled with the public frontend URL of your Gatsby Preview instance.
26+
27+
To find your **Preview Instance URL**, navigate to the "Preview" tab in [Gatsby Cloud](https://www.gatsbyjs.com/dashboard/sites), wait for your first Preview build to complete, and then copy the frontend URL from above the build history list in the center of the page.
28+
29+
![Gatsby Cloud Preview frontend URL Screenshot](../../docs/assets/gatsby-cloud-preview-frontend-url.png)
30+
31+
#### 3. Fill the "Preview Webhook" Field
32+
33+
You can find your **Preview webhook** by navigating to "Site Settings" in Gatsby Cloud and then navigating to "Webhooks" via the left-side menu.
34+
35+
![Gatsby Cloud Preview Webhook URL](../../docs/assets/gatsby-cloud-preview-webhook-url.png)
36+
37+
#### 4. Double check the "Preview JWT secret" field
38+
39+
This field should be filled for you automatically with a cryptocraphically secure key when you install WPGatsby. If this field is empty, feel free to copy a salt from the [WordPress salts generator page](https://api.wordpress.org/secret-key/1.1/salt) and use that as your JWT secret key.
40+
41+
This secret key is used to authenticate short-lived JWT tokens when you're viewing previews from WordPress so a very strong key should be used to prevent security issues.
42+
43+
### Using your Preview
44+
45+
Now that you've configured WPGatsby for your Preview instance, visit a page or post you'd like to preview, edit it, and press "preview" in the top right corner of the edit screen like you usually would in WordPress. You should see a new tab pop open with your Preview instance and previewed content visible!
46+
47+
:point_left: [Back to Features](./index.md)

‎packages/gatsby-source-wordpress/docs/tutorials/configuring-wp-gatsby.md

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -27,17 +27,19 @@ Now that your Builds webhook is set up, when content is updated in WordPress you
2727

2828
## Setting Up Preview
2929

30-
Once configured in the GatsbyJS settings page in wp-admin, Previews will work out of the box as long as your Gatsby pages have the corresponding node id as part of their pageContext. See [this starter's gatsby-node.js](https://github.com/gatsbyjs/gatsby/blob/master/starters/gatsby-starter-wordpress-blog/tree/master/gatsby-node.js) for an example of how to set up your Gatsby pages. See the [feature page on Preview](../features/preview.md) for more information about how Preview works, considerations you should keep in mind while writing Preview-ready templates, and how to debug Preview templates.
30+
Once configured in the GatsbyJS settings page in wp-admin, Previews will work out of the box. See the [feature page on Preview](../features/preview.md) for more information about how Preview works. WPGatsby has been updated to use Gatsby Cloud's new Content Sync service, which is a service that handles the loading view, error handling, and redirection for users that are previewing content. Make sure you've upgraded to the latest versions of WPGatsby, `gatsby`, and `gatsby-source-wordpress`. For documentation about legacy previews where the preview loader used to live on the WordPress side [see here](./configuring-previews-legacy.md).
31+
32+
Note that this feature will work on the latest version of Gatsby but will be more reliable on `gatsby@3.13.0-alpha-node-manifests.26`.
3133

3234
### Connecting Preview
3335

34-
To get started, set up a Preview instance on [Gatsby Cloud](https://www.gatsbyjs.com/) or set up your [self-hosted Preview instance](https://www.gatsbyjs.org/docs/running-a-gatsby-preview-server/). If you want to try out Preview but aren't sure whether you want to subscribe to Gatsby Cloud or self-host, you can start a free 2 week Gatsby Cloud trial with no credit card to help you make up your mind!
36+
To get started, set up a Preview instance on [Gatsby Cloud](https://www.gatsbyjs.com/).
3537

3638
#### WordPress Settings
3739

3840
Navigate to your GatsbyJS WordPress settings by visiting this path in your WP instance `/wp-admin/options-general.php?page=gatsbyjs` or by hovering on "Settings" in the WordPress admin menu and clicking on "GatsbyJS".
3941

40-
You will see 4 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Preview Instance", "Preview Webhook", and "Preview JWT secret".
42+
You will see 5 fields related to Gatsby Preview. "Enable Gatsby Preview?", "Use Gatsby Content Sync?", "Content Sync URL", "Preview Webhook", and "Preview JWT secret".
4143

4244
If you don't see this settings page, or you don't see these 4 fields, make sure the latest version of [WPGatsby](https://github.com/gatsbyjs/wp-gatsby) is installed in your WordPress instance.
4345

@@ -47,21 +49,23 @@ If you don't see this settings page, or you don't see these 4 fields, make sure
4749

4850
When this checkbox is checked, WPGatsby will override the functionality of the WordPress "preview" button in the page/post edit screen. Clicking "preview" will open the regular WordPress preview template, but the WP frontend will be replaced with your Gatsby Preview instance.
4951

50-
#### 2. Fill the "Preview Instance" Field
52+
#### 2. Check the "Use Gatsby Content Sync?" Checkbox
53+
54+
When this checkbox is checked, WPGatsby will use the new Gatsby Cloud Content Sync service for previews. Instead of WPGatsby handling loading previews and redirecting to the right page, Gatsby Cloud will now do it instead. This is optional but recommended as this will become the default in the future and [legacy previews](./configuring-previews-legacy.md) will be removed.
5155

52-
This field should be filled with the public frontend URL of your Gatsby Preview instance.
56+
#### 3. Fill the "Gatsby Content Sync URL" Field
5357

54-
To find your **Preview Instance URL**, navigate to the "Preview" tab in [Gatsby Cloud](https://www.gatsbyjs.com/dashboard/sites), wait for your first Preview build to complete, and then copy the frontend URL from above the build history list in the center of the page.
58+
This field should be filled with the Content Sync URL of your Gatsby Preview instance.
5559

56-
![Gatsby Cloud Preview frontend URL Screenshot](../../docs/assets/gatsby-cloud-preview-frontend-url.png)
60+
To find your **Content Sync URL**, navigate to the "Site Settings" tab in [Gatsby Cloud](https://www.gatsbyjs.com/dashboard/sites), scroll down until you see the "Content Sync URL", and copy the URL displayed there.
5761

58-
#### 3. Fill the "Preview Webhook" Field
62+
#### 4. Fill the "Preview Webhook" Field
5963

6064
You can find your **Preview webhook** by navigating to "Site Settings" in Gatsby Cloud and then navigating to "Webhooks" via the left-side menu.
6165

6266
![Gatsby Cloud Preview Webhook URL](../../docs/assets/gatsby-cloud-preview-webhook-url.png)
6367

64-
#### 4. Double check the "Preview JWT secret" field
68+
#### 5. Double check the "Preview JWT secret" field
6569

6670
This field should be filled for you automatically with a cryptocraphically secure key when you install WPGatsby. If this field is empty, feel free to copy a salt from the [WordPress salts generator page](https://api.wordpress.org/secret-key/1.1/salt) and use that as your JWT secret key.
6771

0 commit comments

Comments
 (0)