README.md in contentful_middleman-0.0.4 vs README.md in contentful_middleman-1.0.0
- old
+ new
@@ -1,15 +1,13 @@
# Contentful Middleman
[](https://travis-ci.org/contentful/contentful_middleman)
-Contentful Middleman is a [Middleman](http://middlemanapp.com/) extension to use the Middleman static side generator together with the API-driven [Contentful CMS](https://www.contentful.com). It is powered by the [Contentful Ruby Gem](https://github.com/contentful/contentful.rb).
+Contentful Middleman is a [Middleman](http://middlemanapp.com/) extension to use the Middleman static site generator together with the API-driven [Contentful CMS](https://www.contentful.com). It is powered by the [Contentful Ruby Gem](https://github.com/contentful/contentful.rb).
Experience the power of Middleman while staying sane as a developer by letting end-users edit content in a web-based interface.
-This extensions supports both page-based content as well as blog posts through middleman-blog.
-
## Installation
Add the following line to the Gemfile of your Middleman project:
```
@@ -20,64 +18,140 @@
```
bundle install
```
+## Usage
+
+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](https://middlemanapp.com/advanced/local-data/) as yaml files.
+
+### --rebuild option
+
+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.
+
## Configuration
To configure the extension, add the following configuration block to Middleman's config.rb:
-```
+```ruby
activate :contentful do |f|
- # The Space ID of your Contentful space
- f.space = 'YOUR_SPACE_ID'
+ f.space = SPACE
+ f.access_token = ACCESS_TOKEN
+ f.cda_query = QUERY
+ f.content_types = CONTENT_TYPES_MAPPINGS
+end
+```
- # The access token (API Key) for the Content Delivery API
- f.access_token = 'YOUR_CONTENT_DELIVERY_API_ACCESS_TOKEN'
+Parameter | Description
+---------- |------------
+space | Hash with an user choosen name for the space as key and the space id as value
+access_token | Contentful Delivery API access token
+cda_query | Hash describing query configuration. See [contentful.rb](https://github.com/contentful/contentful.rb) for more info
+content_types | Hash describing the mapping applied to entries of the imported content types
- # Optional: Options for middleman-blog
+You can activate the extension multiple times to import entries from different spaces.
+## Entry mapping
- # Filter Entries for your blog posts. See Contentful gem and Content Delivery API documentation.
- f.blog_posts_query = {content_type: "6LbnqgnwA08qYaU", category: "news" }
-
- # Which keys to use in the article template for blog posts
- # Key: template variable
- # Value: Entry method or block
- f.blog_post_mappings = {
- slug: :id,
- date: :created_at,
- body: :id,
- tags: :tags,
- title: ->(e){"#{e.id}XXXX"}
- }
+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.
- # Define your own template for blog posts
- f.new_article_template = "/my_templates/article.tt"
+The default mapper will map fields, assets and linked entries.
- # Automatically synchronize blog posts before building with "middleman build"
- f.sync_blog_before_build = true # default: false
+### Custom mappers
+
+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:
+
+```ruby
+class MyAwesomeMapper
+ def map(context, entry)
+ context.slug = entry.title.parameterize
+ #... more transformations
+ end
end
```
-## Using managed content in regular pages
+If you don't want to map all the fields by hand inherit from the Base mappper:
-The `contentful` helper provides a Contentful gem client object, that can be used to fetch managed content from Contentful:
+```ruby
+class MyAwesomeMapper < ContentfulMiddleman::Mappers::Base
+ def map(context, entry)
+ super
+ # After calling super the context object
+ # will have a property for every field in the
+ # entry
+ end
+end
+```
+## Configuration: examples
+
+```ruby
+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
```
- <ol>
- <% contentful.entries(content_type: '6LbnqgnwA08qYaU').each do |entry| %>
- <li>
- <%= entry.title %>
- <%= entry.body %>
- <%= entry.created_at %>
- </li>
- <% end %>
- </ol>
+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`.
+
+```ruby
+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
```
-## Synchronizing blog posts manually
+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.
-Blog posts are synchronized to your repo as YAML files with front matter, just as if you would write them manually. Either automatically when building, or manually by running:
+## Using imported entries in templates
+
+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:
+
+```html
+<h1>Partners</h1>
+<ol>
+ <% data.partners.partner.each do |id, partner| %>
+ <li><%= partner["name"] %></li>
+ <% end %>
+</ol>
```
-middleman contentful
+
+### Rendering Markdown:
+
+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 %>
```