Contentful Middleman is a Middleman extension to use the Middleman static site generator together with the API-driven Contentful CMS. It is powered by the Contentful Ruby Gem.

Experience the power of Middleman while staying sane as a developer by letting end-users edit content in a web-based interface.

The main release works for Middleman v3 - The most used version

If you are using Middleman v4, consider trying out our experimental branch. Feel free to communicate with us if you are experiencing any bugs.

Add the following line to the Gemfile of your Middleman project:

gem "contentful_middleman"

Then as usual, run:

bundle install

Run middleman contentful in your terminal. This will fetch entries for the configured spaces and content types and put the resulting data in the local data folder as yaml files.

The contentful command has a --rebuild option which will trigger a rebuild of your site only if there were changes between the last and the current import.

To configure the extension, add the following configuration block to Middleman's config.rb:

activate :contentful do |f|
  f.space         = SPACE
  f.access_token  = ACCESS_TOKEN
  f.cda_query     = QUERY
  f.content_types = CONTENT_TYPES_MAPPINGS
end

You can activate the extension multiple times to import entries from different spaces.

The extension will transform every fetched entry before storing it as a yaml file in the local data folder. If a custom mapper is not specified a default one will be used.

The default mapper will map fields, assets and linked entries.

You can create your own mappers if you need so. The only requirement for a class to behave as a mapper is to have a map(context, entry) instance method. This method will take as parameters:

• A context object. All properties set on this object will be written to the yaml file
• An entry

Following is an example of such custom mapper:

class MyAwesomeMapper
  def map(context, entry)
    context.slug = entry.title.parameterize
    #... more transformations
  end
end

If you don't want to map all the fields by hand inherit from the Base mappper:

class MyAwesomeMapper < ContentfulMiddleman::Mapper::Base
  def map(context, entry)
    super
    # After calling super the context object
    # will have a property for every field in the
    # entry
  end
end

There's also an example back-reference mapper in the examples directory for adding back-references onto entries that are linked to by other entries.

If you want to process a Content Type with multiple mappers, you can use the Composite Design Pattern. The Mapper code should look something similar to the following.

Then you can attach as many Custom Mappers as you want to that one.

class CompositeMapper < ContentfulMiddleman::Mapper::Base
  @@mappers = []
  def self.mappers
    @@mappers
  end

  def map(context, entry)
    super
    mappers.each do |m|
      m.map(context, entry)
    end
  end
end

Then in your config.rb file:

CompositeMapper.mappers << YourMapper.new
CompositeMapper.mappers << OtherMapper.new

activate :contentful do |f|
  '... your config here ...'
  f.content_types = {content_type_name_you_want_to_map: {mapper: CompositeMapper, id: 'content_type_id'}}
end

NOTE: This kind of Composite Mapper is static, therefore if you want to have multiple combinations of mappers for multiple entries, you'd need to write code a bit differently.

activate :contentful do |f|
  f.space         = {partners: 'space-id'}
  f.access_token  = 'some_access_token'
  f.cda_query     = { content_type: 'content-type-id', include: 1 }
  f.content_types = { partner: 'content-type-id'}
end

The above configuration does the following:

• Sets the alias partners to the space with id some-id
• Sets the alias partner to the content type with id content-type-id
• Uses the default mapper to transform partner entries into yaml files (no mapper specified for the partner content type)

Entries fetched using this configuration will be stored as yaml files in data/partners/partner/ENTRY_ID.yaml.

class Mapper
  def map(context, entry)
    context.title = "#{entry.title}-title"
    #...
  end
end

activate :contentful do |f|
  f.space         = {partners: 'space-id'}
  f.access_token  = 'some_access_token'
  f.cda_query     = { content_type: '1EVL9Bl48Euu28QEOa44ai', include: 1 }
  f.content_types = { partner: {mapper: Mapper, id: 'content-type-id'}}
end

The above configuration is the same as the previous one only that this time we are setting a custom mapper for the entries belonging to the partner content type.

Middleman will load all the yaml files stored in the local data folder. This lets you use all the imported data into your templates.

Consider that we have data stored under data/partners/partner. Then in our templates we could use that data like this:

<h1>Partners</h1>
<ol>
  <% data.partners.partner.each do |id, partner| %>
    <li><%= partner["name"] %></li>
  <% end %>
</ol>

If you want to use markdown in your content types you manually have to render this to markdown. Depending on the markdown library you need to transform the data. For Kramdown this would be:

<%= Kramdown::Document.new(data).to_html %>

If you have localized entries, and want to display content for multiple locales. You can now include locale: '*' in your CDA query.

Then you have the following methods of accessing locales:

• Manual access

You can access your localized fields by fetching the locale directly from the data

<h1>Partners</h1>
<ol>
  <% data.partners.partner.each do |id, partner| %>
    <li><%= partner["name"]['en-US'] %></li>
  <% end %>
</ol>

• Entry Helper

You can also map an specific locale for all entry fields using localize_entry

<h1>Partners</h1>
<ol>
  <% data.partners.partner.each do |id, partner| %>
    <% localized_partner = localize_entry(partner, 'es') %>
    <li><%= localized_partner["name"] %></li>
  <% end %>
</ol>

• Generic Field Helper

The localize helper will map an specific locale to a field of your entry

<h1>Partners</h1>
<ol>
  <% data.partners.partner.each do |id, partner| %>
    <li>Value Field: <%= localize(partner, 'name', 'en-US') %></li>
    <li>Array Field: <%= localize(partner, 'phones', 'es') %></li>
  <% end %>
</ol>

• Specific Field Type Helper

Or, you can use localize_value or localize_array if you want more granularity.

This method is discouraged, as localize achieves the same goal and is a field-type agnostic wrapper of these methods.

<h1>Partners</h1>
<ol>
  <% data.partners.partner.each do |id, partner| %>
    <li>Value Field: <%= localize_value(partner['name'], 'en-US') %></li>
    <li>Array Field: <%= localize_array(partner['phones'], 'es') %></li>
  <% end %>
</ol>

If your fields are not localized, the value of the field will be returned.

In case of the field being localized but no value being set for a given entry, it will use a fallback locale, by default is en-US but can be specified as an additional parameter in all the mentioned calls.

You can use the #with_preview helper to try your Preview API content without having to generate the entire data structures.

This generates a new Preview Contentful Client and has a cache that will store your objects in memory until they are considered to need refresh.

It can be used like a Contentful Client:

<% with_preview(space: 'cfexampleapi', access_token: 'b4c0n73n7fu1') do |preview| %>
  <% entry = preview.entry('nyancat') %>

  <p>Name: <%= entry.name %></p>
<% end %>

If you want to clear the cache to force a refresh:

<% with_preview(space: 'cfexampleapi', access_token: 'b4c0n73n7fu1') do |preview| %>
  <% preview.clear_cache %>
<% end %>

• Every preview client will be cached by Space/Access Token combination
• Only entry, entries, asset and assets will be cached
• Every call will be cached by it's query parameters and ID (if ID is applicable)
• Each call will be considered, by default, stale after 3 tries or 2 hours
• Cache can be cleared by calling #clear_cache, this applies per preview client

You can configure :tries and :expires_in in the #with_preview call like this:

<% with_preview(
     space: 'cfexampleapi',
     access_token: 'b4c0n73n7fu1',
     tries: 20,                                                      # Set Tries to 20 before stale
     expires_in: ContentfulMiddleman::Tools::PreviewProxy.minutes(5) # Set Expiration to 5 minutes
   ) do |preview| %>
  <!-- do your stuff -->
<% end %>