keynote 0.0.1 → 0.1.0

data/README.md

@@ -1,8 +1,246 @@
-## Keynote
+# Keynote
 
-Presenters for Rails.
+*Flexible presenters for Rails.*
 
-### TODO
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/rf-/keynote)
 
-* Generators.
-* Documentation.
+A presenter is an object that encapsulates view logic. Like Rails helpers,
+presenters help you keep complex logic out of your templates.
+
+Keynote provides a consistent interface for defining and instantiating
+presenters.
+
+## Usage
+
+### The basic idea
+
+A simple case is making a presenter that's named after a model class and holds
+helper methods related to that model.
+
+``` ruby
+# app/presenters/user_presenter.rb
+
+class UserPresenter < Keynote::Presenter
+  presents :user
+
+  def display_name
+    "#{user.first_name} #{user.last_name}"
+  end
+
+  def profile_link
+    link_to user, display_name, data: {user_id: user.id}
+  end
+end
+```
+
+You can then instantiate it by calling the `present` method (aliased to `k`) in
+a view, helper, controller, or another presenter.
+
+``` erb
+<%# app/layouts/_header.html.erb %>
+
+<div id="header">
+  ...
+  <div class="profile_link">
+    <%= k(current_user).profile_link %>
+  </div>
+</div>
+```
+
+If you pass anything other than a symbol as the first parameter of
+`present`/`k`, Keynote will assume you want to instantiate a presenter named
+after the class of that object -- in this case, the model is a `User`, so
+Keynote looks for a class called `UserPresenter`.
+
+### Generating HTML
+
+To make it easier to generate slightly more complex chunks of HTML, Keynote
+includes a modified version of Magnus Holm's [Rumble](https://github.com/judofyr/rumble)
+library. Rumble gives us a simple block-based syntax for generating HTML
+fragments. Here's a small example:
+
+``` ruby
+build_html do
+  div :id => :content do
+    h1 'Hello World', :class => :main
+  end
+end
+```
+
+Becomes:
+
+``` html
+<div id="content">
+  <h1 class="main">Hello World</h1>
+</div>
+```
+
+You can use tag helpers like `div`, `span`, and `a` only within a block passed
+to the `build_html` method. The `build_html` method returns a safe string. See
+[the documentation for `Keynote::Rumble`](http://rubydoc.info/gems/keynote/Keynote/Rumble)
+for more information.
+
+### A more complex example
+
+Let's add to our original example by introducing a named presenter. In addition
+to `UserPresenter`, which has general-purpose methods for displaying the User
+model, we'll create `HeaderPresenter`, which has methods that are specific to
+the `layouts/header` partial.
+
+``` ruby
+# app/presenters/header_presenter.rb
+
+class HeaderPresenter < Keynote::Presenter
+  presents :user
+
+  def profile_or_login_link
+    if logged_in? # defined in a helper
+      profile_link
+    else
+      login_link
+    end
+  end
+
+  def profile_link
+    build_html do
+      div class: 'profile_link' do
+        k(user).profile_link
+      end
+    end
+  end
+
+  def login_link
+    build_html do
+      div class: 'login_link' do
+        link_to 'Log In', login_url
+      end
+    end
+  end
+end
+```
+
+``` erb
+<%# app/layouts/_header.html.erb %>
+
+<% header = present(:header, current_user) %>
+
+<div id="header">
+  ...
+  <%= header.profile_or_login_link %>
+</div>
+```
+
+We've avoided putting a conditional in the template, and we've also avoided
+exposing the `profile_or_login_link` method to other parts of the app that
+shouldn't need to care about it. It's located in a class that's specific to
+this context.
+
+### Delegating to models
+
+If you want to delegate some calls on the presenter to one of the presenter's
+underlying objects, it's easy to do it explicitly with ActiveSupport's
+`delegate` API.
+
+``` ruby
+# app/presenters/user_presenter.rb
+
+class UserPresenter < Keynote::Presenter
+  presents :user
+  delegate :first_name, :last_name, :to => :user
+
+  def display_name
+    "#{first_name} #{last_name}"
+  end
+end
+```
+
+You can also generate prefixed methods like `user_first_name` by passing
+`:prefix => true` to the `delegate` method.
+
+## Rationale
+
+### Why use presenters or decorators at all?
+
+The main alternative is to use helpers. Helpers are fine for many use cases --
+Rails' built-in tag and form helpers are great. They have some drawbacks,
+though:
+
+* Every helper method you write gets mixed into the same view object as the
+  built-in Rails helpers, URL generators, and all the other junk that comes
+  along with `ActionView::Base`. In a freshly-generated Rails project:
+
+  ```ruby
+  >> ApplicationController.new.view_context.public_methods.count
+  => 318
+  >> ApplicationController.new.view_context.private_methods.count
+  => 119
+  ```
+
+* Helpers can't have state that isn't "global" relative to the view, which
+  can make it hard to write helpers that work together.
+
+* By default, every helper is available in every view. This makes it difficult
+  to set boundaries between different parts of your app and organize your view
+  code cleanly.
+
+### Why not use decorators?
+
+The biggest distinction between Keynote and similar libraries like
+[Draper](https://github.com/drapergem/draper) and
+[DisplayCase](https://github.com/avdi/display-case) is that Keynote
+presenters aren't decorators -- undefined method calls don't
+fall through to an underlying model.
+
+Applying the Decorator pattern to generating views is a reasonable thing to do.
+However, this practice also has some downsides.
+
+* Decorators make the most sense when there's exactly one object that's
+  relevant to the methods you want to encapsulate. They're less helpful when
+  you want to do things like define a class whose responsibility is to help
+  render a specific part of your user interface, which may involve bringing in
+  data from multiple models or collections.
+
+* When reading code that uses decorators, it often isn't obvious if a given
+  method is defined on the decorator or the underlying model, especially when
+  the decorator is applied in the controller instead of the view.
+
+* Passing decorated models between controllers and views can make it unclear
+  whether a view (especially a nested partial) depends on a model having some
+  specific decorator applied to it. This makes refactoring view and decorator
+  code harder than it needs to be.
+
+## Generators
+
+Keynote doesn't automatically generate presenters when you generate models or
+resources. To generate a presenter, you can use the `presenter` generator,
+like so:
+
+``` bash
+$ rails g presenter FooBar foo bar
+      create  app/presenters/foo_bar_presenter.rb
+      create  spec/presenters/foo_bar_presenter_spec.rb
+```
+
+That project uses RSpec, but the generator can also create test files for
+Test::Unit or MiniTest::Rails if applicable.
+
+## Compatibility
+
+Keynote is supported on Rails 3.0, 3.1, 3.2, and 4.0. Keynote presenters are
+testable with Test::Unit, RSpec, and MiniTest::Rails.
+
+If you find problems with any of the above integrations, please open an issue.
+
+## Development
+
+You can run Keynote's tests across all supported versions of Rails as follows:
+
+``` bash
+$ bundle install
+$ rake appraisal:gemfiles
+$ rake appraisal:install
+$ rake appraisal
+```
+
+Feel free to submit pull requests according to the usual conventions for Ruby
+projects.

data/lib/keynote.rb

@@ -8,8 +8,17 @@ require "keynote/helper"
 require "keynote/railtie"
 require "keynote/cache"
 
+# Keynote is a library for defining and instantiating presenters,
+# objects that encapsulate view logic.
+#
+# @see file:README.md
 module Keynote
   class << self
+    # @return [Boolean] When `use_caching` is enabled, repeatedly invoking
+    #   the same presenter with the same parameters will always return the
+    #   same object. This is disabled by default for now.
+    attr_accessor :use_caching
+
     # Create or retrieve a presenter wrapping zero or more objects.
     #
     # The first parameter is a Rails view context, but you'll usually access
@@ -47,7 +56,11 @@ module Keynote
         name = presenter_name_from_object(objects[0])
       end
 
-      Cache.fetch(name, view, *objects) do
+      if Keynote.use_caching
+        Cache.fetch(name, view, *objects) do
+          presenter_from_name(name).new(view, *objects)
+        end
+      else
         presenter_from_name(name).new(view, *objects)
       end
     end
@@ -62,4 +75,6 @@ module Keynote
       "#{name.to_s.camelize}Presenter".constantize
     end
   end
+
+  Keynote.use_caching = false
 end

data/lib/keynote/controller.rb

@@ -2,13 +2,14 @@
 
 module Keynote
   # `Keynote::Controller` is mixed into `ActionController::Base` and
-  # `ActionMailer::Base`, providing a `present` method for instantiating
-  # presenters.
+  # `ActionMailer::Base`, providing a `present` method (aliased to `k`) for
+  # instantiating presenters.
   module Controller
     # Instantiate a presenter.
     # @see Keynote.present
     def present(*objects)
       Keynote.present(view_context, *objects)
     end
+    alias k present
   end
 end

data/lib/keynote/helper.rb

@@ -2,13 +2,13 @@
 
 module Keynote
   # `Keynote::Helper` is mixed into `ActionView::Base`, providing a `present`
-  # method (aliased to `p`) for instantiating presenters.
+  # method (aliased to `k`) for instantiating presenters.
   module Helper
     # Instantiate a presenter.
     # @see Keynote.present
     def present(*objects)
       Keynote.present(self, *objects)
     end
-    alias p present
+    alias k present
   end
 end

data/lib/keynote/presenter.rb

@@ -1,6 +1,10 @@
 # encoding: UTF-8
 
 module Keynote
+  # Keynote::Presenter is a base class for presenters, objects that encapsulate
+  # view logic.
+  #
+  # @see file:README.md
   class Presenter
     include Keynote::Rumble
 
@@ -20,7 +24,7 @@ module Keynote
       #   end
       #
       #   # In a view
-      #   presenter = p(:post, @some_post, @some_user)
+      #   presenter = k(:post, @some_post, @some_user)
       #   presenter.blog_post # == @some_post
       #   presenter.author    # == @some_user
       #
@@ -55,7 +59,7 @@ module Keynote
     def present(*objects)
       Keynote.present(@view, *objects)
     end
-    alias p present
+    alias k present
 
     # @private
     def respond_to_missing?(method_name, include_private = true)

data/lib/keynote/rumble.rb

@@ -3,7 +3,7 @@
 module Keynote
   # HTML markup in Ruby.
   #
-  # To invoke Rumble, call the `html` method in a presenter.
+  # To invoke Rumble, call the `build_html` method in a presenter.
   #
   # ## 1. Syntax
   #
@@ -26,7 +26,7 @@ module Keynote
   # Example:
   #
   # ``` ruby
-  # html do
+  # build_html do
   #   div :id => :content do
   #     h1 'Hello World', :class => :main
   #   end
@@ -133,7 +133,7 @@ module Keynote
   #   presents :article
   #
   #   def published_at
-  #     html do
+  #     build_html do
   #       div.published_at do
   #         span.date publication_date
   #         span.time publication_time
@@ -321,8 +321,8 @@ module Keynote
     end
 
     # Generate HTML using Rumble tag methods. If tag methods are called
-    # outside an `html` block, they'll raise an exception.
-    def html
+    # outside a `build_html` block, they'll raise an exception.
+    def build_html
       ctx = @rumble_context
       @rumble_context = Context.new
       yield

data/lib/keynote/version.rb

@@ -2,5 +2,5 @@
 
 module Keynote
   # @private
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/spec/helper.rb

@@ -51,7 +51,7 @@ class NormalPresenter < Keynote::Presenter
   end
 
   def some_bad_html
-    html do
+    build_html do
       div { text some_bad_js }
       div { some_bad_js }
       div some_bad_js
@@ -67,7 +67,7 @@ module Keynote
     presents :model
 
     def generate_div
-      html do
+      build_html do
         div.hi! do
           link_to '#', 'Hello'
         end

data/spec/keynote_spec.rb

@@ -58,41 +58,60 @@ describe Keynote do
     end
   end
 
-  describe "memoization" do
-    it "should memoize on the model instance(s)" do
-      model_1 = Normal.new
-      model_2 = Normal.new
+  describe "caching" do
+    describe "enabled" do
+      before { Keynote.use_caching = true }
+      after  { Keynote.use_caching = false }
 
-      presented_1 = Keynote.present(:view, model_1)
-      presented_2 = Keynote.present(:view, model_1)
+      it "should cache on the model instance(s)" do
+        model_1 = Normal.new
+        model_2 = Normal.new
 
-      presented_1.must_be :equal?, presented_2
+        presented_1 = Keynote.present(:view, model_1)
+        presented_2 = Keynote.present(:view, model_1)
 
-      presented_3 = Keynote.present(:view, :combined, model_1, model_2)
-      presented_4 = Keynote.present(:view, :combined, model_1, model_2)
-      presented_5 = Keynote.present(:view, :combined, model_2, model_1)
+        presented_1.must_be :equal?, presented_2
 
-      presented_3.wont_be :equal?, presented_1
-      presented_3.must_be :equal?, presented_4
-      presented_3.wont_be :equal?, presented_5
-    end
+        presented_3 = Keynote.present(:view, :combined, model_1, model_2)
+        presented_4 = Keynote.present(:view, :combined, model_1, model_2)
+        presented_5 = Keynote.present(:view, :combined, model_2, model_1)
+
+        presented_3.wont_be :equal?, presented_1
+        presented_3.must_be :equal?, presented_4
+        presented_3.wont_be :equal?, presented_5
+      end
+
+      it "shouldn't cache if there are no models" do
+        presenter_1 = Keynote.present(:view, :empty)
+        presenter_2 = Keynote.present(:view, :empty)
 
-    it "shouldn't memoize if there are no models" do
-      presenter_1 = Keynote.present(:view, :empty)
-      presenter_2 = Keynote.present(:view, :empty)
+        presenter_1.wont_be :equal?, presenter_2
+      end
 
-      presenter_1.wont_be :equal?, presenter_2
+      it "should update the view every time" do
+        model = Normal.new
+
+        presenter_1 = Keynote.present(:view, model)
+        presenter_1.view.must_equal :view
+
+        presenter_2 = Keynote.present(:view_2, model)
+        presenter_2.must_be :equal?, presenter_1
+        presenter_2.view.must_equal :view_2
+      end
     end
 
-    it "should update the view every time" do
-      model = Normal.new
+    describe "disabled" do
+      before { Keynote.use_caching = false }
+
+      it "shouldn't cache" do
+        model_1 = Normal.new
+        model_2 = Normal.new
 
-      presenter_1 = Keynote.present(:view, model)
-      presenter_1.view.must_equal :view
+        presented_1 = Keynote.present(:view, model_1)
+        presented_2 = Keynote.present(:view, model_1)
 
-      presenter_2 = Keynote.present(:view_2, model)
-      presenter_2.must_be :equal?, presenter_1
-      presenter_2.view.must_equal :view_2
+        presented_1.wont_be :equal?, presented_2
+      end
     end
   end
 end

data/spec/railtie_spec.rb

@@ -6,13 +6,14 @@ describe Keynote::Railtie do
   let(:controller) { HelloController.new }
   let(:context)    { controller.view_context }
 
-  it "should make the present method available to controllers" do
+  it "should make the present and k methods available to controllers" do
     controller.must_respond_to :present
+    controller.must_respond_to :k
   end
 
-  it "should make the present and p methods available to views" do
+  it "should make the present and k methods available to views" do
     context.must_respond_to :present
-    context.must_respond_to :p
+    context.must_respond_to :k
   end
 
   it "should pass present call from controller to Keynote.present" do

data/spec/rumble_spec.rb

@@ -12,7 +12,7 @@ class TestRumble < MiniTest::Unit::TestCase
   def assert_rumble(str, &blk)
     exp = str.gsub(/(\s+(<)|>\s+)/) { $2 || '>' }
     res = nil
-    html {
+    build_html {
       res = yield.to_s
     }
     assert_equal exp, res
@@ -79,16 +79,16 @@ class TestRumble < MiniTest::Unit::TestCase
 
     assert_rumble str do
       div do
-        (%w[Hello World].map { |x| html { p x; p x } } * '|').html_safe
+        (%w[Hello World].map { |x| build_html { p x; p x } } * '|').html_safe
       end
     end
   end
 
   def test_capture_raise
     assert_raises RuntimeError do
-      html {
+      build_html {
         div do
-          html { raise }
+          build_html { raise }
         end
       }
     end
@@ -174,7 +174,7 @@ class TestRumble < MiniTest::Unit::TestCase
 
   def test_error_selfclosing_content
     assert_raises Rumble::Error do
-      html {
+      build_html {
         br "content"
       }
     end
@@ -182,7 +182,7 @@ class TestRumble < MiniTest::Unit::TestCase
 
   def test_error_css_proxy_continue
     assert_raises Rumble::Error do
-      html {
+      build_html {
         p.one("test").two
       }
     end
@@ -191,7 +191,7 @@ class TestRumble < MiniTest::Unit::TestCase
   # The real test here is if @rumble_context is nil in the teardown.
   def test_error_general
     assert_raises RuntimeError do
-      html {
+      build_html {
         div do
           raise
         end

metadata

@@ -1,128 +1,128 @@
 --- !ruby/object:Gem::Specification
 name: keynote
 version: !ruby/object:Gem::Version
-  version: 0.0.1
   prerelease: 
+  version: 0.1.0
 platform: ruby
 authors:
 - Ryan Fitzgerald
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-19 00:00:00.000000000 Z
+date: 2012-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rails
-  requirement: !ruby/object:Gem::Requirement
-    none: false
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
+    none: false
+  name: rails
   type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: 3.0.0
-- !ruby/object:Gem::Dependency
-  name: appraisal
-  requirement: !ruby/object:Gem::Requirement
     none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
+  name: appraisal
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
     none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
+  name: minitest
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: mocha
-  requirement: !ruby/object:Gem::Requirement
     none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
+  name: mocha
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
     none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
+  name: pry
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: redcarpet
-  requirement: !ruby/object:Gem::Requirement
     none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
+  name: redcarpet
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
     none: false
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
+  name: yard
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+    none: false
 description: ''
 email:
 - rwfitzge@gmail.com
@@ -170,23 +170,17 @@ rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -4215378202038736203
-required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -4215378202038736203
+  none: false
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24