prospecto 0.1.3 → 0.2.0

data/README.md

@@ -1,3 +1,143 @@
 # Prospecto
 
-*Simple rails presenter that emphasizes using plain old ruby.*
+*Simple rails presenter with an emphasis on just using ruby.*
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'prospecto'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install prospecto
+
+## Overview
+
+There are 2 problems that prospecto was created to solve.
+
+1. Views are hard and ineffective to test.
+2. Code is often common between the output formats.
+
+We feel that (our interpretation of) the presenter pattern is the answer to these problems. To be clear, you
+do not need a library to implement the presenter pattern.  The purpose of prospecto is to provide some syntactic
+sugar and structure.
+
+## Usage
+
+### ApplicationPresenter
+
+To start it is recommended (but not required) that you generate an `ApplicationPresenter`.  This will act
+as a base class for all other presenters much like an `ApplicationController`.  Just use the built in
+generator:
+
+    $ rails generate prospecto:install
+
+### Presenter
+
+You are now ready to start creating presenters.  In prospecto a presenter does not necessarily correlate with
+a model (though this often ends up as the case), instead a presenter represents a view or family of views
+depending on the situation.  This is up to you to decide.
+
+To create a simple presenter use the included generator:
+
+    $rails generate prospecto:presenter User
+
+### Prospecto::PresenterView
+
+By default all presenters inherit from the `Prospecto::PresenterView` class.  This class is optional and exists
+solely to provide some sugar for creating constructors for objects.
+
+#### accepts
+
+The `accepts` method is the most encouraged.  It creates a private accessor for
+the provided value.
+
+``` ruby
+class UserPresenter < Prospecto::PresenterView
+  accepts :user
+
+  def name
+    "#{user.first} #{user.last}"
+  end
+end
+
+view = UserPresenter.new(user: @user)
+puts user.name
+```
+
+#### decorates
+
+The `decorates` method allows the provided value to be accessed directly on the
+presenter.  This is simalar to how something like [draper](https://github.com/jcasimir/draper)
+works.
+
+``` ruby
+class UserPresenter < Prospecto::PresenterView
+  decorates :user
+end
+
+view = UserPresenter.new(user: @user)
+puts "#{view.first} #{view.last}"
+```
+
+#### proxies
+
+The `proxies` method creates named methods on the presenter for the provided value.
+
+``` ruby
+class UserPresenter < Prospecto::PresenterView
+  proxies :user
+end
+
+view = UserPresenter.new(user: @user)
+puts "#{view.user_first} #{view.user_last}"
+```
+
+#### presents
+
+The `presents` method is creates a public accessor for the provided value.  Use
+of this is discouraged.
+
+``` ruby
+class UserPresenter < Prospecto::PresenterView
+  presents :user_public
+end
+
+view = UserPresenter.new(user_public: @user)
+puts "#{view.user_public.first} #{view.user_public.last}"
+```
+
+### Rails Views and Controllers
+
+How you use the presenters is very loose.  Since you are just dealing with pretty vanilla
+ruby objects you can instantiate where it makes the most sense for your project.  Usually
+basic usage looks something like this.
+
+``` ruby
+class UserController < ApplicationController
+  def index
+    users = User.where(active: true)
+    @view = UserPresenter.new(users: users)
+  end
+end
+```
+
+You then use the `@view` object like normal in the view.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Sponsor
+
+Development for prospecto is sponsored mainly by my employer [Voonami](http://www.voonami.com)
+since we use it heavily in house.

data/lib/generators/prospecto/install/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Generate a base ApplicationPresenter class.
+
+    This is completely optional.  If an ApplicationPresenter is not found then
+    not base class will be set on new presenters.
+
+Example:
+    rails generate prospecto:install
+
+    This will create:
+        app/presenters/application_presenter.rb
+        spec/presenters/application_presenter_spec.rb

data/lib/generators/prospecto/install/install_generator.rb

@@ -0,0 +1,13 @@
+module Prospecto
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('../templates', __FILE__)
+
+    def write_application_presenter
+      template 'application_presenter.rb', "app/presenters/application_presenter.rb"
+    end
+
+    def write_application_presenter_spec
+      template 'application_presenter_spec.rb', "spec/presenters/application_presenter_spec.rb"
+    end
+  end
+end

data/lib/generators/prospecto/install/templates/application_presenter.rb

@@ -0,0 +1,6 @@
+class ApplicationPresenter < Prospecto::PresenterView
+  # Place common functionality here that will be shared with all presenters.
+
+  # Use of the Prospecto::PresenterView is completely optional and just gives a
+  # little initialization sugar.
+end

data/lib/generators/prospecto/install/templates/application_presenter_spec.rb

@@ -0,0 +1,4 @@
+require 'spec_helper'
+
+describe ApplicationPresenter do
+end

data/lib/generators/{presenter → prospecto/presenter}/USAGE

@@ -6,7 +6,7 @@ Description:
     presenter and the controller.
 
 Example:
-    rails generate presenter User
+    rails generate prospecto:presenter User
 
     This will create:
         app/presenters/user_presenter.rb

data/lib/generators/prospecto/presenter/presenter_generator.rb

@@ -0,0 +1,35 @@
+module Prospecto
+  class PresenterGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('../templates', __FILE__)
+
+    def write_presenter
+      template 'presenter.rb', "app/presenters/#{file_name_root}_presenter.rb"
+    end
+
+    def write_presenter_spec
+      template 'presenter_spec.rb', "spec/presenters/#{file_name_root}_presenter_spec.rb"
+    end
+
+    protected
+
+    def file_name_root
+      name.underscore
+    end
+
+    def class_name
+      name.camelize
+    end
+
+    def single_name
+      name.underscore.singularize
+    end
+
+    def base_class
+      if File.exists?(Rails.root.join("app/presenters/application_presenter.rb"))
+        "ApplicationPresenter"
+      else
+        "Prospecto::PresenterView"
+      end
+    end
+  end
+end

data/lib/generators/prospecto/presenter/templates/presenter.rb

@@ -0,0 +1,13 @@
+class <%= class_name %>Presenter < <%= base_class %>
+  # Use of the Prospecto::PresenterView is completely optional and just gives a
+  # little initialization sugar. Ala:
+  #
+  # Create a private accessor:
+  #   accepts :<%= single_name %>
+  #
+  # Create a public accessor:
+  #   presents :<%= single_name %>_public
+  #
+  # Create named proxy methods:
+  #   proxies :<%= single_name %>
+end

data/lib/prospecto/presenter_view.rb

@@ -1,9 +1,13 @@
+require "set"
+
 module Prospecto
   class PresenterView
     def initialize(args={})
       args.each do |name, value|
         if respond_to? name
           instance_variable_set("@#{name}", value)
+        elsif self.class.__delegates.include?(name)
+          __delegates << value
         else
           # Stop everything there is a design problem.
           raise ArgumentError.new("Unknown property '#{name}' for class '#{self.class.name}'.")
@@ -15,18 +19,28 @@ module Prospecto
       if property_name = self.class.__properties.find{|m| name.to_s.start_with? "#{m}_"}
         field_name = name.to_s.sub("#{property_name}_", "")
         self.send(property_name).send(field_name)
+      elsif delegate_obj = __delegates.find{|d| d.respond_to? name}
+        delegate_obj.send(name)
       else
         super
       end
     end
 
+    def __delegates
+      @__delegates ||= Set.new
+    end
+
     class << self
       # "Presents" means a member will be reflected out to the view. Use of presents should be
       # limited to very special cases.
       alias :presents :attr_reader
 
       def __properties
-        @__properties ||= []
+        @__properties ||= Set.new
+      end
+
+      def __delegates
+        @__delegates ||= Set.new
       end
 
       # Accepts means the view uses the member internally, but it is not available
@@ -48,6 +62,13 @@ module Prospecto
         end
         accepts(*args)
       end
+
+      # Decorates means that properties of the object will be available directly on the presenter.
+      def decorates(*args)
+        args.each do |name|
+          __delegates << name
+        end
+      end
     end
   end
 end

data/lib/prospecto/version.rb

@@ -1,3 +1,3 @@
 module Prospecto
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prospecto
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-17 00:00:00.000000000 Z
+date: 2012-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70145041443540 !ruby/object:Gem::Requirement
+  requirement: &70296683085180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 3.1.0
   type: :runtime
   prerelease: false
-  version_requirements: *70145041443540
+  version_requirements: *70296683085180
 - !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: &70145041442140 !ruby/object:Gem::Requirement
+  name: rspec
+  requirement: &70296683083860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70145041442140
+  version_requirements: *70296683083860
 - !ruby/object:Gem::Dependency
-  name: turn
-  requirement: &70145041441240 !ruby/object:Gem::Requirement
+  name: pry
+  requirement: &70296683082860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70145041441240
+  version_requirements: *70296683082860
 description: ''
 email:
 - bigjasonwebb@gmail.com
@@ -51,10 +51,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/generators/presenter/presenter_generator.rb
-- lib/generators/presenter/templates/presenter.rb
-- lib/generators/presenter/templates/presenter_spec.rb
-- lib/generators/presenter/USAGE
+- lib/generators/prospecto/install/install_generator.rb
+- lib/generators/prospecto/install/templates/application_presenter.rb
+- lib/generators/prospecto/install/templates/application_presenter_spec.rb
+- lib/generators/prospecto/install/USAGE
+- lib/generators/prospecto/presenter/presenter_generator.rb
+- lib/generators/prospecto/presenter/templates/presenter.rb
+- lib/generators/prospecto/presenter/templates/presenter_spec.rb
+- lib/generators/prospecto/presenter/USAGE
 - lib/prospecto/presenter_view.rb
 - lib/prospecto/railtie.rb
 - lib/prospecto/version.rb
@@ -63,39 +67,6 @@ files:
 - MIT-LICENSE
 - Rakefile
 - README.md
-- test/dummy/app/assets/javascripts/application.js
-- test/dummy/app/assets/stylesheets/application.css
-- test/dummy/app/controllers/application_controller.rb
-- test/dummy/app/helpers/application_helper.rb
-- test/dummy/app/views/layouts/application.html.erb
-- test/dummy/config/application.rb
-- test/dummy/config/boot.rb
-- test/dummy/config/database.yml
-- test/dummy/config/environment.rb
-- test/dummy/config/environments/development.rb
-- test/dummy/config/environments/production.rb
-- test/dummy/config/environments/test.rb
-- test/dummy/config/initializers/backtrace_silencers.rb
-- test/dummy/config/initializers/inflections.rb
-- test/dummy/config/initializers/mime_types.rb
-- test/dummy/config/initializers/secret_token.rb
-- test/dummy/config/initializers/session_store.rb
-- test/dummy/config/initializers/wrap_parameters.rb
-- test/dummy/config/locales/en.yml
-- test/dummy/config/routes.rb
-- test/dummy/config.ru
-- test/dummy/log/development.log
-- test/dummy/log/test.log
-- test/dummy/public/404.html
-- test/dummy/public/422.html
-- test/dummy/public/500.html
-- test/dummy/public/favicon.ico
-- test/dummy/Rakefile
-- test/dummy/README.rdoc
-- test/dummy/script/rails
-- test/prospecto_test.rb
-- test/test_helper.rb
-- test/view_test.rb
 homepage: http://github.com/bigjason/prospecto
 licenses: []
 post_install_message: 
@@ -110,7 +81,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2556641238186213598
+      hash: -977387351276312960
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -119,44 +90,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2556641238186213598
+      hash: -977387351276312960
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
-summary: Seperation of views and templates for rails projects.
-test_files:
-- test/dummy/app/assets/javascripts/application.js
-- test/dummy/app/assets/stylesheets/application.css
-- test/dummy/app/controllers/application_controller.rb
-- test/dummy/app/helpers/application_helper.rb
-- test/dummy/app/views/layouts/application.html.erb
-- test/dummy/config/application.rb
-- test/dummy/config/boot.rb
-- test/dummy/config/database.yml
-- test/dummy/config/environment.rb
-- test/dummy/config/environments/development.rb
-- test/dummy/config/environments/production.rb
-- test/dummy/config/environments/test.rb
-- test/dummy/config/initializers/backtrace_silencers.rb
-- test/dummy/config/initializers/inflections.rb
-- test/dummy/config/initializers/mime_types.rb
-- test/dummy/config/initializers/secret_token.rb
-- test/dummy/config/initializers/session_store.rb
-- test/dummy/config/initializers/wrap_parameters.rb
-- test/dummy/config/locales/en.yml
-- test/dummy/config/routes.rb
-- test/dummy/config.ru
-- test/dummy/log/development.log
-- test/dummy/log/test.log
-- test/dummy/public/404.html
-- test/dummy/public/422.html
-- test/dummy/public/500.html
-- test/dummy/public/favicon.ico
-- test/dummy/Rakefile
-- test/dummy/README.rdoc
-- test/dummy/script/rails
-- test/prospecto_test.rb
-- test/test_helper.rb
-- test/view_test.rb
+summary: Simple rails presenter with an emphasis on just using ruby.
+test_files: []

data/lib/generators/presenter/presenter_generator.rb

@@ -1,25 +0,0 @@
-class PresenterGenerator < Rails::Generators::NamedBase
-  source_root File.expand_path('../templates', __FILE__)
-
-  def write_presenter
-    template 'presenter.rb', "app/presenters/#{file_name_root}_presenter.rb"
-  end
-
-  def write_presenter_spec
-    template 'presenter_spec.rb', "spec/presenters/#{file_name_root}_presenter_spec.rb"
-  end
-
-  protected
-
-  def file_name_root
-    name.underscore
-  end
-
-  def class_name
-    name.camelize
-  end
-
-  def single_name
-    name.underscore.singularize
-  end
-end

data/lib/generators/presenter/templates/presenter.rb

@@ -1,8 +0,0 @@
-class <%= class_name %>Presenter < Prospecto::PresenterView
-  # The presenter class is completely optional and just gives a
-  # little initialization sugar. Ala:
-  #
-  #   accepts :<%= single_name %>
-  #   presents :<%= single_name %>_public
-  #
-end