README.md in contentful_middleman-1.1.1 vs README.md in contentful_middleman-1.2.0
- old
+ new
@@ -1,8 +1,8 @@
# Contentful Middleman
-[](https://travis-ci.org/contentful-labs/contentful_middleman)
+[](https://travis-ci.org/contentful/contentful_middleman)
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.
@@ -42,19 +42,23 @@
f.cda_query = QUERY
f.content_types = CONTENT_TYPES_MAPPINGS
end
```
-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 (look for filter options there). Note that by default only 100 entries will be fetched, this can be configured to up to 1000 entries using the `limit` option.
-content_types | Hash describing the mapping applied to entries of the imported content types
-use_preview_api | Boolean to toogle the used API. Set it to `false` to use `cdn.contentful.com` (default value). Set it to `true` to use `preview.contentful.com`. More info in [the documentation](https://www.contentful.com/developers/documentation/content-delivery-api/#preview-api)
+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 (look for filter options there). Note that by default only 100 entries will be fetched, this can be configured to up to 1000 entries using the `limit` option. Example: `f.cda_query = { limit: 1000 }`
+content_types | Hash describing the mapping applied to entries of the imported content types
+use_preview_api | Boolean to toggle the used API. Set it to `false` to use `cdn.contentful.com` (default value). Set it to `true` to use `preview.contentful.com`. More info in [the documentation](https://www.contentful.com/developers/documentation/content-delivery-api/#preview-api)
+all_entries | Boolean to toggle multiple requests to the API for getting over 1000 entries. This uses a naive approach and can get rate limited. When using this, have in mind adding an `order` in your `:cda_query` . Default order is `order: 'sys.createdAt'`
+rebuild_on_webhook | Boolean to toggle Webhook server. Server will run in port 5678, and will be expecting to receive Contentful Webhook calls on `/receive`
+webhook_timeout | Integer (in seconds) for wait time after Webhook received for rebuilding. Only used if `:rebuild_on_webhook` is true. Defaults to 300 seconds
You can activate the extension multiple times to import entries from different spaces.
+
## Entry mapping
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.
@@ -92,20 +96,59 @@
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.
+#### Multiple Mappers
+
+If you want to process a Content Type with multiple mappers, you can use the [Composite Design Pattern](https://en.wikipedia.org/wiki/Composite_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.
+
+```ruby
+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:
+
+```ruby
+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.
+
## 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
```
+
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)
@@ -156,5 +199,76 @@
For Kramdown this would be:
```
<%= Kramdown::Document.new(data).to_html %>
```
+
+### Locales
+
+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
+
+```html
+<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`
+
+```html
+<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
+
+```html
+<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.
+
+```html
+<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.