Aiki x Developer

contentful

Contentful Preview API (CPA) with Gatsby

June 23rd, 2019

contentful

Hiya, it's Arisa, a freelance Full-Stack & Frontend Developer living in Germany 🇩🇪

I like Contentful and this blog is also powered by Contentful.

Wordpress or other CMS require theme templates but Contentful doesn't require templates.

Instead, we can build the content structure as we imagine.

Wordpress or other CMS are more for "packages" which has features already in there and users don't need to build a theme by themselve if they don't want to write programming.

But it has limitations when users want to edit from dashboard and loading speed is slow. Also, I insist CMS is not developer friendly...!

Contentful is more for "white art boards" where you can draw any structures you want. Users can change contents frequently and fast when once programmers customize for them.

There is almost no limits if users want to edit from the dashboard after their apps are fully customized by developers. And the most important, it's developer friendly ✨

But how limitless?

Let's say there is an editor coming and asking you.

"Hey, Wordpress has a preview feature but our Contentful app doesn't have one. Can you make this feature?"

Of course, we can!

And a preview feature is one of the highly demanded feature for editors and users.

Let's rock it!💻

Add 'preview.contentful.com' as a host value in a config file

I developed this blog with Gatsby.

In the official Youtube from Contentful, you see they show you a case to apply preview feature with Nuxt which I personally feel the code looks slightly similar with Gatsby.

Bits & Bytes Ep. 7 - Creating a preview environment using the Preview API > https://www.youtube.com/watch?v=d-xo_2NL44M

I'll talk about the case when you develop the Contentful web app with Gatsby.

At this point, I assume you already built your web app with Gatsby with the blog post feature.

(Preview API is made for blog preview.)

Also, you already have an account from Contentful and enabled content access from Access Token API key and Space ID API key and seeing your blog posts are working.

Before you get start, make sure you installed the Gatsby package, gatsby-source-contentful.

In the config file(gatsby-config.js), add a host property with the value of 'preview.contentful.com'.

preview-config

Change Access Token API key to Preview API key

This is what I took time a bit unexpectedly.

https://www.gatsbyjs.org/packages/gatsby-source-contentful/#configuration-options

In Gatsby's documments, you find they wrote a very important thing about the accessToken.

The accessToken is a Contentful Delivery API key.

When you enable the content access from Contentful into your Gatsby web app, you need to put your Access Token API key in accessToken property's value in a config file.

That's the first step to check whether your web app is getting the content through API from Contentful or not.

But if you want to add the Preview feature, use your Preview API key, not your Access Token API key.

I didn't realize that while I was struggling with only getting a return as a 404 page.

But the error log from the command line was asking me to check whether my accessToken value is right one or not.

At this point, if you're good at guessing, yup, you need to also change the Access Token API value you set up in Netlify too.

Go to the 'Settings', then in 'Build & Deploy' section from the sidebar, you find the variables you set up if you already have deployed your Gatsby & Contentful web app.

If not, you need to create Preview API key and Space ID API key into each variables and set in Netlify's Settings section.

netlify-tokens

Settings > Content Preview > Add Content Preview

Go to your Contentful Dashboard.

In a header menu, you find a 'Settings' and click the 'Content Preview.'

You'll be asked to name the preview for your blog post content.

Name anything as long as you can guess which preview feature.

Write a description to explain which content preview.

In the bottom of the screen, you'll find a 'Content preview URLs' section.

This URL could be a bit different depends on whether you prefer local environment or online environment to see your previews.

Choice 1: Set up the Content Preview URLs (the online environment)

If you prefer to see your preview in an online, you need to insert your domain URL.

contentful-preview-settings

Which means, you need to have one already and linked to your Gatsby web app.

You can set up that easily in Netlify.

I know you wondered what's the path I have after my domain.

Here is the magic.

When you see the right sidebar, there is the answer written.

I used the case of 'Entry fields.'

It depends on the path you set up to display your blog posts and in my case, I have a structure like this.

https://my-domain-url.com/blog/slug

The /blog/ path is the one I set up from gatsby-node.js when creating pages like blog posts.

And /slug is the fileds from the content model I created for blog posts from Contentful.

GraphQl catches them up, and this slug is everytime different for each blog posts I create.

When I structured my content model with fields like this, it fits with the case they explained in 'Entry fields.'

Therefore, the URL path includes this curly braces part.

https://mydomai-url.com/blog/{entry_field.slug}/

Choice 2: Set up the Content Preview URLs (the local environment)

If you prefer to see youre preview in local environment with your local host, this is the right way.

When I explained the way to see the preview in online, you recognized you need to have a domain and already wired up your web app with your domain.

That's the way for already in production and after deployed your web app.

But there is also the way for development mode.

You just insert your local host URL and use the choice suits to your content fields like the example from seeing preview in online.

For your information, the official tutorial from Contentful is showing us this case.

Push to a Git repo & deploy in Netlify

In my case, I normally develop web apps with Netlify then I talk mainly about the case you use Netlify.

If you're ready to deploy your web app or already have deployed one and added online preview feature, simply push into your Git repo and deploy to your Netlify.

After you pushed your web app into a Git repo, just hit the 'Clear cache and deploy site' from Netlify dashboard.

If you haven't yet deployed your web app, and want to deploy to make your app in online, wire up your domain with your web app by deploying in Netlify.

You can choose later whether you change to an online preview or not.

Notes

At this point, I haven't yet applied the Netlify - Build manually UI extension.

I assume this is why Contentful Preview is not updated in live online unless I deploy and clear cache from Netlify.

... Maybe 😶

Also, this preview feature is only available to the draft status blog post.

Means if you already published, you can't preview, only edit.

Summary

This preview feature is very nice to editors and developers.

Contentful provides the needs from editors and for developers.

Editors get what their posts look like before putting into a public.

Developers can make the exact feature what editors asked them to make their work being productive.

I imagine if it was a CMS like Wordpress, I can work on it if editors ask me to add some features but it's not as easy as Contentful.

As long as you can set up a bit of preview path in Contentful dashboard and set the Preview API in the framework and the server, you're all set✨

The other thing I liked the Preview API from them is the documments and the Youtube sources were very helpful.

I didn't have to Googling around what the other people found the way from poor documments.

There are lots more things to discover and play around.

Hope this blog post was helpful for you.

Ciao!

Resources:

Contentful and Gatsby Documments:

Preview API > https://www.contentful.com/developers/docs/references/content-preview-api/

GatsbyJS and Contentful in five minutes > https://www.contentful.com/r/knowledgebase/gatsbyjs-and-contentful-in-five-minutes/

Content Preview > https://www.contentful.com/r/knowledgebase/setup-content-preview/

Setting a default preview environment > https://www.contentful.com/developers/docs/tutorials/general/content-preview/

gatsby-source-contentful > https://www.gatsbyjs.org/packages/gatsby-source-contentful/#configuration-options

Environment Variables > https://www.gatsbyjs.org/docs/environment-variables/

Contentful Youtube channel:

Bits & Bytes Ep. 7 - Creating a preview environment using the Preview API > https://www.youtube.com/watch?v=d-xo_2NL44M