strong_presenter 0.0.1 → 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1a4c71461c442ca200ed884ad386a15e9ff45ef5
+  data.tar.gz: 33fdccd699136c74dcaf5d05d26ae389b068820f
+SHA512:
+  metadata.gz: 18500c434c142b6308f5dbcc54917cec4cbbc0abfba72fd5afcb0f630c6c1503ea5ee3fae333581b734c24244b217b6c1ba6c297fd1ff13a14abc0c55c58b1cb
+  data.tar.gz: 193487ffad3116820af4096105461b882ffc506b179fd60bc99f262f41aac2419e95f07c8b72712dc5091144791663ba6f7f87b083ba4cdde1e181d4aab0df22

data/.gitignore

@@ -6,13 +6,16 @@
 Gemfile.lock
 InstalledFiles
 _yardoc
-coverage
+/coverage
 doc/
 lib/bundler/man
-pkg
+/pkg
 rdoc
 spec/reports
 test/tmp
 test/version_tmp
 tmp
 *.swp
+*.log
+*.sqlite3
+

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order rand

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - rbx-19mode
+  - jruby-19mode
+
+env:
+  - "RAILS_VERSION=4.0"
+  - "RAILS_VERSION=3.2"
+  - "RAILS_VERSION=3.1"
+  - "RAILS_VERSION=3.0"
+  - "RAILS_VERSION=4.1"
+
+matrix:
+  allow_failures:
+    - env: "RAILS_VERSION=4.1"

data/.yardopts

@@ -0,0 +1 @@
+yardoc 'lib/strong_presenter/**/*.rb' -m markdown --no-private

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# StrongPresenter Changelog
+
+## 0.2.0 In development
+
+Changes to be made:
+
+- Remove permissions grouping - convert to copy on write
+- Remove permit_all! class method
+- Require explicit wildcard endings to attribute paths to permit everything `[:association, :nested_association, :*]` to permit all methods in the association
+
+## 0.1.0 - Stable
+
+- Copied features from Draper gem (thanks):
+  - spec/spec_helper.rb, spec/integration, spec/dummy - much easier for me, since I have difficulties trying to get a dummy app working.
+  - ViewContext, HelperProxy - compared to my HelperProxy trying to include various rails modules, this exposes methods like `current_user` as well.
+  - test integration - ties in with ViewContext.
+  - Gemfile, .travis.yml, .yardopts, Rakefile, Guardfile, .rspec, tasks
+  - Generators
+- Features derived from the Draper gem with substantial modifications
+  - factory - remove many options, some simplifications.
+  - DecoratesAssigned -> ControllerAdditions - :only, :except options, execute block instead of passing :context-like options.
+  - CollectionDecorator -> CollectionPresenter
+  - Associations -> Associable
+- Other features added
+  - *Presenter::Collection - constant automatically added which points to the corresponding collection presenter. If this does not exist, a subclass of StrongPresenter::CollectionPresenter is dynamically created.
+  - Permissible, Permissions - `permit`, `permit!`, `filter` interface separated into a separate Permissible module. The Permissions class just stores attributes that have been permitted
+
+## 0.0.1
+
+- Allows presenters in `app/presenters` to wrap models and expose a read-only interface.
+- `permit` interface to mark attributes with a `presents` method on each presenter, which yields the value of permitted attributes to a block.

data/Gemfile

@@ -1,4 +1,24 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
-# Specify your gem's dependencies in strong_presenter.gemspec
 gemspec
+
+gem 'debugger', platforms: :mri_19
+gem 'byebug', platforms: :mri_20
+
+platforms :mri_19, :mri_20 do
+  gem 'simplecov', require: false
+  gem 'coveralls', require: false
+end
+
+platforms :ruby do
+  gem "sqlite3"
+end
+
+platforms :jruby do
+  gem "minitest", ">= 3.0"
+  gem "activerecord-jdbcsqlite3-adapter", ">= 1.3.0.beta2"
+end
+
+version = ENV["RAILS_VERSION"] || "4.0"
+
+eval_gemfile File.expand_path("../gemfiles/#{version}.gemfile", __FILE__)

data/Guardfile

@@ -0,0 +1,26 @@
+def rspec_guard(options = {}, &block)
+  options = {
+    :version => 2,
+    :notification => false
+  }.merge(options)
+
+  guard 'rspec', options, &block
+end
+
+rspec_guard :spec_paths => %w{spec/strong_presenter spec/generators} do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+
+rspec_guard :spec_paths => 'spec/integration', :env => {'RAILS_ENV' => 'development'} do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+
+rspec_guard :spec_paths => 'spec/integration', :env => {'RAILS_ENV' => 'production'} do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/README.md

@@ -1,20 +1,31 @@
 # StrongPresenter
 
-StrongPresenter lets you add presenters to your application, along with strong_parameters-inspired permit logic to handle mass presentations, where each user may have permision to view different fields.
+[![Gem Version](https://badge.fury.io/rb/strong_presenter.png)](http://badge.fury.io/rb/strong_presenter)
+[![Build Status](https://travis-ci.org/ronalchn/strong_presenter.png?branch=master)](https://travis-ci.org/ronalchn/strong_presenter)
+[![Coverage Status](https://coveralls.io/repos/ronalchn/strong_presenter/badge.png)](https://coveralls.io/r/ronalchn/strong_presenter)
+[![Code Climate](https://codeclimate.com/github/ronalchn/strong_presenter.png)](https://codeclimate.com/github/ronalchn/strong_presenter)
 
-Adding an explicit `permit` interface allows authorization logic to be pushed back from the view to the controller where it probably belongs. This allows the view to concentrate on laying out the webpage, rather than deciding whether each of the components should be displayed.
+StrongPresenter adds a layer of presentation logic to your application. The presenters also give you a strong_parameters-like syntax to specify what attributes can be read, helping you push authorization logic from the view layer back to the controller layer. The view layer can be dumber, and concentrate on page layout rather than authorization logic flow.
 
-When displaying a datatable, there is no need to call `can? :read_email_column, @user` in both the table headings, and as each row is displayed. The permission check can be performed once in the controller.
+A number of features have been copied from Draper and refined.
 
-This gem puts presenters in `app/presenters`, not `app/decorators`, because not all decorators are presenters. It better separates the different class types in your application. Presenters should be providing a read-only interface to a model. Variable setters should not be delegated through the presenter. On the other hand, decorators add features to a model, and can very well delegate setters methods to the model. However, they may be used for other reasons, such as in domain-specific logic. We don't want to mix presenter classes with decorator classes that may be used for domain-specific logic.
+## Why use Presenters?
 
-While there exist other presenter gems, we hope to provide a more natural interface to create your presenters. This gem is opinionated - presenters should be in `app/presenters`, read-only interfaces to the underlying models, and not mixed with general-purpose decorators.
+Presenters deal with presentation, so your models can concentrate on domain logic. Instead of using a helper methods, you can implement the method in a presenter instead.
+
+Others have used decorators for this purpose - while they can be used for presentation logic, it may cause some confusion in your application. Presenters are designed to help you to present - a market-oriented solution. Decorators are a coding pattern which can be used for presentation - a product-oriented solution.
+
+The decorator coding pattern involves using delegation to wrap the model, adding new behaviour to the base object, possibly overriding some methods to present data in a visually appealing way. The decorator pattern not only wraps an object, but also involves keeping the decorated object acting like an instance of the base object (allowing multiple redecorations) - but this is not really what you want for presentation.
+
+When we consider presentation, we are interested in reading the information, not further mutating the object, so we want to hide attribute setters, or other domain logic. We are also not interested in wrapping multiple layers around the object (we can use multiple still use presenters of the same object). If we want to share presentation logic between different models, we should instead use one presenter per model, including various behaviour using mixins.
+
+While there exist other gems for presentation, we hope to provide a more natural interface to create your presenters.
 
 ## Installation
 
 Requires Rails. Rails 3.2+ is supported (probably works on 3.0, 3.1 as well).
 
-Add this line to your application's Gemfile:
+Add this line to your application''s Gemfile:
 
     gem 'strong_presenter'
 
@@ -26,106 +37,184 @@ Or install it yourself as:
 
     $ gem install strong_presenter
 
+Or to use the edge version, add this to your Gemfile:
+
+    gem 'strong_presenter', :github => 'ronalchn/strong_presenter'
+
 ## Usage
 
-Create a new presenter:
+### Writing Presenters
+
+Presenters are stored in `app/presenters`, they inherit from `StrongPresenter::BasePresenter` and are named based on the model they decorate. We also recommend you create an `ApplicationPresenter`.
 
-```ruby    
-class ApplicationPresenter < StrongPresenter::Base
+```ruby
+# app/presenters/user_presenter.rb
+class UserPresenter < ApplicationPresenter
+  # ...
 end
+```
+
+### Accessing the Model and Helpers
 
+As shown below, rails helpers can be accessed through `h`. You can access the model using the `object` method, or the model name (in this case `user`). For example:
+
+```ruby
 class UserPresenter < ApplicationPresenter
   presents :user
-  delegate :username, :name, :email, to: :user
-
   def avatar
     h.tag :img, :src => user.avatar_url
   end
 end
 ```
 
-Use the presenter on your object in your controller
+The model name is either inferred from the class name - taking `UserPresenter`, and converting the part before "Presenter" to lower case with underscores between each word, or it can be set using the `presents` method as shown above.
+
+### Delegating Methods
+
+If no changes are necessary, a method can be delegated to the model. The `:to` option defaults to `object`.
+
+```ruby
+class UserPresenter < ApplicationPresenter
+  delegate :username, :email
+end
+```
+
+### Wrapping Models with Presenters
+
+#### Single Objects
+
+Just pass the model to a new presenter instance:
+
+```ruby
+@user_presenter = UserPresenter.new(@user)
+```
+
+#### Collections
+
+Pass the model to a corresponding collection presenter:
+
+```ruby
+@users_presenter = UserPresenter::Collection.new(@users)
+```
+
+To add methods to your collection presenter, inherit from `StrongPresenter::CollectionPresenter`:
+
+```ruby
+# app/presenters/users_presenter.rb
+class UsersPresenter < StrongPresenter::CollectionPresenter
+  def pages
+    (collection.size / 20).ceil
+  end
+end
+```
+
+It wraps each item in the collection with the corresponding singular presenter inferred from the class name, but it can be set using the `:with` option in the constructor, or by calling `presents_with :user` (for example), in the class definition.
+
+### Model Associations
+
+To automatically wrap associations with a presenter, use `presents_association` or `presents_associations`:
+
+```ruby
+# app/presenters/users_presenter.rb
+class UsersPresenter < StrongPresenter::CollectionPresenter
+  presents_association :comments
+end
+```
+
+A specific presenter can be specified using the `:with` option, otherwise it is inferred from the association. A scope can be specified using the `:scope` option. It can also yield the new presenter to a block.
+
+### When to Wrap the Model with the Presenter
+
+You will normally want to wrap the model with the presenter at the end of your controller action:
 
 ```ruby
 class UserController < ApplicationController
   def show
     @user = User.find(params[:id])
-    @user_presenter = UserPresenter.wrap(@user).permit *visible_attributes
+    @user_presenter = UserPresenter.new(@user)
   end
+end
+```
+
+But you can use the `presents` method to add a helper method that returns the presenter lazily:
 
-  private
-  def visible_attributes
-    [:username] + (can?(:read_private_details, @user) ? [:name, :email] : [])
+```ruby
+class UserController < ApplicationController
+  presents :user, with: UserPresenter, only: :show
+  def show
+    @user = User.find(params[:id])
   end
 end
 ```
 
-Use the presenter in the view:
+If the `:with` option is not passed, it will be inferred by using the model class name. `:only` and `:except` sets the controller actions it applies to.
+
+### Permit!
+
+You can simply use the presenter in the view:
 
 ```ruby
 Avatar: <%= @user_presenter.avatar %>
 ```
 
-Or use mass presentation to present multiple fields/attributes at once. Notice that if `visible_attributes`
-does not include name or email, they will not show. The advantage is that authorization logic
-remains in the controller where it arguably belongs.
+However, sometimes you will want to display information only if it is permitted. To do this, simply pass the attribute symbols to the `presents` method on the presenter, and it will only display it if it is permitted. This is especially powerful because it controls the display of not just the attribute value, but everything that is passed in the block.
 
 ```erb
-<% @user_presenter.presents :username, :name, :email do |key, value| %>
-  <b><%= UserPresenter.label(key) %>:</b> <%= value %><br>
+<% fields = { :username => "Username", :name => "Name", :email => "E-mail" } %>
+<% user.presents *fields.keys do |key, value| # user = @user_presenter because of the call to `presents` in the controller class %>
+  <b><%= fields[key] %>:</b> <%= value %><br>
 <% end %>
 ```
 
-The `presents` method will only present those attributes which have been permitted. In contrast, a method
-such as `avatar` on the presenter will not check if the attribute is permitted. To check this, the `presents`
-method can be used. For example:
+The `present` method is also available to display a single attribute:
 
 ```erb
-<% @user_presenter.presents(:avatar).each do |presented_avatar| %>
-  <%= presented_avatar %>
+<b>Hello <%= user.present :name %></b><br>
+<% user.present :username do |value| %>
+  <b>Username:</b> <%= value %><br>
 <% end %>
 ```
 
-In this case, since `permit` was not passed `:avatar`, it will not be presented. To remove authorization checks
-from mass presentations, simply call `permit!` on an instance of a presenter, or on the class (to disable for all instances).
-
-Fields or attributes can be assigned a label, by calling `label` with a hash.
+To permit the display of the attributes, call `permit` on the presenter with the attribute symbols in the controller.
 
 ```ruby
-class UserPresenter < ApplicationPresenter
-  ...
-  label :email => "E-mail", :name => "Real Name"
+class UserController < ApplicationController
+  def show
+    @user = User.find(params[:id])
+    @user_presenter = UserPresenter.new(@user).permit :username, :name # but not :email
+  end
 end
 ```
 
-Labels can be retrieved by using the field/attribute by calling `label` with the symbol(s):
+You can also call it when using the `presents` method in the controller:
 
 ```ruby
-  UserPresenter.label [:email, :username] # returns ["E-mail", "Username"]
+class UserController < ApplicationController
+  presents :user do |presenter|
+    presenter.permit :username, :name
+    presenter.permit :email if current_user.admin?
+  end
+  def show
+    @user = User.find(params[:id])
+  end
+end
 ```
 
-If no label was explicitly assigned, it is simply converted to a string and humanized.
+To remove authorization checks, simply call `permit!` on an instance of a presenter.
 
-Labels can be useful when used in a datatable to display collections. The controller can wrap
-a collection using `wrap_each`:
-
-```ruby
-  @users_presenter = UserPresenter.wrap_each(@users).permit( *visible_attributes )
-```
-
-Then the view can use each presenter, to display only the columns a user is permitted to view.
+There is also a `filter` method to help you with tables:
 
 ```erb
-<% fields = [:username, :name, :email] %>
+<% fields = { :username => "Username", :name => "Name", :email => "E-mail" } %>
 <table>
   <tr>
-    <% @users_presenter.filter( *fields ).to_labels.each do |label| %>
-      <th><%= label %></th>
+    <% @users_presenter.filter( *fields.keys ) do |key| %>
+      <th><%= fields[key] %></th>
     <% end %>
   </tr>
   <% @users_presenter.each do |user_presenter| %>
     <tr>
-      <% user_presenter.presents( *fields ).each do |value| %>
+      <% user_presenter.presents( *fields.keys ).each do |value| %>
         <%= content_tag :td, value %>
       <% end %>
     </tr>
@@ -134,16 +223,85 @@ Then the view can use each presenter, to display only the columns a user is perm
 ```
 
 Here, we use filter to check which of the columns are visible, just like `presents` does. It returns an
-array of only the visible columns, and `to_labels` is a method added to the array to allow conversion to label form.
+array of only the visible columns, and we use our `fields` hash to label it.
 
-This also allows mass presentation based on GET parameter input, for example:
+We can decide what attributes to present based on a GET parameter input, for example:
 
 ```erb
-<% user_presenter.presents( params[:columns].split(',') ).each do |value| %><%= content_tag :td, value %><% end %>
+<% @user_presenter.presents( params[:columns].split(',') ).each do |value| %>
+  <%= content_tag :td, value %>
+<% end %>
 ```
 
 Because of the `permit` checks, there is no danger that private information will be revealed.
 
+#### Permissions Paths
+
+Association methods can be permitted by passing an array.
+
+```rb
+@article_presenter.permit :body, [:author, :name]
+```
+
+Then, presenting it:
+
+```erb
+<%= @article_presenter.present [:author, :name] %>
+```
+
+is equivalent to `@article_presenter.author.name`, except it includes the permission check.
+
+#### Permissions Groups
+
+Currently, each group of presenters shares a single permissions object. Therefore, each element in a collection references the same permissions object. The presenter for each association also shares the same permissions object. This means that permitting a method will permit it for all presenters in the group, and it is not possible for two presenters in the same collection to have different methods permitted.
+
+Everytime you get a presenter through a collection or association, it will be added to the permissions group. To start a new group, you will need to initialize it yourself.
+
+It is the intention that in version 0.2.0, permissions groups (for efficiency in a simple implementation), will be removed, and each new presenter will implement copy on write with the permissions object. This will retain efficiency where `permit` is called early before forking new presenters, but allow different permissions for each presenter. This will change the behaviour of what is considered permitted, but if `permit` is called before using the presenter, the behaviour will not change.
+
+### Testing
+
+#### RSpec
+
+The specs are placed in `spec/presenters`. Add `type: :presenter` if they are placed elsewhere.
+
+#### Isolated Tests
+
+In tests, a view context is built to access helper methods. By default, it will create an ApplicationController and then use its view context. If you are speeding up your test suite by testing each component in isolation, you can eliminate this dependency by putting the following in your spec_helper or similar:
+
+```ruby
+StrongPresenter::ViewContext.test_strategy :fast
+```
+
+In doing so, your presenters will no longer have access to your application''s helpers. If you need to selectively include such helpers, you can pass a block:
+
+```ruby
+StrongPresenter::ViewContext.test_strategy :fast do
+  include ApplicationHelper
+end
+```
+
+### Generating Presenters
+
+With StrongPresenter installed:
+
+```sh
+rails generate resource Article
+```
+
+will include a presenter.
+
+To generate a presenter by itself:
+
+```sh
+rails generate presenter Article
+```
+
+## Acknowledgements
+
+- [Draper](https://github.com/drapergem/draper) - a number of features from this gem have been copied and refined. Thanks!
+- https://github.com/railscasts/287-presenters-from-scratch/
+
 ## License
 
 Mozilla Public License Version 2.0

data/Rakefile

@@ -1 +1,77 @@
-require "bundler/gem_tasks"
+require 'rake'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+def run_in_dummy_app(command)
+  success = system("cd spec/dummy && #{command}")
+  raise "#{command} failed" unless success
+end
+
+task "default" => "ci"
+
+desc "Run all tests for CI"
+citask = ["spec"]
+begin
+  require 'coveralls/rake/task'
+  Coveralls::RakeTask.new
+  citask << "coveralls:push" if defined? 'Coveralls'
+rescue LoadError
+end
+task "ci" => citask
+
+desc "Run all specs"
+task "spec" => "spec:all"
+
+namespace "spec" do
+  task "all" => ["strong_presenter", "generators", "integration"]
+
+  def spec_task(name)
+    desc "Run #{name} specs"
+    RSpec::Core::RakeTask.new(name) do |t|
+      t.pattern = "spec/#{name}/**/*_spec.rb"
+    end
+  end
+
+  spec_task "strong_presenter"
+  spec_task "generators"
+
+  desc "Run integration specs"
+  task "integration" => ["db:setup", "integration:all"]
+
+  namespace "integration" do
+    task "all" => ["development", "production", "test"]
+
+    ["development", "production"].each do |environment|
+      task environment do
+        Rake::Task["spec:integration:run"].execute environment
+      end
+    end
+
+    task "run" do |t, environment|
+      puts "Running integration specs in #{environment}"
+
+      ENV["RAILS_ENV"] = environment
+      success = system("rspec spec/integration")
+
+      raise "Integration specs failed in #{environment}" unless success
+    end
+
+    task "test" do
+      puts "Running rake in dummy app"
+      ENV["RAILS_ENV"] = "test"
+      run_in_dummy_app "rake"
+    end
+  end
+end
+
+namespace "db" do
+  desc "Set up databases for integration testing"
+  task "setup" do
+    puts "Setting up databases"
+    run_in_dummy_app "rm -f db/*.sqlite3"
+    run_in_dummy_app "RAILS_ENV=development rake db:schema:load db:seed"
+    run_in_dummy_app "RAILS_ENV=production rake db:schema:load db:seed"
+    run_in_dummy_app "RAILS_ENV=test rake db:schema:load"
+  end
+end
+

data/gemfiles/3.0.gemfile

@@ -0,0 +1,2 @@
+gem "rails", "~> 3.0.0"
+gem "active_model_serializers", "~> 0.7.0"

data/gemfiles/3.1.gemfile

@@ -0,0 +1,2 @@
+gem "rails", "~> 3.1.0"
+gem "devise", "~> 2.2"

data/gemfiles/3.2.gemfile

@@ -0,0 +1,2 @@
+gem "rails", "~> 3.2.0"
+gem "devise", "~> 2.2"

data/gemfiles/4.0.gemfile

@@ -0,0 +1,2 @@
+gem "rails", "~> 4.0.0"
+gem "devise", "~> 3.0.0"

data/gemfiles/4.1.gemfile

@@ -0,0 +1,2 @@
+gem "rails", github: "rails/rails"
+gem "devise", github: "plataformatec/devise"

data/lib/generators/controller_override.rb

@@ -0,0 +1,15 @@
+require "rails/generators"
+require "rails/generators/rails/controller/controller_generator"
+require "rails/generators/rails/scaffold_controller/scaffold_controller_generator"
+
+module Rails
+  module Generators
+    class ControllerGenerator
+      hook_for :presenter, default: true
+    end
+
+    class ScaffoldControllerGenerator
+      hook_for :presenter, default: true
+    end
+  end
+end

data/lib/generators/mini_test/presenter_generator.rb

@@ -0,0 +1,20 @@
+require 'generators/mini_test'
+
+module MiniTest
+  module Generators
+    class PresenterGenerator < Base
+      def self.source_root
+        File.expand_path('../templates', __FILE__)
+      end
+
+      class_option :spec, :type => :boolean, :default => false, :desc => "Use MiniTest::Spec DSL"
+
+      check_class_collision suffix: "PresenterTest"
+
+      def create_test_file
+        template_type = options[:spec] ? "spec" : "test"
+        template "presenter_#{template_type}.rb", File.join("test/presenters", class_path, "#{singular_name}_presenter_test.rb")
+      end
+    end
+  end
+end

data/lib/generators/mini_test/templates/presenter_spec.rb

@@ -0,0 +1,4 @@
+require 'minitest_helper'
+
+describe <%= class_name %>Presenter do
+end

data/lib/generators/mini_test/templates/presenter_test.rb

@@ -0,0 +1,4 @@
+require 'minitest_helper'
+
+class <%= class_name %>PresenterTest < StrongPresenter::TestCase
+end