Getting started with Ruby and the CMA

This post will walk you through your first steps in using Contentful Management API within your Ruby applications. We will provide simple steps to create and edit your resources and start using them. For that, we'll be building a simple blog system with posts, authors, assets and categories linked to the posts. Of course, the Contentful platform is capable of managing any content model you can dream up, blogs are just an easy to understand example.

Creating a blog space

Let's start with mapping out the type of items we need to publish a blog. A cursory glance will reveal that a standard blog post contains the following fields:

• Title
• Author
• Body
• Category
• Tags

In order to keep things manageable, we will create separate content types for author and category entries. Categories are simple, each blog category has two fields:

• Name
• Description

And each author entry will have the following fields:

• Name
• Bio
• Profile picture
• URL

When using media assets in Contentful keep in mind a simple rule of thumb: a single asset does not require a separate content type, since it is handled through the built-in asset type. All assets have a title and description field by default.

However, if you would like to organize assets into a gallery or need to display additional meta information beyond title and description, then we recommended creating a wrapper content type (e.g. a "gallery" content type) for your media assets and linking an entry of that type to your blog post.

Installation

First, you need to install our contentful-management gem. You can do it either manually on the console:

$ gem install contentful

Or you can add it inside your Gemfile:

gem 'contentful-management', '~> 2.0'

Once in your Gemfile, running bundle install will install the gem and all its dependencies.

Setting up your Contentful Management client

Once you have your gem installed, you can start using it inside your application.

For this example, we'll assume you have already created an account. You can fetch your management token from our authentication docs

Once you have the management token, you can create the client:

require 'contentful/management'

client = Contentful::Management::Client.new("YOUR_MANAGEMENT_TOKEN")

Creating content types

First, we are creating a new space to start from scratch:

Note: Creation of a space may result in additional charges if the free spaces available in your plan are exhausted.

space = client.spaces.create(name: 'Blog')

If you happen to be in more than one organization you need to specify an organization ID. The ID can be found in your account settings in the url once you selected the organization.

Before we can create posts we need to create the content types. A content type consists of an optional custom id, a name, a type and more fields that can be found in the documentation.

For the blog post itself we add the following fields:

post = space.environments('master').content_types.create(name: 'Post')
post.fields.create(id: 'title', name: 'Title', type: 'Text')
post.fields.create(id: 'body', name: 'Body', type: 'Text')

Setting the displayField to 'title' will cause the value of 'title' to be shown when listing entries on the Contentful web app.

post.update(displayField: 'title')

We follow the same procedure to create a content type for category entry:

category = space.environments('master').content_types.create(name: 'Category')
category.fields.create(id: 'name', name: 'Name', type: 'Text')
category.fields.create(id: 'description', name: 'Description', type: 'Text')
category.update(displayField: 'name')

Last but not least, we add a content type for authors:

author = space.environments('master').content_types.create(name: 'Author')
author.fields.create(id: 'name', name: 'Name', type: 'Text')
author.fields.create(id: 'bio', name: 'Biography', type: 'Text')
author.update(displayField: 'name')

Now we want to create a relation between blog posts and categories, authors and assets. To model one-to-many relationships we will be adding Array fields to our content types, and the items in those arrays will be a special Link type.

First we need to create standalone Link fields for categories and assets that will be linked to a post:

category_link = Contentful::Management::Field.new
category_link.type = 'Link'
category_link.link_type = 'Entry'

asset_link = Contentful::Management::Field.new
asset_link.type = 'Link'
asset_link.link_type = 'Asset'

The type specifies that we are dealing with a link, the _link_type_ describes what we are linking to. In this case we are linking to other entries and assets. Then we add Array fields to post content type:

post.fields.create(id: 'categories', name: 'Categories', type: 'Array', items: category_link)
post.fields.create(id: 'assets', name: 'Assets', type: 'Array', items: asset_link)

Finally, we add a field that links from the post to its author, because the author is not an array we can create the field directly through the content type.

post.fields.create(id: 'author', name: 'Post Author', type: 'Link', link_type: 'Entry')

At this point we have created the basic structure for our blog, but before we start creating entries we need to publish our content types:

post.publish
category.publish
author.publish

If you now take a look at the Contentful web app you will see your newly prepared space, with the well-defined post, category and author content types.

Creating Entries

Now lets get down to creating some categories:

categories = []
categories << category.entries.create(
  name: 'Misc',
  description: 'Misc stuff'
)
categories << category.entries.create(
  name: 'ContentManagement',
  description: 'Basics and principles about content.'
)
categories.map(&:publish)

And lets add an author whose name will appear in the blog post:

post_author = author.entries.create(
  name: 'Janine McKay ',
  bio: 'Technical writer and twitter ninja.'
)
post_author.publish

Now to create an actual post linked to the Misc and ContentManagement category:

post_entry = post.entries.create(
  title: 'First Post',
  body: 'Letterpress sustainable authentic, disrupt semiotics actually kitsch.'\
    ' Direct trade Cosby sweater Austin, Pitchfork flexitarian small batch'\
    ' authentic roof party 8-bit YOLO literally Neutra pour-over American Apparel'\
    ' dreamcatcher. High Life distillery cliche YOLO, flexitarian four loko put a'\
    ' bird on it plaid Marfa Shoreditch seitan Echo Park bicycle rights Pinterest PBR.'\
    ' Drinking vinegar Banksy gastropub, stumptown occupy farm-to-table Blue Bottle'\
    ' tattooed Truffaut single-origin coffee iPhone locavore pug. Blue Bottle cray'\
    ' quinoa farm-to-table Bushwick tousled. beard Kitschgit tousled, American Apparel'\
    ' XOXO vegan readymade Pitchfork church-key 3 wolf moon direct trade lo-fi.'\
    ' Food truck try-hard deep v salvia raw denim.'
)

Then link our categories array to our freshly created post:

post_entry.update(categories: categories)

To complete the post we want to upload an asset, create a link to it, and add an author:

image_file = Contentful::Management::File.new
image_file.properties[:contentType] = 'image/jpeg'
image_file.properties[:fileName] = 'example.jpg'
image_file.properties[:upload] = 'https://farm9.staticflickr.com/8144/6974761828_493d4dc28d_k_d.jpg'

asset = space.assets.create(
  title: "Unter den Linden",
  description: "A nice shot of the TV-Tower in Berlin",
  file: image_file
)
asset.publish

If we want to update an existing entry with additional links we have to include all of the existing links:

post_entry.update(categories: categories, assets: [asset], author: author)

The last step now is to publish the entry so we can fetch it through the Content Delivery API or view it in the web interface. Please note that entries in 'draft' state will not show up in the Content Delivery API.

post_entry.publish

You are invited to use the Delivery API Gem to fetch your first entries. You can also read our Getting Started With the CDA and Ruby Guide.

Summary

With this basic guide, you should be able to start using the Contentful Management API within your Ruby applications.

Once you have created your content types, publishing new entries and assets is fairly simple. For an example of setting up a more complex content model from scratch, we have built a script that imports the Open Beer Database, creating a structure with breweries, beers and beer styles and automatically linking them to each other.

You can find the script to try out and study on our Github account.

You can also check out how to get your spaces started with a single command using Contentful Bootstrap.

Further Reading

• Content Management API Documentation
• contentful-management.rb on Github
• contentful-management.rb on RubyGems
• contentful-management.rb Documentation
• Example Script using the Open Beer Database to create a space with multiple content types and entries.

License Attributions:

• Image Credits: Picture "Unter den Linden", Amira A License: Creative Commons 2.0