renderful 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2915cb05e7ad342ff0423bb0a5f024f92388334aec40f8bb209ff30b2c14e57e
-  data.tar.gz: 28ff5620681ba6c05aa67887e45400a3035c9eb0f4c131bd5972801ef193f5ac
+  metadata.gz: e8b21d6a36339a25124f85dc7a61596b84307b23d3931d163d72f543a592ae90
+  data.tar.gz: bca04f50852ace266b6ce965159f0d1d9d681ada34727551e9ae3faa404d4aaf
 SHA512:
-  metadata.gz: 8bde61ec61fb15f4eaa13bb807263df6f85816d17d80810c033a5d9757a42c2fb0846b7663a7bb313a8c5602c2a73fec4c6b0ae36457bf65e7afccc44efe596e
-  data.tar.gz: 475ab0f2bb694af4c9d7d109881a4e98fd09ce3a639e7b360f466b4d1d0170fe633a4590c537a76016ced1b3b5187c0c453eef779fba246643854dc902e99bce
+  metadata.gz: 8c2e0367a4297cf75dc9851122b77628321959d398c8cf5354af3a6d683462cdbf94d0225d58fa6eca7355a5c7451fe097204f25c96c7613e1dbbc9d0874bd4d
+  data.tar.gz: 41fe4c2e8aadff79edad156da04ba42832f3443c2456aa45f969f3d52165ede301d88dc9d6bef5293341b2c119070c0a91880729cff7cc0f6b9c3f9e367f11d5

data/.circleci/config.yml

@@ -14,8 +14,11 @@ jobs:
             - renderful-v1-{{ .Branch }}
             - renderful-v1-
       - run:
-          name: Bundle Install
+          name: Bundle install
           command: bundle check || bundle install
+      - run:
+          name: Appraisal install
+          command: bundle exec appraisal install
       - save_cache:
           key: renderful-v1-{{ .Branch }}-{{ .Revision }}
           paths:

data/.gitignore

@@ -1,3 +1,4 @@
 .rspec_status
 Gemfile.lock
 gemfiles/*.lock
+tmp/

data/.rubocop-https---relaxed-ruby-style-rubocop-yml

@@ -1,5 +1,5 @@
 # Relaxed.Ruby.Style
-## Version 2.4
+## Version 2.5
 
 Style/Alias:
   Enabled: false
@@ -145,30 +145,9 @@ Lint/AssignmentInCondition:
   Enabled: false
   StyleGuide: https://relaxed.ruby.style/#lintassignmentincondition
 
-Metrics/AbcSize:
+Layout/LineLength:
   Enabled: false
 
-Metrics/BlockNesting:
-  Enabled: false
-
-Metrics/ClassLength:
-  Enabled: false
-
-Metrics/ModuleLength:
-  Enabled: false
-
-Metrics/CyclomaticComplexity:
-  Enabled: false
-
-Metrics/LineLength:
-  Enabled: false
-
-Metrics/MethodLength:
-  Enabled: false
-
-Metrics/ParameterLists:
-  Enabled: false
-
-Metrics/PerceivedComplexity:
+Metrics:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,23 +1,47 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## [Unreleased](https://github.com/nebulab/renderful/tree/HEAD)
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
-adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+[Full Changelog](https://github.com/nebulab/renderful/compare/v0.2.0...HEAD)
 
-## [Unreleased]
+**Closed issues:**
 
-### Added
+- Normalize field values [\#21](https://github.com/nebulab/renderful/issues/21)
+- Expose customer helpers to ERB views [\#15](https://github.com/nebulab/renderful/issues/15)
+- \[Contentful\] Render entities embedded in rich text? [\#14](https://github.com/nebulab/renderful/issues/14)
+- Generate a UI component library [\#13](https://github.com/nebulab/renderful/issues/13)
+- Write an end-to-end integration test [\#12](https://github.com/nebulab/renderful/issues/12)
+- Remove rails from the gemspec [\#8](https://github.com/nebulab/renderful/issues/8)
+- Remove redis from the gemspec [\#7](https://github.com/nebulab/renderful/issues/7)
+- Move issues from the upstream here [\#3](https://github.com/nebulab/renderful/issues/3)
+- Adopt ActionView::Component for rendering [\#2](https://github.com/nebulab/renderful/issues/2)
+- Add support for Prismic [\#1](https://github.com/nebulab/renderful/issues/1)
 
-- Added support for Rails 6 ([#5](https://github.com/nebulab/renderful/pull/5))
+**Merged pull requests:**
 
-### Fixed
+- Raise error when entry not found [\#24](https://github.com/nebulab/renderful/pull/24) ([filippoliverani](https://github.com/filippoliverani))
+- Add support for \#render\_in and ViewComponent [\#19](https://github.com/nebulab/renderful/pull/19) ([aldesantis](https://github.com/aldesantis))
+- Fix a typo and trim whitespace in the README [\#18](https://github.com/nebulab/renderful/pull/18) ([elia](https://github.com/elia))
+- Prismic integration [\#17](https://github.com/nebulab/renderful/pull/17) ([aldesantis](https://github.com/aldesantis))
+- Support for multiple providers [\#16](https://github.com/nebulab/renderful/pull/16) ([aldesantis](https://github.com/aldesantis))
 
-- Fixed linked entries not being invalidated ([5325981](https://github.com/nebulab/renderful/commit/5325981b6ed093407712e16e9937d86f92cdbab0))
+## [v0.2.0](https://github.com/nebulab/renderful/tree/v0.2.0) (2020-01-17)
 
-## [0.1.0] (2019-06-08)
+[Full Changelog](https://github.com/nebulab/renderful/compare/v0.1.0...v0.2.0)
 
-First public release.
+**Closed issues:**
 
-[Unreleased]: https://github.com/nebulab/renderful/compare/v0.1.0...HEAD 
-[0.1.0]: https://github.com/nebulab/renderful/tree/v0.1.0
+- Add Rails 6 support [\#4](https://github.com/nebulab/renderful/issues/4)
+
+**Merged pull requests:**
+
+- Update linting and testing infrastructure [\#6](https://github.com/nebulab/renderful/pull/6) ([aldesantis](https://github.com/aldesantis))
+- Add support for Rails 6 [\#5](https://github.com/nebulab/renderful/pull/5) ([aldesantis](https://github.com/aldesantis))
+
+## [v0.1.0](https://github.com/nebulab/renderful/tree/v0.1.0) (2019-05-02)
+
+[Full Changelog](https://github.com/nebulab/renderful/compare/579c7801e5937dc02d789cc0fa4877ae43a60e70...v0.1.0)
+
+
+
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/README.md

@@ -1,9 +1,9 @@
 # Renderful
 
-[![CircleCI](https://circleci.com/gh/bestmadeco/renderful.svg?style=svg)](https://circleci.com/gh/bestmadeco/renderful)
+[![CircleCI](https://circleci.com/gh/nebulab/renderful.svg?style=svg)](https://circleci.com/gh/nebulab/renderful)
 
-Welcome! Renderful is a rendering engine for [Contentful](https://www.contentful.com) spaces. It
-allows you to map your content types to Ruby objects that take care of rendering your content.
+Welcome! Renderful is a rendering engine for headless CMSs. It allows you to map your content types
+to Ruby objects that take care of rendering your content.
 
 ## Installation
 
@@ -28,154 +28,81 @@ $ gem install renderful
 Once you have installed the gem, you can configure it like this:
 
 ```ruby
-contentful = Contentful::Client.new(
-  space: 'CONTENTFUL_SPACE_ID',
-  access_token: 'CONTENTFUL_ACCESS_TOKEN',
+RenderfulClient = Renderful::Client.new(
+  provider: Renderful::Provider::DummyCms.new(api_key: 'secretApiKey'), # see "Providers"
+  components: {
+    'jumbotron' => JumbotronComponent,
+  },
 )
-
-renderful = Renderful.new(
-  contentful: contentful,
-  renderers: {
-    'jumbotron' => JumbotronRenderer,
-  }
-)
-``` 
+```
 
 ## Usage
 
 Suppose you have the `jumbotron` content type in your Contentful space. This content type has the
 `title` and `content` fields, both strings.
 
-Let's create the `app/renderers/jumbotron_renderer.rb` file:
+Let's create the `app/components/jumbotron_component.rb` file:
 
 ```ruby
-class JumbotronRenderer < Renderful::Renderer
+class JumbotronComponent < Renderful::Component
   def render
     <<~HTML
       <div class="jumbotron">
-        <h1 class="display-4"><%= entry.title %></h1>
-        <p class="lead"><%= entry.content %></p>
+        <h1 class="display-4">#{ entry.title }</h1>
+        <p class="lead">#{ entry.content }</p>
       </div>
     HTML
   end
 end
 ```
 
-You can now render this component by retrieving it from Contentful and rendering it with Renderful:
-
-```ruby
-entry = contentful.entry('jumbotron_entry_id')
-renderful.render(entry)
-```
-
-### Rich text rendering
-
-If you have rich-text fields, you can leverage Contentful's [rich_text_renderer](https://github.com/contentful/rich-text-renderer.rb)
-along with a custom local variable:
+You can now render the component like this:
 
 ```ruby
-class TextBlockRenderer < Renderful::Renderer::Rails
-  def html_body
-    RichTextRenderer::Renderer.new.render(entry.body)
-  end
-
-  def locals
-    { html_body: html_body }
-  end
-end
-```
-
-Then, just reference the `html_body` variable as usual:
-
-```erb
-<%# app/views/renderful/_text_block.html.erb %>
-<%= raw html_body %>
-```
-
-### Nested components
-
-What if you want to have a `Grid` component that can contain references to other components? It's
-actually quite simple! Simply create a _References_ field for your content, then recursively render
-all of the content entries contained in that field:
-
-```ruby
-# app/components/grid.rb
-class Grid < Renderful::Renderer
-  # This will define a `resolved_blocks` method that reads external references 
-  # from the `blocks` fields and turns them into Contentful::Entry instances
-  resolve :blocks
-
-  def render
-    entries = blocks.map do |block|
-      # `client` can be used to access the Renderful::Client instance
-      <<~HTML
-        <div class="grid-entry">
-          #{client.render(block)}
-        </div>
-      HTML
-    end
-
-    <<~HTML
-      <div class="grid">#{entries}</div>
-    HTML
-  end
-end
+RenderfulClient.render('my_entry_id')
 ```
 
 ### Caching
 
-You can easily cache the output of your renderers by passing a `cache` key when instantiating the
-client. The value of this key should be an object that responds to the following methods:
- 
-- `#read(key)`
-- `#write(key, value)`
-- `#delete(key)`
-- `#exist?(key)`
-
-A Redis cache implementation is included out of the box. Here's an example:
+You can easily cache the output of your components. A Redis cache implementation is included out of
+the box. Here's an example:
 
 ```ruby
-renderful = Renderful.new(
-  contentful: contentful,
+RenderfulClient = Renderful.new(
   cache: Renderful::Cache::Redis.new(Redis.new(url: 'redis://localhost:6379')),
-  renderers: {
-    'jumbotron' => JumbotronRenderer
-  }
+  # ...
 )
-``` 
+```
 
 If you are using Rails and want to use the Rails cache store for Renderful, you can simply pass
 `Rails.cache`, which responds to the expected interface:
 
 ```ruby
-renderful = Renderful.new(
-  contentful: contentful,
+RenderfulClient = Renderful.new(ful,
   cache: Rails.cache,
-  renderers: {
-    'jumbotron' => JumbotronRenderer
-  }
+  # ...
 )
-``` 
+```
 
 #### Cache invalidation
 
-The best way to invalidate the cache is through [Contentful webhooks](https://www.contentful.com/developers/docs/concepts/webhooks/).
+The best way to invalidate the cache is through [webhooks](https://www.contentful.com/developers/docs/concepts/webhooks/).
 
 Renderful ships with a framework-agnostic webhook processor you can use to automatically invalidate
 the cache for all updated content:
 
 ```ruby
-Renderful::CacheInvalidator.new(renderful).process_webhook(json_body)
+RenderfulClient.invalidate_cache_from_webhook(json_body)
 ```
 
 This is how you could use it in a Rails controller:
 
 ```ruby
-class ContentfulWebhooksController < ApplicationController
+class WebhooksController < ApplicationController
   skip_before_action :verify_authenticity_token
 
   def create
-    Renderful::CacheInvalidator.new(RenderfulClient).process_webhook(request.raw_post)
+    RenderfulClient.invalidate_cache_from_webhook(request.raw_post)
     head :no_content
   end
 end
@@ -186,96 +113,109 @@ also for any entries linking to it, so that they are re-rendered. This is very u
 if you have a `Page` entry type that contains references to many UI components - when one of the
 components is updated, you want the page to be re-rendered.
 
-### Rails integration
+### ViewComponent support
 
-If you are using Ruby on Rails and you want to use ERB instead of including HTML in your renderers,
-you can inherit from the Rails renderer:
+Renderful integrates nicely with [ViewComponent](https://github.com/github/view_component) for
+rendering your components:
 
 ```ruby
-class JumbotronRenderer < Renderful::Renderer::Rails
-end
+RenderfulClient = Renderful::Client.new(
+  components: {
+    'jumbotron' => JumbotronComponent, # JumbotronComponent inherits from ViewComponent::Base
+  },
+)
+``` 
+
+However, keep in mind you will now have to pass a view context when rendering them:
+
+```ruby
+RenderfulClient.render('my_entry_id', view_context: view_context)
 ```
 
-Then, create an `app/views/renderful/_jumbotron.html.erb` partial:
+## Providers
 
-```erb
-<div class="jumbotron">
-  <h1 class="display-4"><%= entry.title %></h1>
-  <p class="lead"><%= entry.content %></p>
-</div>
+### Contentful
+
+In order to integrate with Contentful, you will first need to add the `contentful` gem to your
+Gemfile:
+
+```ruby
+gem 'contentful'
 ```
 
-As you can see, you can access the Contentful entry via the `entry` local variable.
+Now make sure to install it:
 
-#### Custom renderer
+```console
+$ bundle install
+```
 
-The Rails renderer uses `ActionController::Base.renderer` by default, but this prevents you from
-using your own helpers in components. If you want to use a different renderer instead, you can
-override the `renderer` method:
+Finally, initialize Renderful with the Contentful provider:
 
 ```ruby
-class JumbotronRenderer < Renderful::Renderer::Rails
-  def renderer
-    ApplicationController.renderer
-  end
-end
-``` 
+RenderfulClient = Renderful::Client.new(
+  provider: Renderful::Provider::Contentful.new(
+    contentful: Contentful::Client.new(
+      space: 'cfexampleapi',
+      access_token: 'b4c0n73n7fu1',
+    )
+  )
+)
+```
+
+You can now render your Contentful entries via Renderful:
+
+```ruby
+RenderfulClient.render('your_entry_id')
+```
 
-#### Custom locals
+### Prismic
 
-If you want, you can also add your own locals:
+In order to integrate with Prismic, you will first need to add the `prismic.io` gem to your Gemfile:
 
 ```ruby
-class JumbotronRenderer < Renderful::Renderer::Rails
-  def locals
-    italian_title = entry.title.gsub(/hello/, 'ciao')
-    { italian_title: italian_title }
-  end
-end
+gem 'prismic.io', require: 'prismic'
 ```
 
-You would then access them like regular locals:
+Now make sure to install it:
 
-```erb
-<div class="jumbotron">
-  <h1 class="display-4">
-    <%= entry.title %>
-    (<%= italian_title %>) 
-  </h1>
-  <p class="lead"><%= entry.content %></p>
-</div>
+```console
+$ bundle install
 ```
 
-#### Resolution in ERB views
+Finally, initialize Renderful with the Prismic provider:
 
-If you need to render resolved fields (as in our `Grid` example), you can use `renderer` and
-`client` to access the `Renderful::Renderer` and `Renderful::Client` objects:
+```ruby
+RenderfulClient = Renderful::Client.new(
+  provider: Renderful::Provider::Prismic.new(
+    prismic: Prismic.api('https://yourendpoint.prismic.io/api', 'your_access_token')
+  )
+)
+```
 
-```erb
-<%# app/views/renderful/_grid.html.erb %>
-<div class="grid">
-  <% renderer.blocks.each do |block| %>
-    <div class="grid-entry">
-      <%= client.render(block) %>
-    </div>
-  <% end %>
-</div>
+You can now render your Prismic documents via Renderful:
+
+```ruby
+RenderfulClient.render('your_entry_id')
 ```
 
+NOTE: Due to limitations in Prismic's API, cache invalidation for Prismic will invalidate all your
+components. Depending on how often you update your content, you may want to disable caching entirely
+if you are using Prismic.
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run 
-the tests. You can also run `bin/console` for an interactive prompt that will allow you to 
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run
+the tests. You can also run `bin/console` for an interactive prompt that will allow you to
 experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new 
-version, update the version number in `version.rb`, and then run `bundle exec rake release`, which 
-will create a git tag for the version, push git commits and tags, and push the `.gem` file to 
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`, which
+will create a git tag for the version, push git commits and tags, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/bestmadeco/renderful.
+Bug reports and pull requests are welcome on GitHub at https://github.com/nebulab/renderful.
 
 ## License
 
@@ -283,4 +223,5 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Credits
 
-Renderful is sponsored and maintained by [Bolt Threads Inc.](https://www.boltthreads.com).
+Renderful was originally developed by [Nebulab](https://nebulab.it) and sponsored by
+[Bolt Threads](https://www.boltthreads.com). It is currently maintained by Nebulab.