showcase 0.1.7 → 0.2.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 93da90243af0c3fe8b795954fbdf5df12a28007b
-  data.tar.gz: 463b88936212e9e181cb15fe44613e947ab116cb
+  metadata.gz: 3abceb896eb37c725738c997b0bddcb09e74605b
+  data.tar.gz: 8ad7e9cd6cc06b41bf2008f1e25a4116eed1e80f
 SHA512:
-  metadata.gz: b7a38f5e9d326581b10ea36a15ffd78019a5b3fae9deb475ed6565723e187e3894383ee1ec3c8574784cd3c25e65aeed63f8793891ca8b66db588780371e615a
-  data.tar.gz: 69ed3a3ac0c0dbc8c7a12f4d1b0fd018a5ffe465ddb611de1ba576e2fbca792e692b09296a93e33e6a90eb63fb447d9821dda374a9122c6e3ba30a838218d059
+  metadata.gz: 1ff5470207bd67524b1de59fa28e4bc9970c2488ed9df89392a8630f939e1f0d5bea6445528cbfbf9e9f3c631b4765f001cd4acccd45208c217fbf8978583ba0
+  data.tar.gz: 1454964cabb2b9f4be47fee3d041a3f3cdcbe061375a29de485d96bb10ae564c23100ea06643c92bcda3589f692f1ce74e0fa5b3356746b2c2676ad8f4c080fa

data/.rspec

@@ -0,0 +1,2 @@
+
+

data/.travis.yml

@@ -1,4 +1,12 @@
 language: ruby
+
 rvm:
   - "1.9.3"
-script: "bundle exec rspec spec"
+  - "2.0.0"
+
+gemfile:
+  - "gemfiles/activerecord3.gemfile"
+  - "gemfiles/activerecord4.gemfile"
+
+script: "bundle exec rake spec"
+

data/Appraisals

@@ -0,0 +1,8 @@
+appraise "activerecord3" do
+  gem "activerecord", "3.2.14"
+end
+
+appraise "activerecord4" do
+  gem "activerecord", "4.0.0"
+end
+

data/Gemfile

@@ -2,3 +2,6 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in basic_presenter.gemspec
 gemspec
+
+gem "appraisal"
+

data/README.md

@@ -1,17 +1,15 @@
-# Showcase [![Build Status](https://travis-ci.org/welaika/showcase.png?branch=master)](https://travis-ci.org/welaika/showcase) [![Coverage Status](https://coveralls.io/repos/welaika/showcase/badge.png?branch=master)](https://coveralls.io/r/welaika/showcase)
+# Showcase [![Build Status](https://travis-ci.org/stefanoverna/showcase.png?branch=master)](https://travis-ci.org/stefanoverna/showcase) [![Coverage Status](https://coveralls.io/repos/stefanoverna/showcase/badge.png?branch=master)](https://coveralls.io/r/stefanoverna/showcase)
 
-A simple (< 100 lines of code) but powerful exhibit/presenter implementation. It's framework agnostic: works with Rails, Padrino or simply Sinatra.
+A simple (< 100 lines of code) but powerful exhibit/presenter implementation.
+It's framework agnostic: works with Rails, Padrino or just Sinatra.
 
-## Properties of the Exhibit pattern
+Since version 0.2.0 Showcase is bundled with [a set of "traits"](https://github.com/stefanoverna/showcase#traits)
+you can pick and choose to augment your presenters with additional sugar
+(available in Rails 3+ only).
 
-Citing [Avdi's introductory post](http://devblog.avdi.org/2012/06/04/displaycase-gem-now-available/):
+## Why should I use presenters in my Rails app?
 
-* **It wraps a single model instance.** Not an assortment of objects.
-* **It is a true Decorator.** All unrecognized messages are passed through to the underlying object. This facilitates a gradual migration to the use of Exhibits to encapsulate presentation knowledge, since they can be layered onto models without any change to the existing views. It also enables multiple Exhibits to be layered onto an object, each handling different aspects of presentation.
-* **It brings together a model and a context.** Exhibits need a reference to a “context” object—either a controller or a view context—in order to be able to render templates as well as construct URLs for the object or related resources.
-* **It encapsulates decisions about how to render an object.** The tell-tale of an Exhibit is telling an object “render yourself”, rather than explicitly rendering a template and passing the object in as an argument.
-* **It may modify the behavior of an object.** For instance, an Exhibit might impose a scope on a `Blog#entries` association which only returns entries that are visible to the current user (as determined from the Exhibit’s controller context). Or it might reformat the return value of a `#social_security_number` method to include dashes and have all but the last four digits obscured: `***-**-5678`.
-* **There is a many-to-many relationship between model classes and exhibit classes.** One generic exhibit class may apply to several different types of model. Other exhibits may be specific, not just to a model, but to a model in a particular state, or within a particular viewing context.
+See [Avdi's Exhibits introductory post](http://devblog.avdi.org/2012/06/04/displaycase-gem-now-available/).
 
 ## Installation
 
@@ -29,15 +27,8 @@ Or install it yourself as:
 
 ## Usage
 
-With Rails, include `Showcase::Helpers` into your controller and/or views:
-
-```ruby
-# config/initializers/showcase.rb
-ActionController::Base.send :include, Showcase::Helpers
-ActionView::Base.send :include, Showcase::Helpers
-```
-
-With Padrino, include `Showcase::Helpers` in your app `helpers` block.
+With Rails, you're already set, move on! With Padrino, include `Showcase::Helpers`
+in your app `helpers` block.
 
 ```ruby
 helpers do
@@ -45,7 +36,8 @@ helpers do
 end
 ```
 
-You can now instantiate new presenters in your controller/views using the included helpers:
+You can now instantiate new presenters in your controller/views using the
+included helpers:
 
 ```ruby
 # this is the object that needs to be presented
@@ -74,7 +66,8 @@ class ProjectPresenter < Showcase::Presenter
   # automatically wraps the attribute into an AdminPresenter
   presents :person, with: AdminPresenter
 
-  # expects project.task to return an enumerable. automatically wraps each task in a TaskPresenter presenter
+  # expects project.task to return an enumerable. automatically wraps each task
+  # in a TaskPresenter presenter
   presents_collection :tasks
 
   # you can use `view_context`, or the shortcut `h`, to access the context.
@@ -85,6 +78,178 @@ class ProjectPresenter < Showcase::Presenter
 end
 ```
 
+## Rails
+
+### Generators
+
+Showcase comes with a generator to create new presenters a little faster:
+
+```
+rails generate showcase:presenter User
+```
+
+Will generate `app/presenters/user_presenter.rb`. If your Rails app has the file
+`app/presenters/base_presenter.rb`, the newly created presenter will inherit
+from `BasePresenter` instead of `Shocase::Presenter`.
+
+### Traits
+
+Please [read the tests](https://github.com/stefanoverna/showcase/tree/master/lib/showcase/traits) 
+for a detailed explanation of each method available.
+
+#### `Showcase::Traits::Record`
+
+To be used to present ActiveModel-based records. Inside your presenter, include
+the trait like this:
+
+```ruby
+class ProjectPresenter < Showcase::Presenter
+  include Showcase::Traits::Record
+end
+```
+
+##### `#dom_id`
+
+```ruby
+present(@project).dom_id # => "project_12"
+```
+
+##### `#dom_class`
+
+```ruby
+present(@project).dom_class # => "project"
+```
+
+##### `#box`
+
+Super useful in acceptance testing to check the presence of a record inside a
+view:
+
+```erb
+<% present(@project).box do %>
+  <p>Hi there!</p>
+<% end %>
+```
+
+Produces the following:
+
+```html
+<div class="project" id="project_12">
+  <p>Hi there</p>
+</div>
+
+Additional HTML attributes can be optionally specified within a config block 
+inside the presenter:
+
+```ruby
+class ProjectPresenter < Showcase::Presenter
+  include Showcase::Traits::Record
+
+  box do |c|
+    c.html_options class: 'another-class', role: 'project'
+  end
+end
+```
+
+#### `Showcase::Traits::LinkTo`
+
+Adds a nice DSL to declare links within your presenter.
+
+```ruby
+class ProjectPresenter < Showcase::Presenter
+  include Showcase::Traits::LinkTo
+
+  link_to do |c|
+    c.url           h.project_path(self)
+    c.label         name
+    c.active        h.controller_name == 'projects'
+    c.active_class  'current'
+    c.html_options  role: 'label'
+  end
+
+  link_to :tasks do
+    c.url     h.project_tasks_path(self)
+    c.label   "Tasks"
+  end
+end
+```
+
+In your views:
+
+```erb
+<%= project.url %>
+<%= project.tasks_url %>
+
+<%= project.link_active? %>
+<%= project.tasks_link_active? %>
+
+<%= project.link %>
+<%= project.tasks_link %>
+
+<%= project.link('Alternative label') %>
+<%= project.link(class: 'additional_class') %>
+<%= project.link do %>
+  Link content!
+<% end %>
+```
+
+#### `Showcase::Traits::Share`
+
+Useful to produce social share links:
+
+```ruby
+class ProjectPresenter < Showcase::Presenter
+  include Showcase::Traits::Share
+
+  share do |c|
+    c.url         h.project_path(self)
+    c.text        name
+    c.image_url   cover_image
+  end
+end
+```
+In your views:
+
+```erb
+<%= project.twitter_share_url %>
+<%= project.twitter_share_link %>
+<%= project.twitter_share_link('Alternative label') %>
+<%= project.twitter_share_link(class: 'additional_class') %>
+<%= project.twitter_share_link do %>
+  Link content!
+<% end %>
+
+<%= project.facebook_share_link %>
+<%= project.gplus_share_link %>
+<%= project.pinterest_share_link %>
+<%= project.linkedin_share_link %>
+```
+
+#### `Showcase::Traits::Seo`
+
+Useful to produce SEO meta tags (title, description, Facebook OpenGraph,
+Twitter cards, and canonical URL):
+
+```ruby
+class ProjectPresenter < Showcase::Presenter
+  include Showcase::Traits::Seo
+
+  seo do |c|
+    c.title           name
+    c.description     [ description, 'Fallback description if blank' ]
+    c.image_url       cover_thumb_image
+    c.canonical_url   h.project_path(self)
+  end
+end
+```
+In your views:
+
+```erb
+<% content_for(:head) do %>
+  <%= present(@project).seo_tags(title_suffix: ' - BaseClump') %>
+<% end %>
+```
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1 +1,14 @@
-require "bundler/gem_tasks"
+require 'rubygems'
+require 'bundler/setup'
+require 'appraisal'
+
+desc 'Default: run specs'
+task default: :spec
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "spec/**/*_spec.rb"
+end
+
+Bundler::GemHelper.install_tasks
+

data/gemfiles/activerecord3.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "activerecord", "3.2.14"
+
+gemspec :path=>"../"

data/gemfiles/activerecord4.gemfile

@@ -0,0 +1,8 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "activerecord", "4.0.0"
+
+gemspec :path=>"../"

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

@@ -4,8 +4,10 @@ module Showcase
       source_root File.expand_path(File.join(File.dirname(__FILE__), 'templates'))
 
       def create_presenter
+        @base_presenter = File.exist?('app/presenters/base_presenter.rb') ? "BasePresenter" : "Showcase::Presenter"
         template 'presenter.rb', File.join('app/presenters', class_path, "#{file_name}_presenter.rb")
       end
     end
   end
 end
+

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

@@ -1,4 +1,5 @@
 <% module_namespacing do -%>
-class <%= class_name %>Presenter < Showcase::Presenter
+class <%= class_name %>Presenter < <%= @base_presenter %>
 end
 <% end -%>
+

data/lib/showcase/helpers/config_object.rb

@@ -0,0 +1,28 @@
+require 'ostruct'
+
+module Showcase
+  module Helpers
+    class ConfigObject
+      def initialize(context, &block)
+        @config_block = block
+        @context = context
+      end
+
+      def to_struct
+        OpenStruct.new(to_hash)
+      end
+
+      def to_hash
+        @result = {}
+        @context.instance_exec(self, &@config_block)
+        @result.symbolize_keys
+      end
+
+      def method_missing(name, *args, &block)
+        name = name.to_s.gsub(/=$/, '')
+        @result[name.to_sym] = args.first
+      end
+    end
+  end
+end
+

data/lib/showcase/helpers/html_options.rb

@@ -0,0 +1,22 @@
+class HtmlOptions
+  def initialize(options = {})
+    @options = (options || {}).symbolize_keys
+  end
+
+  def add_class!(css_class)
+    @options[:class] ||= ""
+    css_classes = @options[:class].split(/\s+/)
+    css_classes << css_class
+    @options[:class] = css_classes.join(" ")
+  end
+
+  def merge_attrs!(options = {})
+    options = (options || {}).symbolize_keys
+    @options.merge!(options)
+  end
+
+  def to_h
+    @options.dup
+  end
+end
+

data/lib/showcase/helpers/seo_meta_builder.rb

@@ -0,0 +1,56 @@
+module Showcase
+  module Helpers
+    class SeoMetaBuilder
+      attr_reader :context
+
+      def initialize(context)
+        @context = context
+      end
+
+      def title(values, options = {})
+        title = first_nonblank(values)
+        title += options[:title_suffix] if options[:title_suffix]
+
+        context.content_tag(:title, title) <<
+        seo_meta_tags(:og_title, :twitter_title, values)
+      end
+
+      def description(values, options = {})
+        seo_meta_tags(:description, :og_description, :twitter_description, values)
+      end
+
+      def image_url(image_url, options = {})
+        seo_meta_tags(:og_image, :twitter_image, image_url)
+      end
+
+      def canonical_url(url, options = {})
+        seo_meta_tags(:og_url, url) <<
+        context.tag(:link, rel: "canonical", "href" => url)
+      end
+
+      private
+
+      def first_nonblank(values)
+        Array(values).map(&:presence).compact.first
+      end
+
+      def seo_meta_tags(*args)
+        value = first_nonblank(args.pop)
+
+        return nil unless value.present?
+
+        args.map do |name|
+          chunks = name.to_s.split("_")
+          attr_name = if chunks.first == 'og'
+            'property'
+          else
+            'name'
+          end
+          name = chunks.join(':')
+          context.tag(:meta, attr_name => name, content: value)
+        end.join.html_safe
+      end
+    end
+  end
+end
+

data/lib/showcase/presenter.rb

@@ -12,6 +12,7 @@ module Showcase
     alias_method :object, :__getobj__
     alias_method :h, :view_context
     alias_method :try, :__send__
+    alias_method :__decorator_class__, :class
 
     def initialize(obj, context)
       super(obj)

data/lib/showcase/railtie.rb

@@ -0,0 +1,12 @@
+require 'showcase/traits'
+
+module Showcase
+  class Railtie < Rails::Railtie
+    initializer "action_view.initialize_showcase" do
+      ActiveSupport.on_load(:action_view) do
+        ActionView::Base.send :include, Showcase::Helpers
+      end
+    end
+  end
+end
+

data/lib/showcase/traits/base.rb

@@ -0,0 +1,23 @@
+module Showcase
+  module Traits
+    module Base
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        private
+
+        def define_method?(name_chunks, &block)
+          method_name = Array(name_chunks).map(&:to_s).map(&:presence).compact.join("_")
+          if method_defined?(method_name)
+            false
+          else
+            define_method(method_name, &block)
+            true
+          end
+        end
+      end
+
+    end
+  end
+end
+

data/lib/showcase/traits/link_to.rb

@@ -0,0 +1,37 @@
+require 'showcase/helpers/config_object'
+require 'showcase/helpers/html_options'
+
+module Showcase
+  module Traits
+
+    module LinkTo
+      extend ActiveSupport::Concern
+      include Base
+
+      module ClassMethods
+        def link_to(name = nil, &block)
+          define_method? [name, :url] do
+            Helpers::ConfigObject.new(self, &block).to_struct.url
+          end
+
+          define_method? [name, :link_active?] do
+            Helpers::ConfigObject.new(self, &block).to_struct.active
+          end
+
+          define_method? [name, :link] do |*args, &link_block|
+            config = Helpers::ConfigObject.new(self, &block).to_struct
+
+            html_options = HtmlOptions.new(config.html_options)
+            html_options.merge_attrs!(args.extract_options!)
+            html_options.add_class!(config.active_class || 'active') if config.active
+
+            args = Array(config.label) if args.empty? && !link_block
+            h.link_to *args, config.url, html_options.to_h, &link_block
+          end
+        end
+      end
+    end
+
+  end
+end
+

data/lib/showcase/traits/record.rb

@@ -0,0 +1,61 @@
+module Showcase
+  module Traits
+
+    module Record
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        def box(&block)
+          @box_config_block = block
+        end
+
+        def __box_config_block__
+          @box_config_block
+        end
+      end
+
+      def dom_id
+        record_identifier.dom_id(self)
+      end
+
+      def dom_class
+        record_identifier.dom_class(self)
+      end
+
+      def box(*args, &block)
+        options = args.extract_options!
+        tag = args.pop || :div
+
+        config_block = self.__decorator_class__.__box_config_block__
+        config_options = if config_block
+                           Helpers::ConfigObject.new(self, &config_block).to_struct.html_options
+                         else
+                           {}
+                         end
+
+        html_options = HtmlOptions.new(config_options)
+        html_options.merge_attrs!(options)
+        html_options.add_class!(dom_class)
+        html_options.merge_attrs!(id: dom_id)
+
+        h.content_tag(tag, html_options.to_h) do
+          h.capture(self, &block)
+        end
+      end
+
+      private
+
+      def record_identifier
+        if defined?(ActionView::RecordIdentifier)
+          ActionView::RecordIdentifier
+        elsif defined?(ActionController::RecordIdentifier)
+          ActionController::RecordIdentifier
+        else
+          raise 'No RecordIdentifier found!'
+        end
+      end
+    end
+
+  end
+end
+

data/lib/showcase/traits/seo.rb

@@ -0,0 +1,27 @@
+require 'showcase/helpers/config_object'
+require 'showcase/helpers/seo_meta_builder'
+
+module Showcase
+  module Traits
+    module Seo
+      extend ActiveSupport::Concern
+      include Base
+
+      module ClassMethods
+
+        def seo(name = nil, options = {}, &block)
+          define_method? [name, :seo_tags] do |options = {}|
+            meta = Helpers::ConfigObject.new(self, &block).to_hash
+            builder = Helpers::SeoMetaBuilder.new(view_context)
+            parts = %w(title description canonical_url image_url canonical_url).map(&:to_sym)
+            parts.map do |tag|
+              builder.send(tag, meta[tag], options) if meta[tag]
+            end.compact.join.html_safe
+          end
+        end
+
+      end
+    end
+  end
+end
+