Add StructuredText support (#64)

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 ### Added
 * Added capability to autoload mappers [#22](https://github.com/contentful/jekyll-contentful-data-import/issues/22)
+* *This feature is currently in ALPHA state, changes may occur as patch fixes* Added support for StructuredText and added the `structured_text` view filter.
 
 ## v1.7.0
 ### Added

README.md

@@ -43,38 +43,41 @@ To configure the extension, add the following configuration block to Jekyll's `_
 ```yaml
 contentful:
   spaces:
-    - example: # Jekyll _data folder identifier - Required
-        space: cfexampleapi         # Required
-        access_token: b4c0n73n7fu1  # Required
-        environment: master         # Optional
-        cda_query:                  # Optional
+    - example:                              # Jekyll _data folder identifier - Required
+        space: cfexampleapi                 # Required
+        access_token: b4c0n73n7fu1          # Required
+        environment: master                 # Optional
+        cda_query:                          # Optional
           include: 2
           limit: 100
-        all_entries: true           # Optional - Defaults to false, only grabbing the amount set on CDA Query
-        all_entries_page_size: 1000 # Optional - Defaults to 1000, maximum amount of entries per CDA Request for all_entries
-        content_types:              # Optional
+        all_entries: true                   # Optional - Defaults to false, only grabbing the amount set on CDA Query
+        all_entries_page_size: 1000         # Optional - Defaults to 1000, maximum amount of entries per CDA Request for all_entries
+        content_types:                      # Optional
           cat: MyCoolMapper
-        client_options:             # Optional
+        client_options:                     # Optional
           api_url: 'preview.contentful.com' # Defaults to 'api.contentful.com' which is Production
-          max_include_resolution_depth: 5 # Optional - Defaults to 20, maximum amount of levels to resolve includes
-        base_path: app_path         # Optional - Defaults to Current directory
-        destination: destination_in_data # Optional - Defaults to _data/contentful/spaces
-        individual_entry_files: true # Optional - Defaults to false
+          max_include_resolution_depth: 5   # Optional - Defaults to 20, maximum amount of levels to resolve includes
+        base_path: app_path                 # Optional - Defaults to Current directory
+        destination: destination_in_data    # Optional - Defaults to _data/contentful/spaces
+        individual_entry_files: true        # Optional - Defaults to false
+        structured_text_mappings:           # Optional - Defaults to {}
+          embedded-entry-block: MyEntryRenderer
 ```
 
-Parameter              | Description
-----------             | ------------
-space                  | Contentful Space ID
-access_token           | Contentful Delivery API access token
-environment            | Space environment, defaults to `master`
-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.
-all_entries            | Boolean, if true will run multiple queries to the API until it fetches all entries for the space
-all_entries_page_size  | Integer, the amount of maximum entries per CDA Request when fetching :all_entries
-content_types          | Hash describing the mapping applied to entries of the imported content types
-client_options         | Hash describing Contentful::Client configuration. See [contentful.rb](https://github.com/contentful/contentful.rb) for more info.
-base_path              | String with path to your Jekyll Application, defaults to current directory. Path is relative to your current location.
-destination            | String with path within `_data` under which to store the output yaml file. Defaults to contentful/spaces
-individual_entry_files | Boolean, if true will create an individual file per entry separated in folders by content type, file path will be `{space_alias}/{content_type_id}/{entry_id}.yaml`. Default behavior is to create a file per space. Usage is affected when this is set to true, please look in the section below.
+Parameter                | Description
+----------               | ------------
+space                    | Contentful Space ID
+access_token             | Contentful Delivery API access token
+environment              | Space environment, defaults to `master`
+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.
+all_entries              | Boolean, if true will run multiple queries to the API until it fetches all entries for the space
+all_entries_page_size    | Integer, the amount of maximum entries per CDA Request when fetching :all_entries
+content_types            | Hash describing the mapping applied to entries of the imported content types
+client_options           | Hash describing `Contentful::Client` configuration. See [contentful.rb](https://github.com/contentful/contentful.rb) for more info.
+base_path                | String with path to your Jekyll Application, defaults to current directory. Path is relative to your current location.
+destination              | String with path within `_data` under which to store the output yaml file. Defaults to contentful/spaces
+individual_entry_files   | Boolean, if true will create an individual file per entry separated in folders by content type, file path will be `{space_alias}/{content_type_id}/{entry_id}.yaml`. Default behavior is to create a file per space. Usage is affected when this is set to true, please look in the section below.
+structured_text_mappings | Hash with `'nodeTyoe' => RendererClass` pairs determining overrides for the [`StructuredTextRenderer` library](https://github.com/contentful/structured-text-renderer.rb) configuration.
 
 You can add multiple spaces to your configuration
 
@@ -109,21 +112,51 @@ end
 
 #### Caveats
 
-Jekyll itself only allows you to import code as plugins only for its recognized plugin entry points.
-Therefore we need to use a custom [Rakefile](https://github.com/contentful/contentful_jekyll_examples/blob/master/examples/custom_mapper/example/Rakefile) to import the mapper and required files:
+**Note:** This has changed since previous version.
 
-```ruby
-require 'jekyll'
-require 'jekyll-contentful-data-import'
-require './_plugins/mappers'
+When creating custom mappers, you should create them in a file under `#{source_dir}/_plugins/mappers/`.
+This will allow the autoload mechanism that has been included in the latest version.
 
-desc "Import Contentful Data with Custom Mappers"
-task :contentful do
-  Jekyll::Commands::Contentful.process([], {}, Jekyll.configuration['contentful'])
-end
+With the autoload mechanism, there is no longer a need to create a `rake` task for importing using custom mappers.
+
+If you already have a custom `rake` task, the new autoload mechanism will not affect it from working as it was working previously.
+
+### Structured Text *ALPHA*
+
+To render structured text in your views, you can use the `structured_text` filter:
+
+```liquid
+{{ entry.structured_text_field | structured_text }}
+```
+
+This will output the generated HTML generated by the [`StructuredTextRenderer` library](https://github.com/contentful/structured-text-renderer.rb).
+
+#### Adding custom renderers
+
+When using structured text, if you're planning to embed entries, then you need to create your custom renderer for them. You can read how create your own renderer classes [here](https://github.com/contentful/structured-text-renderer.rb#using-different-renderers).
+
+To configure the mappings, you need to add them in your `contentful` block like follows:
+
+```yaml
+contentful:
+  spaces:
+    - example:
+      # ... all the regular config ...
+      structured_text_mappings:
+        embedded-entry-block: MyCustomRenderer
 ```
 
-Then proceed to run: `bundle exec rake contentful`
+You can also add renderers for all other types of nodes if you want to have more granular control over the rendering.
+
+This will use the same autoload strategy included for custom entry mappers, therefore, you should include your mapper classes in `#{source_dir}/_plugins/mappers/`.
+
+#### Using the helper with multiple Contentful spaces
+
+In case you have multiple configured spaces, and have different mapping configurations for them. You can specify which space you want to pull the configuration from when using the helper.
+
+The helper receives an additional optional parameter for the space name. By default it is `nil`, indicating the first available space.
+
+So, if for example you have 2 spaces with different configurations, to use the space called `foo`, you should call the helper as: `{{ entry.field | structured_text: "foo" }}`.
 
 ### Hiding Space and Access Token in Public Repositories
 

jekyll-contentful.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
 
   # Additional dependencies
   s.add_dependency("contentful", '~> 2.1')
+  s.add_dependency("structured_text_renderer", '~> 0.0', '> 0.0.1')
 
   s.add_development_dependency 'rubygems-tasks', '~> 0.2'
   s.add_development_dependency "guard"

lib/jekyll-contentful-data-import.rb

@@ -1,4 +1,5 @@
 require 'jekyll-contentful-data-import/version'
+require 'jekyll-contentful-data-import/helpers'
 
 %w[contentful].each do |file|
   require File.expand_path("jekyll/commands/#{file}.rb", File.dirname(__FILE__))

lib/jekyll-contentful-data-import/helpers.rb

@@ -0,0 +1,35 @@
+require 'structured_text_renderer'
+
+module Jekyll
+  module Contentful
+    # Liquid filter for the StructuredText field.
+    module StructuredTextFilter
+      def structured_text(field, space = nil)
+        return if field.nil?
+
+        StructuredTextRenderer::Renderer.new(mappings_for(space)).render(field)
+      end
+
+      private
+
+      def mappings_for(space)
+        mappings = {}
+        config_for(space).fetch('structured_text_mappings', {}).each do |k, v|
+          mappings[k.to_s] = Module.const_get(v)
+        end
+
+        mappings
+      end
+
+      def config_for(space)
+        config = @context.registers[:site].config['contentful']['spaces']
+
+        # Spaces is a list of hashes indexed by space alias
+        return config.first.first[1] if space.nil? # Return the first available configuration
+        config.find { |sc| sc.key?(space) }[space]
+      end
+    end
+  end
+end
+
+Liquid::Template.register_filter(Jekyll::Contentful::StructuredTextFilter)