roots-contentful

Roots Contentful

An extension for using roots with the Contentful CMS API.

Note: This project is in early development, and versioning is a little different. Read this for more details.

Why Should You Care?

We love static sites. They're fast, resilient, simple, and cheap.

However, managing and updating content on a static site is a pain. This extension allows you to load data from Contentful's API into your roots project for use in your view templates during compilation. Non-developers get an easy way to publish and manage content, while developers can still build static sites in a sane way.

Installation

• make sure you are in your roots project directory
• npm install roots-contentful --save
• modify your app.coffee file to include the extension, as such

contentful = require 'roots-contentful'

# ...

module.exports =
  extensions: [
    contentful({
      access_token: 'YOUR_ACCESS_TOKEN'
      space_id: 'xxxxxx'
      content_types: [
        {
          id: 'xxxxxx',
          name: 'posts',
          template: 'views/_post.jade',
          filters: {
            'fields.environment[in]': ['staging', 'production']
          },
          path: (e) -> "blogging/#{e.category}/#{slugify(e.title)}"
        },
        {
          id: 'xxxxxx'
        }
      ]
    })
  ]

# ...

Usage

Accessing Content in Views

A contentful view helper object will be passed into every view containing your content. Each content type will be set as a property on contentful using the name option in your app.coffee configuration. For example with the app.coffee file above, you can access the blog posts like this:

  h1 Hello World
  ul
    - for post in contentful.posts
      li
        h2= post.title
        p= markdown(post.body)

Single Entry Views

Note: This feature is currently not implemented, but is planned for a future release.

If a template option is defined for a Content Type in app.coffee, roots will compile a single page view for each entry in that Content Type collection. The entry will also have a _url key that returns the path to the single page view (so you can create links on an index page for example).

The Entry Object

Contentful's documentation shows the API response when fetching an entry. Your content fields are nested in a fields key. As a convenience, the entry object roots-contentful makes available in your views will have the fields key's value set one level higher on the object. System metadata remains accessible on the sys key and roots-contentful will raise an error if you have a field named sys. Inside your views, the entry object will have this structure:

{
  "title": "Wow. Such title. Much viral",
  "author": "The Doge of Venice"
  # ... the rest of the fields
  "sys": {
    "type": "Entry",
    "id": "cat"
    # ...
  }
}

Configuration Options

access_token

Required. Your Contentful Delivery access token (API key).

space_id

Required. The space ID containing the content you wish to retrieve.

content_types

An array of objects specifying from which Content Types you wish to fetch entries.

Configuring a content_type

Each object in the content_types array can have the following properties:

id

Required. The Content Type's ID on Contentful.

name

Optional. This is the name of the key the entries will be attached to on the contentful object in your views. Defaults to a pluralized, underscored representation of the Content Type name (e.g. 'Blog Post' => contentful.blogPosts)

template

Optional. Path relative to the roots project of a template for a single entry view. Each entry in the Content Type will be passed into the template in an entry variable. If not given, the Content Type will not be compiled into single entry views and will only be attached to the contentful view helper object.

filters

Optional. Takes an object with different filter criteria, see examples of how to structure the object in Contentful's docs.

path

Optional. Provide a function that returns a string of the relative path to the output file for a given entry without the extension. First argument passed into the function is the entry. Default is <name>/<slug> where slug is the slugified output of the entry's displayField (a property of the Content Type), and name is the provided name option above or the default value. This option is ignored if no template is given.

License & Contributing

• Details on the license can be found here
• Details on running tests and contributing can be found here