Introducing the Content Management Gem
It has been a long time in the making, but today we are happy to announce the release of a Ruby Gem for working with our Content Management API (CMA). The Management API is used for creating and editing your content on the Contentful platform, while the Delivery API is used to publish that content to a variety of devices.
This post will illustrate how to use the Ruby Gem in practice, by walking you through the process of 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.
The management library is still under heavy development and we are working hard to add more and more features, but we hope that this basic version will give you a taste of things to come as well as encourage you to experiment with integrating Contentful into your Ruby-run projects.
We are very interested in your feedback and ideas. Feel free to drop us a line at support@contentful.com or open an issue on Github.
Please note that all code samples can be used in an Interactive Ruby Session (IRB)
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
It is always a good idea to plan ahead when designing the model for your content types, since changing it after creating entries can be a lot of work. For a better understanding of how to structure your data, I recommend our earlier Webinar on advanced Content Modeling.
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.
Installing
Now let's install the RubyGem. You can either install it system-wide
or add it to your Gemfile
and run
Depending on how you use it you might want to require the library.
The gem is compatible with all major Ruby versions including jRuby 1.9.
Creating Content Types
After you successfully installed the library you need to create a client object. For this you need to obtain a Management API token. A token can easily be obtained through the Documentation.
We are creating a new space to start from scratch:
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:
Setting the displayField to 'post_title' will cause the value of 'post_title' to be shown when listing entries on the contentful.com user interface.
We follow the same procedure to create a content type for category entry:
Last but not least, we add a content type for author entry:
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:
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:
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.
At this point we have created the basic structure for our blog, but before we start creating entries we need to activate our content types:
If you now take a look at the Contentful web interface 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:
And lets add an author whose name will appear in the blog post:
Now to create an actual post linked to the Misc and ContentManagement category:
Then link our categories array to our freshly created post:
To complete the post we want to upload an asset, create a link to it, and add an author:
If we want to update an existing entry with additional links we have to include all of the existing links:
The last step now is to publish the entry so we can fetch it through the Delivery API or view it in the web interface. Please note that entries in 'draft' state will not show up in the Delivery API.
You are invited to use the Delivery API Gem to fetch your first entries.
Summary
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.
Further Reading
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
