wcc-contentful 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63f3ef5be57de2373cfb7af9def7e9227fe0be9d7acc22977f650f4638f8835d
-  data.tar.gz: 80021d370e0b6e4238515658f491cd6fee5bafe39c813822dcf3e44d86d7a6fa
+  metadata.gz: 3fd731fc709f8ecfcd4ee730a6bc52e693bdd5f160ba00ad4cb5a50978c8a735
+  data.tar.gz: 20b9b0b06f31eace48c3ababb1c4cbbbc6d2a8143bc29677957305c4ce4dfe23
 SHA512:
-  metadata.gz: 4a26f8d7e360cac5511bf68fd083c980f0ab8d9f5c81657b363f157c2c811fa0316bcd6987fff4ae0225a74db8450a196d2a21cafee9d6cb42213d9c55556a4f
-  data.tar.gz: 26299e68f65c992b226c8c17064913454d582795ac2bd2345784f0b4550f73f77047bf8f3a67d2110652843508d885f20f45d6202bb36ede4b3d7b3244b0d6b7
+  metadata.gz: 9d2200e5b8bbb1c4a1b52a9163fa06c48d90049cc03715359610ab2e3b62d776635d174636b275188489da2cea857ca5a001426489513b15b2d31de749340b16
+  data.tar.gz: afb2143f431c139dabfa7139eedb27984f0846e6c377efb2cdea8d61336b1532e97ebba18483ea53ff7826e95b1304afeff99805c5ed750e37b93001cfb9067b

data/README.md

@@ -15,6 +15,7 @@ Table of Contents:
 3. [Configuration](#configure)
 4. [Usage](#usage)
    1. [Model API](#wcccontentfulmodel-api)
+      * [Rich Text Support](#rich-text-support)
    2. [Store API](#store-api)
    3. [Direct CDN client](#direct-cdn-api-simpleclient)
    4. [Accessing the APIs](#accessing-the-apis-within-application-code)
@@ -146,7 +147,7 @@ WCC::Contentful.init!
 ```
 
 All configuration options can be found [in the rubydoc under
-WCC::Contentful::Configuration](https://watermarkchurch.github.io/wcc-contentful/latest/wcc-contentful/WCC/Contentful/Configuration) 
+WCC::Contentful::Configuration](https://watermarkchurch.github.io/wcc-contentful/latest/wcc-contentful/WCC/Contentful/Configuration)
 
 ## Usage
 
@@ -198,6 +199,57 @@ preview_redirect_object.href
 
 See the {WCC::Contentful::Model} documentation for more details.
 
+#### Rich Text support
+
+As of version 1.5.0, the Model API supports parsing and rendering Rich Text fields.
+
+Rich Text fields are retrieved from the API and parsed into the WCC::Contentful::RichText::Document object model.
+```rb
+Page.find_by(slug: '/some-slug').my_rich_text
+# => #<struct WCC::Contentful::RichText::Document ...
+```
+
+If you are using Rails, a rich text field can be rendered to HTML using the default renderer by
+calling #to_html:
+```rb
+my_rich_text.to_html
+# => "<div class=\"contentful-rich-text\"><h2>Dear Watermark Family,</h2>
+```
+
+If you are not using Rails, or if you want to override the default rendering behavior, you need to set the
+WCC::Contentful::Configuration#rich_text_field configuration option:
+```rb
+# lib/my_rich_text_renderer
+class MyRichTextRenderer < WCC::Contentful::ActionViewRichTextRenderer
+  def render_hyperlink(node)
+    # override the default logic for rendering hyperlinks
+  end
+end
+
+# config/initializers/wcc_contentful.rb
+WCC::Contentful.configure do |config|
+  config.rich_text_renderer = MyRichTextRenderer
+end
+```
+
+If you want to construct and render WCC::Contentful::RichText::Document objects directly, the #to_html method will
+raise an error.  Instead, you will need to construct and invoke your renderer directly.
+```rb
+my_document = WCC::Contentful::RichText.tokenize(JSON.parse(...contentful CDN rich text field representation...))
+# => #<struct WCC::Contentful::RichText::Document ...
+
+renderer = MyRichTextRenderer.new(my_document,
+  # (optional) inject services so the renderer can automatically resolve links to entries and assets.
+  # The renderer still works without this, but hyperlinks which reference Assets or Entries will raise an error.
+  config: WCC::Contentful.configuration,
+  store: WCC::Contentful::Services.instance.store,
+  model_namespace: WCC::Contentful::Model)
+# => #<MyRichTextRenderer:0x0000000005c71a78
+
+renderer.call
+# => "<div class=\"contentful-rich-text\"><h2>Dear Watermark Family,</h2>
+```
+
 ### Store API
 
 The Store layer is used by the Model API to access Contentful data in a raw form.
@@ -359,7 +411,7 @@ From the bottom up:
 
 ### Client Layer
 
-The {WCC::Contentful::SimpleClient} provides methods to access the [Contentful 
+The {WCC::Contentful::SimpleClient} provides methods to access the [Contentful
 Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/)
 through your favorite HTTP client gem.  The SimpleClient expects
 an Adapter that conforms to the Faraday interface.
@@ -403,7 +455,7 @@ require 'wcc/contentful/store/rspec_examples'
 
 RSpec.describe MyStore do
   it_behaves_like 'contentful store', {
-    # Set which store features your store implements.  
+    # Set which store features your store implements.
     nested_queries: true,  # Does your store implement JOINs?
     include_param: true    # Does your store resolve links when given the :include option?
   }
@@ -695,7 +747,7 @@ defined inside the `app` directory, this will have the effect of deleting all co
 as well as the constants generated from your schema.
 This will result in one of two errors:
 
-* `NameError (uninitialized constant MySecondSpace::MyContentType)`  
+* `NameError (uninitialized constant MySecondSpace::MyContentType)`
     if you try to reference a subclass such as `MyContentType < MySecondSpace::MyContentType`
 * `ArgumentError (Not yet configured!)`
     if you try to `MySecondSpace.find('xxxx')` to load an Entry or Asset

data/lib/tasks/rewrite_fixtures.rake

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'wcc/contentful'
+
+namespace :wcc_contentful do
+  desc 'Rewrites JSON fixtures from locale=* to locale=en-US'
+  task :rewrite_fixtures, %i[glob locale] => :environment do |_t, args|
+    glob = args[:glob] || 'spec/fixtures/**/*.json'
+    locale = args[:locale] || 'en-US'
+
+    Dir.glob(glob) do |filename|
+      next unless File.file?(filename)
+
+      contents = JSON.parse(File.read(filename))
+      next unless contents.is_a?(Hash) && contents['sys']
+
+      rewritten_contents =
+        case contents['sys']['type']
+        when 'Array'
+          rewrite_array(contents, locale: locale)
+        when 'Entry', 'Asset'
+          rewrite_entry(contents, locale: locale)
+        end
+      next unless rewritten_contents
+
+      File.write(filename, JSON.pretty_generate(rewritten_contents))
+    end
+  end
+
+  def rewrite_array(contents, locale: 'en-US')
+    contents['items'] =
+      contents['items'].map do |item|
+        rewrite_entry(item, locale: locale)
+      end
+    if contents['includes']
+      if contents['includes']['Entry']
+        contents['includes']['Entry'] =
+          contents['includes']['Entry'].map do |item|
+            rewrite_entry(item, locale: locale)
+          end
+      end
+      if contents['includes']['Asset']
+        contents['includes']['Asset'] =
+          contents['includes']['Asset'].map do |item|
+            rewrite_entry(item, locale: locale)
+          end
+      end
+    end
+
+    contents
+  end
+
+  def rewrite_entry(contents, locale: 'en-US')
+    return contents unless contents['sys']
+
+    WCC::Contentful::EntryLocaleTransformer.transform_to_locale(
+      contents,
+      locale
+    )
+  end
+end

data/lib/wcc/contentful/action_view_rich_text_renderer.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'action_view'
+
+# An implementation of the RichTextRenderer that uses ActionView helpers to implement content_tag and concat.
+class WCC::Contentful::ActionViewRichTextRenderer < WCC::Contentful::RichTextRenderer
+  include ActionView::Helpers::TagHelper
+  include ActionView::Helpers::TextHelper
+  include ActionView::Context
+
+  # TODO: use ActionView view context to render ERB templates for embedded entries?
+end

data/lib/wcc/contentful/configuration.rb

@@ -14,6 +14,7 @@ class WCC::Contentful::Configuration
     logger
     management_token
     preview_token
+    rich_text_renderer
     schema_file
     space
     store
@@ -77,6 +78,12 @@ class WCC::Contentful::Configuration
   # Default: 2.seconds
   attr_accessor :sync_retry_wait
 
+  # Sets the rich text renderer implementation.  This must be a class that accepts a WCC::Contentful::RichText::Document
+  # in the constructor, and responds to `:call` with a string containing the HTML.
+  # In a Rails context, the implementation defaults to WCC::Contentful::ActionViewRichTextRenderer.
+  # In a non-Rails context, you must provide your own implementation.
+  attr_accessor :rich_text_renderer
+
   # Returns true if the currently configured environment is pointing at `master`.
   def master?
     !environment.present?
@@ -204,6 +211,12 @@ class WCC::Contentful::Configuration
     }
     @management_token = ENV.fetch('CONTENTFUL_MANAGEMENT_TOKEN', nil)
     @preview_token = ENV.fetch('CONTENTFUL_PREVIEW_TOKEN', nil)
+
+    if defined?(ActionView)
+      require 'wcc/contentful/action_view_rich_text_renderer'
+      @rich_text_renderer = WCC::Contentful::ActionViewRichTextRenderer
+    end
+
     @space = ENV.fetch('CONTENTFUL_SPACE_ID', nil)
     @default_locale = 'en-US'
     @locale_fallbacks = {}

data/lib/wcc/contentful/model_api.rb

@@ -37,7 +37,7 @@ module WCC::Contentful::ModelAPI
         # try looking up the class heierarchy
         (superclass.services if superclass.respond_to?(:services)) ||
         # create it if we have a configuration
-        WCC::Contentful::Services.new(configuration)
+        WCC::Contentful::Services.new(configuration, model_namespace: self)
     end
 
     def store(preview = nil)

data/lib/wcc/contentful/model_builder.rb

@@ -104,7 +104,7 @@ module WCC::Contentful
                 # when :DateTime
                 #   raw_value = Time.parse(raw_value).localtime
                 when :RichText
-                  raw_value = WCC::Contentful::RichText.tokenize(raw_value)
+                  raw_value = WCC::Contentful::RichText.tokenize(raw_value, renderer: ns.services.rich_text_renderer)
                 when :Int
                   raw_value = Integer(raw_value)
                 when :Float

data/lib/wcc/contentful/rich_text/node.rb

@@ -28,6 +28,24 @@ module WCC::Contentful::RichText
           tuple
         end
       end
+
+      # Set the renderer to use when rendering this node to HTML.
+      # By default a node does not have a renderer, and #to_html will raise an ArgumentError.
+      # However if a WCC::Contentful::RichText::Document node is created by the WCC::Contentful::ModelBuilder,
+      # it will inject the renderer configured in WCC::Contentful::Services#rich_text_renderer into the node.
+      attr_accessor :renderer
+
+      # Render the node to HTML using the configured renderer.
+      # See WCC::Contentful::RichTextRenderer for more information.
+      def to_html
+        unless renderer
+          raise ArgumentError,
+            'No renderer provided during tokenization.  ' \
+            'Please configure the rich_text_renderer in your WCC::Contentful configuration.'
+        end
+
+        renderer.call(self)
+      end
     end
 
     class_methods do
@@ -36,8 +54,12 @@ module WCC::Contentful::RichText
         name.demodulize.underscore.dasherize
       end
 
-      def tokenize(raw, context = nil)
-        raise ArgumentError, "Expected '#{node_type}', got '#{raw['nodeType']}'" unless raw['nodeType'] == node_type
+      def matches?(node_type)
+        self.node_type == node_type
+      end
+
+      def tokenize(raw, renderer: nil)
+        raise ArgumentError, "Expected '#{node_type}', got '#{raw['nodeType']}'" unless matches?(raw['nodeType'])
 
         values =
           members.map do |symbol|
@@ -45,15 +67,17 @@ module WCC::Contentful::RichText
 
             case symbol
             when :content
-              WCC::Contentful::RichText.tokenize(val, context)
-              # when :data
-              # TODO: resolve links...
+              WCC::Contentful::RichText.tokenize(val, renderer: renderer)
             else
               val
             end
           end
 
-        new(*values)
+        new(*values).tap do |node|
+          next unless renderer
+
+          node.renderer = renderer
+        end
       end
     end
   end

data/lib/wcc/contentful/rich_text.rb

@@ -23,9 +23,11 @@ require_relative './rich_text/node'
 module WCC::Contentful::RichText
   ##
   # Recursively converts a raw JSON-parsed hash into the RichText object model.
-  def self.tokenize(raw, context = nil)
+  # If renderer are provided, the model will be able to resolve links to entries
+  # and enable direct rendering of documents to HTML.
+  def self.tokenize(raw, renderer: nil)
     return unless raw
-    return raw.map { |c| tokenize(c, context) } if raw.is_a?(Array)
+    return raw.map { |c| tokenize(c) } if raw.is_a?(Array)
 
     klass =
       case raw['nodeType']
@@ -33,10 +35,26 @@ module WCC::Contentful::RichText
         Document
       when 'paragraph'
         Paragraph
+      when 'hr'
+        HR
       when 'blockquote'
         Blockquote
       when 'text'
         Text
+      when 'ordered-list'
+        OrderedList
+      when 'unordered-list'
+        UnorderedList
+      when 'list-item'
+        ListItem
+      when 'table'
+        Table
+      when 'table-row'
+        TableRow
+      when 'table-cell'
+        TableCell
+      when 'table-header-cell'
+        TableHeaderCell
       when 'embedded-entry-inline'
         EmbeddedEntryInline
       when 'embedded-entry-block'
@@ -44,13 +62,17 @@ module WCC::Contentful::RichText
       when 'embedded-asset-block'
         EmbeddedAssetBlock
       when /heading-(\d+)/
-        size = Regexp.last_match(1)
-        const_get("Heading#{size}")
+        Heading
+      when /(\w+-)?hyperlink/
+        Hyperlink
       else
+        # Future proofing for new node types introduced by Contentful.
+        # The best list of node types maintained by Contentful is here:
+        # https://github.com/contentful/rich-text/blob/master/packages/rich-text-types/src/blocks.ts
         Unknown
       end
 
-    klass.tokenize(raw, context)
+    klass.tokenize(raw, renderer: renderer)
   end
 
   Document =
@@ -63,6 +85,11 @@ module WCC::Contentful::RichText
       include WCC::Contentful::RichText::Node
     end
 
+  HR =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
   Blockquote =
     Struct.new(:nodeType, :data, :content) do
       include WCC::Contentful::RichText::Node
@@ -73,6 +100,41 @@ module WCC::Contentful::RichText
       include WCC::Contentful::RichText::Node
     end
 
+  OrderedList =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
+  UnorderedList =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
+  ListItem =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
+  Table =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
+  TableRow =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
+  TableCell =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
+  TableHeaderCell =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
   EmbeddedEntryInline =
     Struct.new(:nodeType, :data, :content) do
       include WCC::Contentful::RichText::Node
@@ -88,18 +150,40 @@ module WCC::Contentful::RichText
       include WCC::Contentful::RichText::Node
     end
 
-  (1..5).each do |i|
-    struct =
-      Struct.new(:nodeType, :data, :content) do
-        include WCC::Contentful::RichText::Node
+  EmbeddedResourceBlock =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+    end
+
+  Heading =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+
+      def self.matches?(node_type)
+        node_type =~ /heading-(\d+)/
       end
-    sz = i
-    struct.define_singleton_method(:node_type) { "heading-#{sz}" }
-    const_set("Heading#{sz}", struct)
-  end
+
+      def size
+        @size ||= /heading-(\d+)/.match(nodeType)[1]&.to_i
+      end
+    end
+
+  Hyperlink =
+    Struct.new(:nodeType, :data, :content) do
+      include WCC::Contentful::RichText::Node
+
+      def self.matches?(node_type)
+        node_type =~ /(\w+-)?hyperlink/
+      end
+    end
 
   Unknown =
     Struct.new(:nodeType, :data, :content) do
       include WCC::Contentful::RichText::Node
+
+      # Unknown nodes are the catch all, so they always match anything that made it to the else case of the switch.
+      def self.matches?(_node_type)
+        true
+      end
     end
 end

data/lib/wcc/contentful/rich_text_renderer.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+# The abstract base class for rendering Rich Text.
+# This base class implements much of the recursive logic necessary for rendering
+# Rich Text nodes, but leaves the actual rendering of the HTML tags to the
+# subclasses.
+#
+# Subclasses can override any method to customize the rendering behavior.  At a minimum they must implement
+# the #content_tag and #concat methods to take advantage of the recursive rendering logic in the base class.
+# The API for these methods is assumed to be equivalent to the ActionView helpers of the same name.
+#
+# The canonical implementation is the WCC::Contentful::ActionViewRichTextRenderer, which uses the standard ActionView
+# helpers as-is to render the HTML tags.
+#
+# @example
+#   class MyRichTextRenderer < WCC::Contentful::RichTextRenderer
+#     def content_tag(name, options, &block)
+#       # your implementation here
+#       # for reference of expected behavior see
+#       # https://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag
+#     end
+#
+#     def concat(html_string)
+#       # your implementation here
+#       # for reference of expected behavior see
+#       # https://api.rubyonrails.org/classes/ActionView/Helpers/TextHelper.html#method-i-concat
+#     end
+#   end
+#
+#   renderer = MyRichTextRenderer.new(document)
+#   renderer.call
+#
+# @abstract
+class WCC::Contentful::RichTextRenderer
+  class << self
+    def call(document, *args, **kwargs)
+      new(document, *args, **kwargs).call
+    end
+  end
+
+  attr_reader :document
+  attr_accessor :configuration, :store, :model_namespace
+
+  def initialize(document, configuration: nil, store: nil, model_namespace: nil)
+    @document = document
+    @configuration = configuration if configuration.present?
+    @store = store if store.present?
+    @model_namespace = model_namespace if model_namespace.present?
+  end
+
+  def call
+    render.to_s
+  end
+
+  def render
+    content_tag(:div, class: 'contentful-rich-text') do
+      render_content(document.content)
+    end
+  end
+
+  def render_content(content)
+    content&.each do |node|
+      concat render_node(node)
+    end
+  end
+
+  def render_node(node)
+    if WCC::Contentful::RichText::Heading.matches?(node.node_type)
+      render_heading(node)
+    else
+      public_send(:"render_#{node.node_type.underscore}", node)
+    end
+  end
+
+  def render_text(node)
+    return node.value unless node.marks&.any?
+
+    node.marks.reduce(node.value) do |value, mark|
+      next value unless type = mark['type']&.underscore
+
+      render_mark(type, value)
+    end
+  end
+
+  DEFAULT_MARKS = {
+    'bold' => 'strong',
+    'italic' => 'em',
+    'underline' => 'u',
+    'code' => 'code',
+    'superscript' => 'sup',
+    'subscript' => 'sub'
+  }.freeze
+
+  def render_mark(type, value)
+    return value unless tag = DEFAULT_MARKS[type]
+
+    content_tag(tag, value)
+  end
+
+  def render_paragraph(node)
+    content_tag(:p) do
+      render_content(node.content)
+    end
+  end
+
+  def render_heading(node)
+    content_tag(:"h#{node.size}") do
+      render_content(node.content)
+    end
+  end
+
+  def render_blockquote(node)
+    content_tag(:blockquote) do
+      render_content(node.content)
+    end
+  end
+
+  def render_hr(_node)
+    content_tag(:hr)
+  end
+
+  def render_unordered_list(node)
+    content_tag(:ul) do
+      render_content(node.content)
+    end
+  end
+
+  def render_ordered_list(node)
+    content_tag(:ol) do
+      render_content(node.content)
+    end
+  end
+
+  def render_list_item(node)
+    content_tag(:li) do
+      render_content(node.content)
+    end
+  end
+
+  def render_table(node)
+    content_tag(:table) do
+      # Check the first row - if it's a header row, render a <thead>
+      first, *rest = node.content
+      if first&.content&.all? { |cell| cell.node_type == 'table-header-cell' }
+        concat(content_tag(:thead) { render_content([first]) })
+      else
+        # Otherwise, render it inside the tbody with the rest
+        rest.unshift(first)
+      end
+
+      concat(content_tag(:tbody) { render_content(rest) })
+    end
+  end
+
+  def render_table_row(node)
+    content_tag(:tr) do
+      render_content(node.content)
+    end
+  end
+
+  def render_table_cell(node)
+    content_tag(:td) do
+      render_content(node.content)
+    end
+  end
+
+  def render_table_header_cell(node)
+    content_tag(:th) do
+      render_content(node.content)
+    end
+  end
+
+  def render_hyperlink(node)
+    content_tag(:a,
+      href: node.data['uri'],
+      # External links should be target="_blank" by default
+      target: ('_blank' if url_is_external?(node.data['uri']))) do
+      render_content(node.content)
+    end
+  end
+
+  def render_asset_hyperlink(node)
+    target = resolve_target(node.data['target'])
+    url = target&.dig('fields', 'file', 'url')
+
+    render_hyperlink(
+      WCC::Contentful::RichText::Hyperlink.tokenize(
+        node.as_json.merge(
+          'nodeType' => 'hyperlink',
+          'data' => node['data'].merge({
+            'uri' => url,
+            'target' => target.as_json
+          })
+        )
+      )
+    )
+  end
+
+  def render_entry_hyperlink(node)
+    unless model_namespace.present?
+      raise NotConnectedError,
+        'Rendering linked entries requires a connected RichTextRenderer.  Please use the one configured in ' \
+        'WCC::Contentful::Services.instance or pass a model_namespace to the RichTextRenderer constructor.'
+    end
+
+    target = resolve_target(node.data['target'])
+    model_instance = model_namespace.new_from_raw(target)
+    unless model_instance.respond_to?(:href)
+      raise NotConnectedError,
+        "Entry hyperlinks are not supported for #{model_instance.class}.  " \
+        'Please ensure your model defines an #href method, or override the ' \
+        '#render_entry_hyperlink method in your app-specific RichTextRenderer implementation.'
+    end
+
+    render_hyperlink(
+      WCC::Contentful::RichText::Hyperlink.tokenize(
+        node.as_json.merge(
+          'nodeType' => 'hyperlink',
+          'data' => node['data'].merge({
+            'uri' => model_instance.href,
+            'target' => target.as_json
+          })
+        )
+      )
+    )
+  end
+
+  def render_embedded_asset_block(node)
+    target = resolve_target(node.data['target'])
+    title = target&.dig('fields', 'title')
+    url = target&.dig('fields', 'file', 'url')
+
+    content_tag(:img, src: url, alt: title) do
+      render_content(node.content)
+    end
+  end
+
+  def render_embedded_entry_block(_node)
+    raise AbstractRendererError,
+      'Entry embeds are not supported.  What should it look like? ' \
+      'Please override this in your app-specific RichTextRenderer implementation.'
+  end
+
+  def render_embedded_entry_inline(_node)
+    raise AbstractRendererError,
+      'Inline Entry embeds are not supported.  What should it look like? ' \
+      'Please override this in your app-specific RichTextRenderer implementation.'
+  end
+
+  private
+
+  def resolve_target(target)
+    unless store.present?
+      raise NotConnectedError,
+        'Rendering embedded or linked entries requires a connected RichTextRenderer.  Please use the one configured ' \
+        'in WCC::Contentful::Services.instance or pass a store to the RichTextRenderer constructor.'
+    end
+
+    if target&.dig('sys', 'type') == 'Link'
+      target = store.find(target.dig('sys', 'id'), hint: target.dig('sys', 'linkType'))
+    end
+    target
+  end
+
+  def url_is_external?(url)
+    return false unless url.present?
+
+    uri =
+      begin
+        URI(url)
+      rescue StandardError
+        nil
+      end
+    return false unless uri&.host.present?
+
+    app_uri =
+      if configuration&.app_url.present?
+        begin
+          URI(configuration.app_url)
+        rescue StandardError
+          nil
+        end
+      end
+    uri.host != app_uri&.host
+  end
+
+  def content_tag(*_args)
+    raise AbstractRendererError, 'RichTextRenderer is an abstract class, please use an implementation subclass'
+  end
+
+  def concat(*_args)
+    raise AbstractRendererError, 'RichTextRenderer is an abstract class, please use an implementation subclass'
+  end
+
+  class AbstractRendererError < StandardError
+  end
+
+  class NotConnectedError < AbstractRendererError
+  end
+end

data/lib/wcc/contentful/rich_text_renderer_factory.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Constructs new connected RichTextRenderer instances w/ needed dependencies
+class RichTextRendererFactory
+  def initialize(implementation_class, services: WCC::Contentful::Services.instance)
+    @implementation_class = implementation_class
+    @services = services
+  end
+
+  def new(document)
+    @implementation_class.new(document).tap do |renderer|
+      # Inject any dependencies that the renderer needs (except itself to avoid infinite recursion)
+      @services.inject_into(renderer, except: [:rich_text_renderer])
+    end
+  end
+
+  def call(document)
+    new(document).call
+  end
+end

data/lib/wcc/contentful/services.rb

@@ -11,10 +11,15 @@ module WCC::Contentful
 
     attr_reader :configuration
 
-    def initialize(configuration)
+    def model_namespace
+      @model_namespace || WCC::Contentful::Model
+    end
+
+    def initialize(configuration, model_namespace: nil)
       raise ArgumentError, 'Not yet configured!' unless configuration
 
       @configuration = configuration
+      @model_namespace = model_namespace
     end
 
     # Gets the data-store which executes the queries run against the dynamic
@@ -123,6 +128,28 @@ module WCC::Contentful
         end
     end
 
+    # Returns a callable object which can be used to render a rich text document.
+    # This object will have all the connected services injected into it.
+    # The implementation class is configured by {WCC::Contentful::Configuration#rich_text_renderer}.
+    # In a rails context the default implementation is {WCC::Contentful::ActionViewRichTextRenderer}.
+    def rich_text_renderer
+      @rich_text_renderer ||=
+        if implementation_class = configuration&.rich_text_renderer
+          RichTextRendererFactory.new(implementation_class, services: self)
+        else
+          # Create a renderer that renders a more helpful error message, but delay the error message until #to_html
+          # is actually invoked in case the user never actually uses the renderer.
+          Class.new(WCC::Contentful::RichTextRenderer) do
+            def call
+              raise WCC::Contentful::RichTextRenderer::AbstractRendererError,
+                'No rich text renderer implementation has been configured.  ' \
+                'Please install a supported implementation such as ActionView, ' \
+                'or set WCC::Contentful.configuration.rich_text_renderer to a custom implementation.'
+            end
+          end
+        end
+    end
+
     # Gets the configured instrumentation adapter, defaulting to ActiveSupport::Notifications
     def instrumentation
       @instrumentation ||=

data/lib/wcc/contentful/simple_client/response.rb

@@ -104,7 +104,7 @@ class WCC::Contentful::SimpleClient
     def includes
       @includes ||=
         raw['includes']&.each_with_object({}) do |(_t, entries), h|
-          entries.each { |e| h[e.dig('sys', 'id')] = e }
+          entries&.each { |e| h[e.dig('sys', 'id')] = e }
         end || {}
     end
   end

data/lib/wcc/contentful/version.rb

@@ -2,6 +2,6 @@
 
 module WCC
   module Contentful
-    VERSION = '1.4.0'
+    VERSION = '1.5.0'
   end
 end

data/lib/wcc/contentful.rb

@@ -20,6 +20,9 @@ require 'wcc/contentful/model'
 require 'wcc/contentful/model_methods'
 require 'wcc/contentful/model_singleton_methods'
 require 'wcc/contentful/model_builder'
+require 'wcc/contentful/rich_text'
+require 'wcc/contentful/rich_text_renderer'
+require 'wcc/contentful/rich_text_renderer_factory'
 require 'wcc/contentful/sync_engine'
 require 'wcc/contentful/events'
 require 'wcc/contentful/middleware'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wcc-contentful
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Watermark Dev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-09 00:00:00.000000000 Z
+date: 2023-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -423,7 +423,9 @@ files:
 - config/initializers/mime_types.rb
 - config/routes.rb
 - lib/tasks/download_schema.rake
+- lib/tasks/rewrite_fixtures.rake
 - lib/wcc/contentful.rb
+- lib/wcc/contentful/action_view_rich_text_renderer.rb
 - lib/wcc/contentful/active_record_shim.rb
 - lib/wcc/contentful/configuration.rb
 - lib/wcc/contentful/content_type_indexer.rb
@@ -451,6 +453,8 @@ files:
 - lib/wcc/contentful/rake.rb
 - lib/wcc/contentful/rich_text.rb
 - lib/wcc/contentful/rich_text/node.rb
+- lib/wcc/contentful/rich_text_renderer.rb
+- lib/wcc/contentful/rich_text_renderer_factory.rb
 - lib/wcc/contentful/rspec.rb
 - lib/wcc/contentful/services.rb
 - lib/wcc/contentful/simple_client.rb
@@ -495,7 +499,7 @@ homepage: https://github.com/watermarkchurch/wcc-contentful/wcc-contentful
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.4/wcc-contentful
+  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.5/wcc-contentful
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -523,11 +527,12 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   [contentful_model](https://github.com/contentful/contentful_model), and [contentful_rails](https://github.com/contentful/contentful_rails)
   gems all in one.  Table of Contents:  1. [Why?](#why-did-you-rewrite-the-contentful-ruby-stack)
   2. [Installation](#installation) 3. [Configuration](#configure) 4. [Usage](#usage)
-  1. [Model API](#wcccontentfulmodel-api) 2. [Store API](#store-api) 3. [Direct CDN
-  client](#direct-cdn-api-simpleclient) 4. [Accessing the APIs](#accessing-the-apis-within-application-code)
-  5. [Architecture](#architecture) 1. [Client Layer](#client-layer) 2. [Store Layer](#store-layer)
-  3. [Model Layer](#model-layer) 6. [Test Helpers](#test-helpers) 7. [Advanced Configuration
-  Example](#advanced-configuration-example) 8. [Connecting to Multiple Spaces](#connecting-to-multiple-spaces-or-environments)
+  1. [Model API](#wcccontentfulmodel-api) * [Rich Text Support](#rich-text-support)
+  2. [Store API](#store-api) 3. [Direct CDN client](#direct-cdn-api-simpleclient)
+  4. [Accessing the APIs](#accessing-the-apis-within-application-code) 5. [Architecture](#architecture)
+  1. [Client Layer](#client-layer) 2. [Store Layer](#store-layer) 3. [Model Layer](#model-layer)
+  6. [Test Helpers](#test-helpers) 7. [Advanced Configuration Example](#advanced-configuration-example)
+  8. [Connecting to Multiple Spaces](#connecting-to-multiple-spaces-or-environments)
   9. [Development](#development) 10. [Contributing](#contributing) 11. [License](#license)   ##
   Why did you rewrite the Contentful ruby stack?  We started working with Contentful
   almost 5 years ago.  Since that time, Contentful''s ruby stack has improved, but
@@ -619,7 +624,7 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   $ gem install wcc-contentful ```  ## Configure  Put this in an initializer:  ```ruby
   # config/initializers/wcc_contentful.rb WCC::Contentful.configure do |config| config.access_token
   = <CONTENTFUL_ACCESS_TOKEN> config.space = <CONTENTFUL_SPACE_ID> end  WCC::Contentful.init!
-  ```  All configuration options can be found [in the rubydoc under WCC::Contentful::Configuration](https://watermarkchurch.github.io/wcc-contentful/latest/wcc-contentful/WCC/Contentful/Configuration)   ##
+  ```  All configuration options can be found [in the rubydoc under WCC::Contentful::Configuration](https://watermarkchurch.github.io/wcc-contentful/latest/wcc-contentful/WCC/Contentful/Configuration)  ##
   Usage  ### WCC::Contentful::Model API  The WCC::Contentful::Model API exposes Contentful
   data as a set of dynamically generated Ruby objects.  These objects are based on
   the content types in your Contentful space.  All these objects are generated by
@@ -640,12 +645,34 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   = WCC::Contentful::Model::Redirect.find_by({ slug: ''draft-redirect'' }, preview:
   true) # => #<WCC::Contentful::Model::Redirect:0x0000000005d879ad @created_at=2018-04-16
   18:41:17 UTC...> preview_redirect_object.href # => ''http://www.somesite.com/slug-for-redirect''
-  ```  See the {WCC::Contentful::Model} documentation for more details.  ### Store
-  API  The Store layer is used by the Model API to access Contentful data in a raw
-  form. The Store layer returns entries as hashes parsed from JSON, conforming to
-  the object structure returned from the Contentful CDN.  The following examples show
-  how to use the Store API to retrieve raw data from the store:  ```ruby store = WCC::Contentful::Services.instance.store
-  # => #<WCC::Contentful::Store::CDNAdapter:0x00007fb92a221498  store.find(''5FsqsbMECsM62e04U8sY4Y'')
+  ```  See the {WCC::Contentful::Model} documentation for more details.  #### Rich
+  Text support  As of version 1.5.0, the Model API supports parsing and rendering
+  Rich Text fields.  Rich Text fields are retrieved from the API and parsed into the
+  WCC::Contentful::RichText::Document object model. ```rb Page.find_by(slug: ''/some-slug'').my_rich_text
+  # => #<struct WCC::Contentful::RichText::Document ... ```  If you are using Rails,
+  a rich text field can be rendered to HTML using the default renderer by calling
+  #to_html: ```rb my_rich_text.to_html # => "<div class=\"contentful-rich-text\"><h2>Dear
+  Watermark Family,</h2> ```  If you are not using Rails, or if you want to override
+  the default rendering behavior, you need to set the WCC::Contentful::Configuration#rich_text_field
+  configuration option: ```rb # lib/my_rich_text_renderer class MyRichTextRenderer
+  < WCC::Contentful::ActionViewRichTextRenderer def render_hyperlink(node) # override
+  the default logic for rendering hyperlinks end end  # config/initializers/wcc_contentful.rb
+  WCC::Contentful.configure do |config| config.rich_text_renderer = MyRichTextRenderer
+  end ```  If you want to construct and render WCC::Contentful::RichText::Document
+  objects directly, the #to_html method will raise an error.  Instead, you will need
+  to construct and invoke your renderer directly. ```rb my_document = WCC::Contentful::RichText.tokenize(JSON.parse(...contentful
+  CDN rich text field representation...)) # => #<struct WCC::Contentful::RichText::Document
+  ...  renderer = MyRichTextRenderer.new(my_document, # (optional) inject services
+  so the renderer can automatically resolve links to entries and assets. # The renderer
+  still works without this, but hyperlinks which reference Assets or Entries will
+  raise an error. config: WCC::Contentful.configuration, store: WCC::Contentful::Services.instance.store,
+  model_namespace: WCC::Contentful::Model) # => #<MyRichTextRenderer:0x0000000005c71a78  renderer.call
+  # => "<div class=\"contentful-rich-text\"><h2>Dear Watermark Family,</h2> ```  ###
+  Store API  The Store layer is used by the Model API to access Contentful data in
+  a raw form. The Store layer returns entries as hashes parsed from JSON, conforming
+  to the object structure returned from the Contentful CDN.  The following examples
+  show how to use the Store API to retrieve raw data from the store:  ```ruby store
+  = WCC::Contentful::Services.instance.store # => #<WCC::Contentful::Store::CDNAdapter:0x00007fb92a221498  store.find(''5FsqsbMECsM62e04U8sY4Y'')
   # => {"sys"=> #  ... # "fields"=> # ...}  store.find_by(content_type: ''page'',
   filter: { slug: ''/some-slug'' }) # => {"sys"=> #  ... # "fields"=> # ...}  query
   = store.find_all(content_type: ''page'').eq(''group'', ''some-group'') # => #<WCC::Contentful::Store::CDNAdapter::Query:0x00007fa3d40b84f0
@@ -692,7 +719,7 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   < ApplicationJob include WCC::Contentful::ServiceAccessors  def perform Page.find(...)  store.find(...)  client.entries(...)
   end end ```  ## Architecture  ![wcc-contentful diagram](./doc-static/wcc-contentful.png)  From
   the bottom up:  ### Client Layer  The {WCC::Contentful::SimpleClient} provides methods
-  to access the [Contentful  Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/)
+  to access the [Contentful Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/)
   through your favorite HTTP client gem.  The SimpleClient expects an Adapter that
   conforms to the Faraday interface.  Creating a SimpleClient to connect using different
   credentials, or to connect without setting up all the rest of WCC::Contentful, is
@@ -711,7 +738,7 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   your own store. In your RSpec suite: ```ruby # frozen_string_literal: true  require
   ''my_store'' require ''wcc/contentful/store/rspec_examples''  RSpec.describe MyStore
   do it_behaves_like ''contentful store'', { # Set which store features your store
-  implements.   nested_queries: true,  # Does your store implement JOINs? include_param:
+  implements. nested_queries: true,  # Does your store implement JOINs? include_param:
   true    # Does your store resolve links when given the :include option? } ```  The
   store is kept up-to-date by the {WCC::Contentful::SyncEngine}.  The `SyncEngine#next`
   methodcalls the `#index` method on the configured store in order to update it with
@@ -827,7 +854,7 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   in a class defined inside the `app` directory, this will have the effect of deleting
   all configuration that was set in the initializer as well as the constants generated
   from your schema. This will result in one of two errors:  * `NameError (uninitialized
-  constant MySecondSpace::MyContentType)`   if you try to reference a subclass such
+  constant MySecondSpace::MyContentType)` if you try to reference a subclass such
   as `MyContentType < MySecondSpace::MyContentType` * `ArgumentError (Not yet configured!)`
   if you try to `MySecondSpace.find(''xxxx'')` to load an Entry or Asset  The solution
   is to have your secondary namespace in a folder which is not in the `autoload_paths`.