contentful_rails 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 287f62b00e44548213d22bc2bd365a1f961324a6
-  data.tar.gz: 280b863df836812bb18113e5ecab529f060c7007
+  metadata.gz: f0f7d55ee8546d4eed5140bb1768923d8bc6861b
+  data.tar.gz: c0616573406f91822b3d3ee04d5138625498497a
 SHA512:
-  metadata.gz: 6d19254615f19e2d81439f30d165c4d78a444d8dfaa9c93e66652b9b6b4c9818656db82f43712a8440966d30ad602e0ca531e05a2939dc101f4124674ded03cb
-  data.tar.gz: 40857c4ba6cb0565dab16183d8c57d27556a3d0ae6233cd5b2e50da6618466c46e99395767a4b3a6912ed86c13c2f3020a94f2fde7bb696884e1a149ea229cdf
+  metadata.gz: bae8ca92a8774946ed40da840af9815059925c9c0f386d0fe23cddb514d6b4ca3906822c07b003826a213b60bc41e7e27881062bba4efd963bed45319ea2629b
+  data.tar.gz: a934378c344537923460d5f96ee2328fe57ec49d316136eb4c6eaf5763fbed085574cccb121107bd929b1b1327b3550ecf7db5759ddf7d8035c9d0fdc52af1e1

data/README.md

@@ -0,0 +1,158 @@
+# Contentful Rails
+
+A collection of useful things to help make it easier to integrate Contentful into your Rails app.
+It includes view helpers, a Webhook handler, caching, and a Rails Engine to hook it all together.
+
+This is a work in progress. It relies on the contentful_model gem (http://github.com/contentful/contentful_model)
+
+## What is Contentful?
+
+[Contentful](https://www.contentful.com) is a content management platform for web applications, mobile apps and connected devices. It allows you to create, edit & manage content in the cloud and publish it anywhere via powerful API. Contentful offers tools for managing editorial teams and enabling cooperation between organizations.
+
+# Configuration
+ContentfulRails accepts a block for configuration. Best done in a Rails initializer.
+
+```
+ContentfulRails.configure do |config|
+  config.authenticate_webhooks = true # false here would allow the webhooks to process without basic auth
+  config.webhooks_username = "a basic auth username"
+  config.webhooks_password = "a basic auth password"
+  config.access_token = "your access token"
+  config.preview_access_token = "your preview access token"
+  config.management_token = "your management access token"
+  config.space = "your space ID"
+  config.contentful_options = "hash of options"
+end
+```
+
+Note that you _don't_ have to separately configure ContentfulModel - adding the access tokens / space ID / options here will
+pass to ContentfulModel in an initializer in the Rails engine.
+
+The default is to authenticate the webhooks; probably a smart move to host on an HTTPS endpoint too.
+
+### Entry Mapping
+
+By default, ContentfulRails will try to define your `entry_mapping` configuration for you.  It does this by iterating through
+ the descendents of the base class `ContentfulModel::Base` during initialization.  In order to ensure these classes are
+ loaded by this time, it will call `eager_load!` for the entire application.  If this is not desired, you can set the
+ `eager_load_entry_mapping` config to false set your entry mapping manually by setting the entry_mapping config
+  as [described here](https://github.com/contentful/contentful.rb#custom-resource-classes).
+
+
+```
+ContentfulRails.configure do |config|
+  ...
+  config.eager_load_entry_mapping = false
+  config.contentful_options = {
+    entry_mapping: {
+      'article' => Article,
+      ...
+    }
+  }
+end
+```
+
+**Note:** If you do not define the entry mapping in your configuration, the webhook cache expiration will likely not work as expected
+
+# Allowing 'Russian Doll' style caching on Entries
+The issue with 'Russian Doll' caching in Rails is that it requires a hit on the database to check the `updated_at` timestamp of an object.
+
+This is obviously expensive when the object is called over an API. So this gem wraps caches `updated_at` locally, and checks that first on subsequent calls.
+
+```
+Foo.updated_at #returns a timestamp from cache, or from the API if no cache exists
+```
+
+# Webhooks Endpoint
+If there's a new version of an entry we need to expire the timestamp from the cache.
+
+This gem includes a controller endpoint for Contentful to POST back to.
+
+To make use of this in your app:
+
+## routes.rb
+Mount the ContentfulRails engine at your preferred url:
+
+```
+mount ContentfulRails::Engine => '/contentful' #feel free to choose a different endpoint name
+```
+
+This will give you 2 routes:
+
+`/contentful/webhooks` - the URL for contentful to post back to.
+`/contentful/webhooks/debug` - a development-only URL to check you have mounted the engine properly :-)
+
+## What the webhook handler does
+At the moment all this does is delete the timestamp cache entry, which means that a subsequent call to `updated_at` calls the API.
+
+# View Helpers
+Contentful has a [really nice url-based image manipulation API](https://www.contentful.com/blog/2014/08/14/do-more-with-images-on-contentful-platform/).
+
+To take advantage of this, there's a custom Redcarpet renderer which allows you to pass the image parameters you want into the call to a `parse_markdown()` method.
+
+In your application_controller.rb:
+
+```
+helper ContentfulRails::MarkdownHelper
+```
+
+This allows you to call `parse_markdown(@your_markdown)` and get HTML. *Note* that out of the box, the `parse_markdown()` is really permissive and allows you to put HTML in the Contentful markdown fields. This might not be what you want.
+
+## Manipulating images
+To manipulate images which are referenced in your markdown, you can pass the following into the `parse_markdown()` call.
+
+```
+parse_markdown(@your_markdown, image_options: {width: 1024, height: 1024})
+```
+
+The `image_options` parameter takes the following options (some are mutually exclusive. Read the [instructions here](https://www.contentful.com/blog/2014/08/14/do-more-with-images-on-contentful-platform/)):
+
+* `:width`
+* `:height`
+* `:fit`
+* `:focus`
+* `:corner_radius`
+* `:quality`
+
+## Subclassing the MarkdownRenderer class
+Sometimes you might want to apply some specific class, markup or similar to an html entity when it's being processed. [With RedCarpet that's dead easy](https://github.com/vmg/redcarpet#and-you-can-even-cook-your-own).
+
+Just subclass the `ContentfulRails::MarkdownRenderer` class, and call any methods you need.
+
+```
+class MyRenderer < ContentfulRails::MarkdownRenderer
+      # If you want to pass options into your renderer, you need to overload initialize()
+      def initialize(opts)
+        @options = opts
+        super
+      end
+
+      # If you want to do something special with links:
+      def link(link,title,content)
+        # Add a class name to all links, for example
+        class_name = "my-link-class-name"
+        content_tag(:a, content, href: link, title: title, class: class_name)
+      end
+end
+```
+
+You can overload any methods exposed in RedCarpet.
+
+# To Do
+Some things would be nice to do:
+
+* Tests :-)
+* Make caching the timestamp optional in the configuration
+* Implement a method on ContentfulModel to simulate a parent-child relationship, so we can invalidate caches for parent items
+
+
+# Licence
+Licence is MIT. Please see MIT-LICENCE in this repo.
+
+# Contributing
+Please feel free to contribute!
+
+* Fork this repo
+* Make your changes
+* Commit
+* Create a PR

data/Rakefile

@@ -6,27 +6,21 @@ end
 
 require 'rdoc/task'
 
+require File.expand_path('../spec/dummy/config/application', __FILE__)
+
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'ContentfulRails'
   rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('README.md')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
-load 'rails/tasks/engine.rake'
 
 Bundler::GemHelper.install_tasks
 
-require 'rake/testtask'
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
-end
+Rails.application.load_tasks
 
+task(:default).clear
+task default: :spec
 
-task default: :test

data/app/controllers/contentful_rails/webhooks_controller.rb

@@ -5,6 +5,7 @@ class ContentfulRails::WebhooksController < ActionController::Base
     http_basic_authenticate_with  name: ContentfulRails.configuration.webhooks_username,
                                   password: ContentfulRails.configuration.webhooks_password
   end
+
   params = [:verify_authenticity_token, {:only => [:create], raise: false}]
   if Rails::VERSION::MAJOR > 4 
     skip_before_action *params

data/lib/contentful_rails/engine.rb

@@ -3,6 +3,10 @@ module ContentfulRails
 
     isolate_namespace ContentfulRails
 
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
     config.before_initialize do
       if ContentfulRails.configuration.nil?
         ContentfulRails.configure {}

data/lib/contentful_rails/preview.rb

@@ -5,7 +5,9 @@ module ContentfulRails
     included do
       before_action :check_preview_domain
       after_action :remove_preview_cache
-      helper_method :preview?
+      if respond_to?(:helper_method)
+        helper_method :preview?
+      end
     end
     # Check whether the subdomain being presented is the preview domain.
     # If so, set ContentfulModel to use the preview API, and request a username / password

data/lib/contentful_rails/version.rb

@@ -1,3 +1,3 @@
 module ContentfulRails
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,43 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: contentful_rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Error Creative Studio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-18 00:00:00.000000000 Z
+date: 2017-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: contentful_model
+  name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.7
+        version: '4.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.7
+        version: '4.2'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: contentful_model
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.1.8
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.1.8
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: redcarpet
   requirement: !ruby/object:Gem::Requirement
@@ -60,6 +60,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - MIT-LICENSE
+- README.md
 - Rakefile
 - app/controllers/contentful_rails/webhooks_controller.rb
 - app/helpers/contentful_rails/markdown_helper.rb
@@ -74,10 +75,6 @@ files:
 - lib/contentful_rails/sluggable.rb
 - lib/contentful_rails/version.rb
 - lib/tasks/contentful_rails_tasks.rake
-- test/contentful_rails_test.rb
-- test/dummy/Rakefile
-- test/integration/navigation_test.rb
-- test/test_helper.rb
 homepage: https://github.com/errorstudio/contentful_rails
 licenses:
 - MIT
@@ -102,8 +99,4 @@ rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: A gem to help with hooking Contentful into your Rails application
-test_files:
-- test/contentful_rails_test.rb
-- test/dummy/Rakefile
-- test/integration/navigation_test.rb
-- test/test_helper.rb
+test_files: []

data/test/contentful_rails_test.rb

@@ -1,7 +0,0 @@
-require 'test_helper'
-
-class ContentfulRailsTest < ActiveSupport::TestCase
-  test "truth" do
-    assert_kind_of Module, ContentfulRails
-  end
-end

data/test/dummy/Rakefile

@@ -1,2 +0,0 @@
-require 'rake'
-require 'rails'

data/test/integration/navigation_test.rb

@@ -1,10 +0,0 @@
-require 'test_helper'
-
-class NavigationTest < ActionDispatch::IntegrationTest
-  fixtures :all
-
-  # test "the truth" do
-  #   assert true
-  # end
-end
-

data/test/test_helper.rb

@@ -1,16 +0,0 @@
-# Configure Rails Environment
-ENV["RAILS_ENV"] = "test"
-
-require File.expand_path("../../test/dummy/config/environment.rb",  __FILE__)
-ActiveRecord::Migrator.migrations_paths = [File.expand_path("../../test/dummy/db/migrate", __FILE__)]
-require "rails/test_help"
-
-Rails.backtrace_cleaner.remove_silencers!
-
-# Load support files
-Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
-
-# Load fixtures from the engine
-if ActiveSupport::TestCase.method_defined?(:fixture_path=)
-  ActiveSupport::TestCase.fixture_path = File.expand_path("../fixtures", __FILE__)
-end