Add Localize Helpers

CHANGELOG.md

@@ -5,6 +5,7 @@
 * Update `middleman-core` required version
 * Removes `middleman-blog` dependency[#9](https://github.com/contentful-labs/contentful_middleman/issues/9)
 * Add Webhook Integration[#55](https://github.com/contentful-labs/contentful_middleman/pull/55)
+* Add Localize Helpers
 
 ## 1.1.1
 ### Changed

README.md

@@ -200,3 +200,74 @@ 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 the locale not found, it will use
+a fallback locale, by default is `en-US` but can be specified as an additional
+parameter in all the mentioned calls.

contentful_middleman.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
   s.add_dependency("middleman-core", ["~> 3.3"])
 
   # Additional dependencies
-  s.add_dependency("contentful")
+  s.add_dependency("contentful", '~> 0.7')
   s.add_dependency("contentful-webhook-listener", '~> 0.1')
 
   s.add_development_dependency 'rubygems-tasks', '~> 0.2'

lib/contentful_middleman/helpers.rb

@@ -3,5 +3,34 @@ module Helpers
     def contentful_instances
       ContentfulMiddleman.instances
     end
+
+    def localize_entry(entry, locale, fallback_locale='en-US')
+      localized_entry = {}
+      entry.each do |field, value|
+        localized_entry[field] = localize(entry, field, locale, fallback_locale)
+      end
+      localized_entry
+    end
+
+    def localize(entry, field, locale, fallback_locale='en-US')
+      value = entry.fetch(field)
+
+      return localize_array(value, locale, fallback_locale) if value.is_a? ::Array
+      localize_value(value, locale, fallback_locale)
+    end
+
+    def localize_array(value, locale, fallback_locale='en-US')
+      value.map do |v|
+        localize_value(v, locale, fallback_locale)
+      end
+    end
+
+    def localize_value(value, locale, fallback_locale='en-US')
+      if value.respond_to? :fetch
+        return value.fetch(locale) if value.key? locale
+        return value.fetch(fallback_locale)
+      end
+      value
+    end
   end
 end