contentful.rb
Ruby client for the Contentful Content Delivery API.
Contentful is a content management platform for web applications, mobile apps and connected devices. It allows you to create, edit & manage content in the cloud and publish it anywhere via powerful API. Contentful offers tools for managing editorial teams and enabling cooperation between organizations.
Setup
Add to your Gemfile and bundle:
gem 'contentful'
Usage
client = Contentful::Client.new(
access_token: 'b4c0n73n7fu1',
space: 'cfexampleapi'
)
You can query for entries, assets, etc. very similar as described in the Delivery API Documentation. Please note, that all methods of the Ruby client library are snake_cased, instead of JavaScript's camelCase:
client.content_types
client.entry 'nyancat'
You can pass the usual filter options to the query:
client.entries('sys.id[ne]' => 'nyancat') # query for all entries except 'nyancat'
client.entries(include: 1) # include one level of linked resources
The results are returned as Contentful::Resource objects. Multiple results will be returned as Contentful::Array. By combining skip and limit you can achieve pagination:
client.entries(skip: 0, limit: 15) # page 1
client.entries(skip: 15, limit: 30) # page 2
client.entries(skip: 30, limit: 45) # page 3 etc.
The properties of a resource can be accessed through Ruby methods. Alternatively the data can be accessed as Ruby Hash.
content_type = client.content_type 'cat'
content_type.description # "Meow."
content_type.properties # { name: '...', description: '...' }
System Properties behave in the same way and can be accessed with the #sys method.
content_type.id # => 'cat'
entry.type # => 'Entry'
asset.sys # { id: '...', type: '...' }
Entry Fields usually don't have direct method accessors, since they are based on individual content types. These fields can be accessed through the #fields method.
entry = client.entry 'nyancat'
entry.fields[:color] # rainbow
Dynamic Entries
However, you can set :dynamic_entries to :auto in your client configuration (see below). If using this option, the client will fetch all available content types and use them to create dynamic entries on the fly.
client = Contentful::Client.new(
access_token: 'b4c0n73n7fu1',
space: 'cfexampleapi',
dynamic_entries: :auto,
)
client.entry 'nyancat' # => #<Contentful::DynamicEntry[cat]: ...>
The previous example fetches all content_types on initialization. If you want to do it by hand, you will need to set the option to :manual and call client.update_dynamic_entry_cache! to fetch all content types.
Links
You can easily request a resource that is represented by a link, by calling #resolve:
happycat = client.entry 'happycat'
happycat.fields[:image]
# => #<Contentful::Link: @sys={:type=>"Link", :linkType=>"Asset", :id=>"happycat"}>
happycat.fields[:image].resolve # => #<Contentful::Asset: @fields={ ...
Assets
There is a helpful method for adding the image resize options for an asset image:
client.find('happycat').image_url
# => "//images.contentful.com/cfexampleapi/3MZPnjZTIskAIIkuuosCss/382a48dfa2cb16c47aa2c72f7b23bf09/happycatw.jpg"
client.find('happycat').image_url width: 300, height: 200, format: 'jpg', quality: 100
# => "//images.contentful.com/cfexampleapi/3MZPnjZTIskAIIkuuosCss/382a48dfa2cb16c47aa2c72f7b23bf09/happycatw.jpg?w=300&h=200&fm=jpg&q=100"
Configuration Options
:space
Required option. The name of the space you want to access.
:access_token
Required option. The space's secret token.
:secure
Whether to use https. Defaults to true.
:authentication_mechanism
How to authenticate with the API. Supports :header (default) or :query_string.
:raise_errors
If set to true (default), error responses will be raised. If set to false, the error objects will simply be returned.
:dynamic_entries
false, :auto or :manual. See resource description above for details on usage.
:raw_mode
Defaults to false. If enabled, the API responses will not be parsed to resource objects. Might be useful for debugging.
Advanced
Dynamic Entries
In :dynamic_entries mode (see above), all entries are returned as specialized entry classes. However, you can also create these specialized classes by yourself, based on a content_type:
content_type = client.content_type 'nyancat'
MyEntry = Contentful::DynamicEntry.create(content_type)
It is also possible to pass in the raw content_type JSON string, as returned from the api. See the RDOC for more details.
License
Copyright (c) 2014 Contentful GmbH - Jan Lelis. See LICENSE.txt for further details.