Contentful Express Tutorial #01

Contentful is a developer focused Content Management System that provides an infrastructure to easily create and distribute content. With a variety of API's that are integratable with a huge variety of platforms, providing an extremely easy to use client and having a gob smackingly generous free tier to top it off. Contetntful is definitely a solution for lightweight websites and web apps that provide useful content! I was also pleasantly surprised by the platform specific documentation provided, making it a pretty easy to get started with your preferred stack.

In these tutorials I'll show you just how easy it is to get up and running with contentful by building an example blog using Express JS (node). Before beginning though, this tutorial assumes that you have a basic knowledge of NodeJS and Node Package Manager. So if any of this seems completely alien to you I would advise heading over to nodejs.org and getting familiar with the node ecosystem. For those who are set up, let's get to it!

Step 1: Contentful Account

Before getting started it's important to take note of some jargon used by Contentful:

  • Space: Spaces can essentially be thought of as contained groups of content and assets that serve a particular purpose. All content editing is done on a Space level.
  • Organisations: Organisations act as a wrapper for Spaces. They are used for management purposes. Example deleting and updating spaces.

With these terms in mind head over to Contentful.com, and create an account. Once you are set up we can move on to creating a space.

Step 2: Creating a Space

Now we'll create our first space. Contentful provides the option to set up what they refer to as an example space. This is simply the option to create some boilerplate content, as a way to get familiar with how Contentful works. For this tutorial we'll be working off their Blog example space. So click 'Add Space' and select 'Create and example space' and the pick the Blog option. You should see:

Screen Shot 2018-01-27 at 11.27.04

Once you've hit 'Create Space' take a quick look around to get familiar with it. Under the 'Content Model' tab you can see how the space's content is separated into three categories: Author, Post & Category. You can also see how many fields are available and when they were last updated. Likewise, under the 'Content' tab you can see all the content available in this space. Here is where you can edit, create and delete your content.

Step 3: Creating an Express Project

Next up we'll need to create an express project to work with. For the sake of convenience in this Tutorial I'm going to use the Express Application Generator, a tool used to quickly create bare bones Express projects. This allows us to get up and running quickly with just a few commands:


  $ npm i express-generator -g
  $ express --view=pug contentful-tutorial
  $ cd contentful-tutorial
  $ npm i
  $ npm start

Open up a browser tab and head to localhost:3000 and you should see a 'welcome to express'. Now we have the foundation of what we are going to build our app on, and everything we need to actually start using the Contentful delivery API.

Step 4: Integrating Contentful

To set up the Contentful client we'll need to create a "service script". Do this by following the commands below:

  
    $ npm i contentful
    $ mkdir services
    $ touch services/contentfulClient.js
  

Open up the contentfulClient.js file and paste the following code:

  
    var contentful = require('contentful');

    var client = contentful.createClient({
      space: 'space_id',
      accessToken: 'access_token'
    });
  

You can find the space_id and access_token values in your space by selecting the API's tab and selecting the website key. If this is your first space it will simply be called 'Website Key', or if it was your second it would be 'Website Key 1' and so on. Scroll down and you should see something like:

Screen Shot 2018-01-28 at 11.31.22

To run the script with our application go the the app.js file in the root of the express project and require it:

  
  var contentfulClient = require('./services/contentfulClient');

Note: These tokens are for an example space I created for this tutorial so there's no harm in them being public.

Step 5: Making an API Call

Now that we have a our credentials all set up we can retrieve data from our space. To start we'll retrieve a single blog post. Go to the 'Content' tab and select the 'Down the Rabbit Hole' post. There select the 'Info' button located at the top right corner of the screen. You should now see this:

Screen Shot 2018-01-28 at 12.04.25

Copy the 'ENTRY ID' value, then add the following code to the contentfulClient.js script in the place of 'entry_id' paste the value.

  
    client.getEntry('entry_id')
      .then(function (entry) {
        console.log(entry.fields.title) //log post title
      });
  

The code above will retrieve a single entry via the entry id and log the title. Now start the application and you should see the title of the blog post logged inthe terminal:

Screen Shot 2018-01-28 at 12.25.09

And that's it! if you for some reason get an error be sure to review the previous steps.

Summary

So in the first part of this tutorial we created blog content and used Contentful's delivery API to retrieve that content and output it in our Express project. In the second part I will show you how to retrieve an entire post and display it on the frontend using Pugjs. I hope this tutorial was helpful and if there are any questions feel free to reach out. Thanks for reading!