wcc-contentful 1.3.2 → 1.4.0.rc1

data/lib/wcc/contentful/store/rspec_examples/locale_queries.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples 'supports locales in queries' do |feature_set|
+  describe 'supports query options: { locale: ... }' do
+    before { skip('querying alternate locales not supported') } if feature_set == false
+
+    generator = proc { "test#{rand(1..10_000)}" }
+
+    let(:desired_value) {
+      generator.call
+    }
+
+    let(:data) {
+      1.upto(3).map do |i|
+        {
+          'sys' => { 'id' => "k#{i}", 'contentType' => { 'sys' => { 'id' => 'test1' } } },
+          'fields' => {
+            'slug' => {
+              'en-US' => generator.call,
+              'es-ES' => generator.call
+            }
+          }
+        }
+      end
+    }
+
+    let(:desired) {
+      {
+        'sys' => { 'id' => "k#{rand}", 'contentType' => { 'sys' => { 'id' => 'test1' } } },
+        'fields' => {
+          'slug' => {
+            'en-US' => generator.call,
+            'es-ES' => desired_value
+          }
+        }
+      }
+    }
+
+    context 'when localized value exists' do
+      it 'find_by can apply filter object' do
+        [*data, desired].shuffle.each { |d| subject.set(d.dig('sys', 'id'), d) }
+
+        # act
+        found = subject.find_by(content_type: 'test1',
+          filter: { 'slug' => desired_value },
+          options: { locale: 'es-ES' })
+
+        # assert
+        expect(found).to_not be_nil
+        expect(found).to eq(desired)
+      end
+
+      it 'find_by can find value in array' do
+        data =
+          1.upto(3).map do |i|
+            {
+              'sys' => {
+                'id' => "k#{i}",
+                'contentType' => { 'sys' => { 'id' => 'test1' } }
+              },
+              'fields' => {
+                'slug' => {
+                  'en-US' => [generator.call, generator.call],
+                  'es-ES' => [generator.call, generator.call]
+                }
+              }
+            }
+          end
+
+        desired_value = generator.call
+        desired = {
+          'sys' => { 'id' => "k#{rand}", 'contentType' => { 'sys' => { 'id' => 'test1' } } },
+          'fields' => {
+            'slug' => {
+              'en-US' => [generator.call, generator.call],
+              'es-ES' => [generator.call, desired_value]
+            }
+          }
+        }
+
+        data << desired
+        data.shuffle.each { |d| subject.set(d.dig('sys', 'id'), d) }
+
+        # act
+        found = subject.find_by(content_type: 'test1',
+          filter: { 'slug' => { eq: desired_value } },
+          options: { locale: 'es-ES' })
+
+        # assert
+        expect(found).to_not be_nil
+        expect(found).to eq(desired)
+      end
+
+      it 'find_all can apply operator' do
+        desired =
+          4.upto(5).map do |i|
+            {
+              'sys' => { 'id' => "d#{i}", 'contentType' => { 'sys' => { 'id' => 'test1' } } },
+              'fields' => {
+                'slug' => {
+                  'en-US' => generator.call,
+                  'es-ES' => desired_value
+                }
+              }
+            }
+          end
+
+        [*data, *desired].shuffle.each { |d| subject.set(d.dig('sys', 'id'), d) }
+
+        # act
+        found = subject.find_all(content_type: 'test1', options: { locale: 'es-ES' })
+          .eq('slug', desired_value)
+
+        # assert
+        expect(found.count).to eq(2)
+        sorted = found.to_a.sort_by { |item| item.dig('sys', 'id') }
+        expect(sorted).to eq(desired)
+      end
+    end
+
+    context 'using fallback locales' do
+      before { pending('querying alternate locales not yet implemented') } if feature_set&.to_s == 'pending'
+
+      before do
+        allow(configuration).to receive(:locale_fallbacks)
+          .and_return({
+            'es-MX' => 'es-ES',
+            'es-ES' => 'en-US'
+          })
+      end
+
+      it 'find_by can apply filter object' do
+        [*data, desired].shuffle.each { |d| subject.set(d.dig('sys', 'id'), d) }
+
+        # act
+        found = subject.find_by(content_type: 'test1',
+          filter: { 'slug' => desired_value },
+          options: { locale: 'es-MX' })
+
+        # assert
+        expect(found).to_not be_nil
+        expect(found).to eq(desired)
+      end
+
+      it 'find_by can find value in array' do
+        data =
+          1.upto(3).map do |i|
+            {
+              'sys' => {
+                'id' => "k#{i}",
+                'contentType' => { 'sys' => { 'id' => 'test1' } }
+              },
+              'fields' => {
+                'slug' => {
+                  'en-US' => [generator.call, generator.call],
+                  'es-ES' => [generator.call, generator.call]
+                }
+              }
+            }
+          end
+
+        desired_value = generator.call
+        desired = {
+          'sys' => { 'id' => "k#{rand}", 'contentType' => { 'sys' => { 'id' => 'test1' } } },
+          'fields' => {
+            'slug' => {
+              'en-US' => [generator.call, generator.call],
+              'es-ES' => [generator.call, desired_value]
+            }
+          }
+        }
+
+        data << desired
+        data.shuffle.each { |d| subject.set(d.dig('sys', 'id'), d) }
+
+        # act
+        found = subject.find_by(content_type: 'test1',
+          filter: { 'slug' => { eq: desired_value } },
+          options: { locale: 'es-MX' })
+
+        # assert
+        expect(found).to_not be_nil
+        expect(found).to eq(desired)
+      end
+
+      it 'find_all can apply operator' do
+        desired = [
+          {
+            'sys' => { 'id' => 'd1', 'contentType' => { 'sys' => { 'id' => 'test1' } } },
+            'fields' => {
+              'slug' => {
+                'en-US' => generator.call,
+                'es-ES' => desired_value
+              }
+            }
+          },
+          {
+            'sys' => { 'id' => 'd2', 'contentType' => { 'sys' => { 'id' => 'test1' } } },
+            'fields' => {
+              'slug' => {
+                'en-US' => desired_value
+              }
+            }
+          }
+        ]
+
+        [*data, *desired].shuffle.each { |d| subject.set(d.dig('sys', 'id'), d) }
+
+        # act
+        found = subject.find_all(content_type: 'test1', options: { locale: 'es-MX' })
+          .eq('slug', desired_value)
+
+        # assert
+        expect(found.count).to eq(2)
+        sorted = found.to_a.sort_by { |item| item.dig('sys', 'id') }
+        expect(sorted).to eq(desired)
+      end
+    end
+  end
+end

data/lib/wcc/contentful/store/rspec_examples/operators/eq.rb

@@ -46,7 +46,7 @@ RSpec.shared_examples 'supports :eq operator' do
                 'id' => "k#{i}",
                 'contentType' => { 'sys' => { 'id' => 'test1' } }
               },
-              'fields' => { 'name' => { 'en-US' => [generator.call, generator.call] } }
+              'fields' => { type.to_s => { 'en-US' => [generator.call, generator.call] } }
             }
           end
 

data/lib/wcc/contentful/store/rspec_examples.rb

@@ -4,6 +4,7 @@ require_relative './rspec_examples/basic_store'
 require_relative './rspec_examples/operators'
 require_relative './rspec_examples/nested_queries'
 require_relative './rspec_examples/include_param'
+require_relative './rspec_examples/locale_queries'
 
 # rubocop:disable Style/BlockDelimiters
 
@@ -24,6 +25,11 @@ require_relative './rspec_examples/include_param'
 #    all linked entries of an object in a single query.
 #    If your store does not respect the include parameter, then the Model layer
 #    will be calling #find a lot in order to resolve linked entries.
+# [:locale_queries] - This feature defines how the store respects the `locale: x`
+#    key in the Options hash.  If this option is set, then the store needs to
+#    compare the query to the appropriate localized value.
+#    If the store does not support this, then either the application should not
+#    use multiple locales OR should always query using the default locale.
 #
 # @example
 #   require 'wcc/contentful/store/rspec_examples'
@@ -38,13 +44,19 @@ require_relative './rspec_examples/include_param'
 RSpec.shared_examples 'contentful store' do |feature_set|
   feature_set = {
     nested_queries: 'pending',
-    include_param: 'pending'
+    include_param: 'pending',
+    locale_queries: 'pending'
   }.merge(feature_set&.symbolize_keys || {})
 
+  let(:configuration) {
+    WCC::Contentful::Configuration.new
+  }
+
   include_examples 'basic store'
   include_examples 'operators', feature_set[:operators]
   include_examples 'supports nested queries', feature_set[:nested_queries]
   include_examples 'supports include param', feature_set[:include_param]
+  include_examples 'supports locales in queries', feature_set[:locale_queries]
 end
 
 # rubocop:enable Style/BlockDelimiters

data/lib/wcc/contentful/sync_engine.rb

@@ -138,7 +138,7 @@ module WCC::Contentful
       # This job uses the Contentful Sync API to update the configured store with
       # the latest data from Contentful.
       class Job < ActiveJob::Base
-        self.queue_adapter = :async
+        self.queue_adapter ||= :async
         queue_as :default
 
         def configuration

data/lib/wcc/contentful/test/double.rb

@@ -60,7 +60,7 @@ module WCC::Contentful::Test::Double
         revision: rand(100),
         locale: 'en-US'
       },
-      fields: attrs.transform_values { |v| { 'en-US' => v } }
+      fields: attrs
     }
 
     double(attrs)

data/lib/wcc/contentful/test/factory.rb

@@ -24,7 +24,7 @@ module WCC::Contentful::Test::Factory
 
       raw_value = v
       raw_value = to_raw(v, field.type) if %i[Asset Link].include?(field.type)
-      raw['fields'][field.name][raw.dig('sys', 'locale')] = raw_value
+      raw['fields'][field.name] = raw_value
     end
 
     instance = const.new(raw, context)
@@ -84,9 +84,7 @@ module WCC::Contentful::Test::Factory
   end
 
   def contentful_fields(model)
-    WCC::Contentful::Test::Attributes.defaults(model).transform_values do |v|
-      { 'en-US' => v }
-    end
+    WCC::Contentful::Test::Attributes.defaults(model)
   end
 
   def to_raw(val, field_type)

data/lib/wcc/contentful/version.rb

@@ -2,6 +2,6 @@
 
 module WCC
   module Contentful
-    VERSION = '1.3.2'
+    VERSION = '1.4.0.rc1'
   end
 end

data/lib/wcc/contentful.rb

@@ -10,6 +10,7 @@ require 'wcc/contentful/configuration'
 require 'wcc/contentful/downloads_schema'
 require 'wcc/contentful/exceptions'
 require 'wcc/contentful/helpers'
+require 'wcc/contentful/entry_locale_transformer'
 require 'wcc/contentful/link_visitor'
 require 'wcc/contentful/services'
 require 'wcc/contentful/simple_client'
@@ -40,9 +41,8 @@ module WCC::Contentful
     end
 
     # Gets all queryable locales.
-    # Reserved for future use.
     def locales
-      @locales ||= { 'en-US' => {} }.freeze
+      configuration&.locale_fallbacks
     end
 
     def logger
@@ -93,15 +93,18 @@ module WCC::Contentful
       end
     end
 
-    content_types =
+    schema =
       begin
-        JSON.parse(File.read(configuration.schema_file))['contentTypes'] if File.exist?(configuration.schema_file)
+        JSON.parse(File.read(configuration.schema_file)) if File.exist?(configuration.schema_file)
       rescue JSON::ParserError
         Services.instance.warn("Schema file invalid, ignoring it: #{configuration.schema_file}")
         nil
       end
 
-    if !content_types && %i[if_possible never].include?(configuration.update_schema_file)
+    content_types = schema['contentTypes'] if schema
+    locales = schema['locales'] if schema
+
+    if !schema && %i[if_possible never].include?(configuration.update_schema_file)
       # Final fallback - try to grab content types from CDN.  We can't update the file
       # because the CDN doesn't have all the field validation info, but we can at least
       # build the WCC::Contentful::Model instances.
@@ -127,7 +130,15 @@ module WCC::Contentful
       services: WCC::Contentful::Services.instance
     )
 
-    # Drop an initial sync
+    # Update the locale fallbacks from the schema file, unless they have already
+    # been configured.
+    locales&.each do |locale_hash|
+      next if @configuration.locale_fallbacks[locale_hash['code']]
+
+      @configuration.locale_fallbacks[locale_hash['code']] = locale_hash['fallbackCode']
+    end
+
+    # Enqueue an initial sync
     WCC::Contentful::SyncEngine::Job.perform_later if defined?(WCC::Contentful::SyncEngine::Job)
 
     @configuration = @configuration.freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wcc-contentful
 version: !ruby/object:Gem::Version
-  version: 1.3.2
+  version: 1.4.0.rc1
 platform: ruby
 authors:
 - Watermark Dev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-18 00:00:00.000000000 Z
+date: 2023-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -429,6 +429,7 @@ files:
 - lib/wcc/contentful/content_type_indexer.rb
 - lib/wcc/contentful/downloads_schema.rb
 - lib/wcc/contentful/engine.rb
+- lib/wcc/contentful/entry_locale_transformer.rb
 - lib/wcc/contentful/event.rb
 - lib/wcc/contentful/events.rb
 - lib/wcc/contentful/exceptions.rb
@@ -440,6 +441,7 @@ files:
 - lib/wcc/contentful/middleware.rb
 - lib/wcc/contentful/middleware/store.rb
 - lib/wcc/contentful/middleware/store/caching_middleware.rb
+- lib/wcc/contentful/middleware/store/locale_middleware.rb
 - lib/wcc/contentful/model.rb
 - lib/wcc/contentful/model_api.rb
 - lib/wcc/contentful/model_builder.rb
@@ -469,10 +471,12 @@ files:
 - lib/wcc/contentful/store/postgres_store/schema_1.sql
 - lib/wcc/contentful/store/postgres_store/schema_2.sql
 - lib/wcc/contentful/store/query.rb
+- lib/wcc/contentful/store/query/condition.rb
 - lib/wcc/contentful/store/query/interface.rb
 - lib/wcc/contentful/store/rspec_examples.rb
 - lib/wcc/contentful/store/rspec_examples/basic_store.rb
 - lib/wcc/contentful/store/rspec_examples/include_param.rb
+- lib/wcc/contentful/store/rspec_examples/locale_queries.rb
 - lib/wcc/contentful/store/rspec_examples/nested_queries.rb
 - lib/wcc/contentful/store/rspec_examples/operators.rb
 - lib/wcc/contentful/store/rspec_examples/operators/eq.rb
@@ -491,7 +495,7 @@ homepage: https://github.com/watermarkchurch/wcc-contentful/wcc-contentful
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.3/wcc-contentful
+  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.4/wcc-contentful
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -504,9 +508,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubygems_version: 3.3.7
 signing_key:
@@ -526,7 +530,7 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   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 3 years ago.  Since that time, Contentful''s ruby stack has improved, but
+  almost 5 years ago.  Since that time, Contentful''s ruby stack has improved, but
   there are still a number of pain points that we feel we have addressed better with
   our gem.  These are:  * [Low-level caching](#low-level-caching) * [Better integration
   with Rails & Rails models](#better-rails-integration) * [Automatic pagination and
@@ -620,19 +624,22 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   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
   `WCC::Contentful.init!`  The following examples show how to use this API to find
-  entries of the `page` content type:  ```ruby # Find objects by id WCC::Contentful::Model::Page.find(''1E2ucWSdacxxf233sfa3'')
-  # => #<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17
-  UTC...>  # Find objects by field WCC::Contentful::Model::Page.find_by(slug: ''/some-slug'')
-  # => #<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17
-  UTC...>  # Use operators to filter by a field # must use full notation for sys attributes
-  (except ID) WCC::Contentful::Model::Page.find_all(''sys.created_at'' => { lte: Date.today
-  }) # => [#<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16
-  18:41:17 UTC...>, ... ]  # Nest queries to mimick joins WCC::Contentful::Model::Page.find_by(subpages:
-  { slug: ''/some-slug'' }) # => #<WCC::Contentful::Model::Page:0x0000000005c71a78
-  @created_at=2018-04-16 18:41:17 UTC...>  # Pass the preview flag to use the preview
-  client (must have set preview_token config param) preview_redirect = 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''
+  entries of the `page` content type:  ```ruby # app/models/page.rb class Page < WCC::Contentful::Model::Page  #
+  You can add additional methods here end  # Find objects by id Page.find(''1E2ucWSdacxxf233sfa3'')
+  # => #<Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>  # Find objects
+  by field Page.find_by(slug: ''/some-slug'') # => #<Page:0x0000000005c71a78 @created_at=2018-04-16
+  18:41:17 UTC...>  # Use operators to filter by a field # must use full notation
+  for sys attributes (except ID) Page.find_all(''sys.created_at'' => { lte: Date.today
+  }) # => [#<Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>, ...
+  ]  # Nest queries to mimick joins Page.find_by(subpages: { slug: ''/some-slug''
+  }) # => #<Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>  # Fetch
+  an entry in a different locale spanish_homepage = Page.find_by(slug: ''/'', options:
+  { locale: ''es-US'' }) # => #<Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17
+  UTC...> spanish_homepage.title # => Esta es la página principal  # Pass the preview
+  flag to use the preview client (must have set preview_token config param) preview_redirect
+  = 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
@@ -643,12 +650,20 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   filter: { slug: ''/some-slug'' }) # => {"sys"=> #  ... # "fields"=> # ...}  query
   = store.find_all(content_type: ''page'').eq(''group'', ''some-group'') # => #<WCC::Contentful::Store::CDNAdapter::Query:0x00007fa3d40b84f0
   query.first # => {"sys"=> #  ... # "fields"=> # ...} query.result # => #<Enumerator::Lazy:
-  ...> query.result.force # => [{"sys"=> ...}, {"sys"=> ...}, ...] ```  See the {WCC::Contentful::Store}
-  documentation for more details.  ### Direct CDN API (SimpleClient)  The SimpleClient
-  is the bottom layer, and is used to get raw data directly from the Contentful CDN.  It
-  handles response parsing and paging, but does not resolve links or transform the
-  result into a Model class.  The following examples show how to use the SimpleClient
-  to retrieve data directly from the Contentful CDN:  ```ruby client = WCC::Contentful::Services.instance.client
+  ...> query.result.force # => [{"sys"=> ...}, {"sys"=> ...}, ...] ```  The store
+  layer, while superficially similar to the Contentful API, tries to present a different
+  "View" over the data which is more compatible with the Model layer.  It resolves
+  includes by actually replacing the in-memory `Link` objects with their linked `Entry`
+  representations.  This lets you traverse the links naturally using `#dig` or `#[]`:  ```ruby
+  # Include to a depth of 3 to make sure it''s included homepage = store.find_by(slug:
+  ''/'', include: 3) # Traverse through the top nav menu => menu button 0 => about
+  page about_page = homepage.dig(''fields'', ''nav_menu'', ''fields'', ''buttons'',
+  0, ''fields'', ''page'') ```   See the {WCC::Contentful::Store} documentation for
+  more details.  ### Direct CDN API (SimpleClient)  The SimpleClient is the bottom
+  layer, and is used to get raw data directly from the Contentful CDN.  It handles
+  response parsing and paging, but does not resolve links or transform the result
+  into a Model class.  The following examples show how to use the SimpleClient to
+  retrieve data directly from the Contentful CDN:  ```ruby client = WCC::Contentful::Services.instance.client
   # => #<WCC::Contentful::SimpleClient::Cdn:0x00007fa3cde89310  response = client.entry(''5FsqsbMECsM62e04U8sY4Y'')
   # => #<WCC::Contentful::SimpleClient::Response:0x00007fa3d103a4e0 response.body
   # => "{\n  \"sys\": {\n ... response.raw # => {"sys"=> #  ... # "fields"=> # ...}  client.asset(''5FsqsbMECsM62e04U8sY4Y'').raw
@@ -704,27 +719,44 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   example, the {WCC::Contentful::Store::MemoryStore} uses this to update the hash
   with the newest version of an entry, or delete an entry out of the hash.  #### Store
   Middleware  The store layer is made up of a base store (which implements {WCC::Contentful::Store::Interface}),
-  and optional middleware.  The middleware allows custom transformation of received
-  entries via the `#select` and `#transform` methods.  To create your own middleware
-  simply include {WCC::Contentful::Middleware::Store} and implement those methods,
-  then call `use` when configuring the store:  ```ruby config.store :direct do use
-  MyMiddleware, param1: ''xxx'' end ```  The most useful middleware is the {WCC::Contentful::Middleware::Store::CachingMiddleware},
-  which enables `:lazy_sync` mode (see {WCC::Contentful::Configuration#store})  ###
-  Model Layer  This is the global top layer where your Rails app looks up content
-  similarly to ActiveModel.  The models are namespaced under the root class {WCC::Contentful::Model}.
-  Each model''s implementation of `.find`, `.find_by`, and `.find_all` simply call
-  into the configured Store.  The main benefit of the Model layer is lazy link resolution.  When
-  a model''s property is accessed, if that property is a link that has not been resolved
-  yet (for example using the `include: n` parameter on `.find_by`), the model will
-  automatically call `#find` on the store to resolve that linked entry.  Note that
-  this can easily result in lots of CDN calls to Contentful!  To optimize this you
-  should use the `include` parameter and/or use a different store.  ## Test Helpers  To
-  use the test helpers, include the following in your rails_helper.rb:  ```ruby require
-  ''wcc/contentful/rspec'' ```  This adds the following helpers to all your specs:  ```ruby
-  ## # Builds a in-memory instance of the Contentful model for the given content_type.
-  # All attributes that are known to be required fields on the content type # will
-  return a default value based on the field type. instance = contentful_create(''my-content-type'',
-  my_field: ''some-value'') # => #<WCC::Contentful::Model::MyContentType:0x0000000005c71a78
+  and some required middleware.  The list of default middleware applied to each store
+  is found in {WCC::Contentful::Store::Factory.default_middleware}  To create your
+  own middleware simply include {WCC::Contentful::Middleware::Store}.  Then you can
+  optionally implement the `#transform` and `#select?` methods:  ```ruby class MyMiddleware
+  include WCC::Contentful::Middleware::Store  # Called for each entry that is requested
+  out of the backing store.  You can modify the entry and return it to the # next
+  layer. def transform(entry, options) # Do something with the entry... # Make sure
+  you return it at the end! entry end  def select?(entry, options) # Choose whether
+  this entry should exist or not.  If you return false here, then the entry will act
+  as though it # were archived in Contentful. entry.dig(''fields'', ''hide_until'')
+  > Time.zone.now end end ```  You can also override any of the standard Store methods.  To
+  apply the middleware, call `use` when configuring the store:  ```ruby config.store
+  :direct do use MyMiddleware, param1: ''xxx'' end ```  The most useful middleware
+  is the {WCC::Contentful::Middleware::Store::CachingMiddleware}, which enables `:lazy_sync`
+  mode (see {WCC::Contentful::Configuration#store})  ### Model Layer  This is the
+  global top layer where your Rails app looks up content similarly to ActiveModel.  The
+  models are namespaced under the root class {WCC::Contentful::Model}. Each model''s
+  implementation of `.find`, `.find_by`, and `.find_all` simply call into the configured
+  Store.  Models can be initialized directly with the `.new` method, by passing in
+  a hash: ```ruby entry = { ''sys'' => ..., ''fields'' => ... } Page.new(entry) ```  **The
+  initializer must receive a localized entry**.  An entry found using a `locale=*`
+  query must be transformed to a localized entry using the {WCC::Contentful::EntryLocaleTransformer}
+  before passing it to your model:  ```ruby entry = client.entry(''1234'', locale:
+  ''*'').raw localized_entry = WCC::Contentful::EntryLocaleTransformer.transform_to_locale(entry,
+  ''en-US'') Page.new(localized_entry) ```  The Store layer ensures that localized
+  entries are returned using the {WCC::Contentful::Middleware::Store::LocaleMiddleware}.  The
+  main benefit of the Model layer is lazy link resolution.  When a model''s property
+  is accessed, if that property is a link that has not been resolved yet (for example
+  using the `include: n` parameter on `.find_by`), the model will automatically call
+  `#find` on the store to resolve that linked entry.  Note that this can easily result
+  in lots of CDN calls to Contentful!  To optimize this you should use the `include`
+  parameter and/or use a different store.  ## Test Helpers  To use the test helpers,
+  include the following in your rails_helper.rb:  ```ruby require ''wcc/contentful/rspec''
+  ```  This adds the following helpers to all your specs:  ```ruby ## # Builds a in-memory
+  instance of the Contentful model for the given content_type. # All attributes that
+  are known to be required fields on the content type # will return a default value
+  based on the field type. instance = contentful_create(''my-content-type'', my_field:
+  ''some-value'') # => #<WCC::Contentful::Model::MyContentType:0x0000000005c71a78
   @created_at=2018-04-16 18:41:17 UTC...>  instance.my_field # => "some-value"  instance.other_required_field
   # => "default-value"  instance.other_optional_field # => nil  instance.not_a_field
   # NoMethodError: undefined method `not_a_field'' for #<MyContentType:0x00007fbac81ee490>  ##