Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Showcase Build Status Coverage Status

A simple (< 100 lines of code) but powerful exhibit/presenter implementation. It's framework agnostic: works with Rails, Padrino or just Sinatra.

Since version 0.2.0 Showcase is bundled with a set of optional "traits" you can pick and choose to augment your presenters with additional sugar (available in Rails 3+ only).

Why should I use presenters in my Rails app?

See Avdi's Exhibits introductory post.

Installation

Add this line to your application's Gemfile:

gem 'showcase'

And then execute:

$ bundle

Or install it yourself as:

$ gem install showcase

Usage

With Rails, you're already set, move on! With Padrino, include Showcase::Helpers::Present in your app helpers block.

helpers do
  include Showcase::Helpers::Present
end

You can now instantiate new presenters in your views using the included helpers:

# this is the object that needs to be presented
person = Person.new

# automatically infers presenter class to use based on person's class name
present(person) # => returns a PersonPresenter instance

# you can also explicitly tell what presenter to use
present(person, AdminPresenter) # => returns an AdminPresenter instance

# explicit presenter and context
present(person, PersonPresenter, context)

# maps each person in the collection with a presenter
present_collection([person]) # => returns an array of PersonPresenters

Define your presenters i.e. in a app/presenters folder:

class ProjectPresenter < Showcase::Presenter
  # automatically wraps the attribute into a PersonPresenter
  presents :person

  # automatically wraps the attribute into an AdminPresenter
  presents :person, with: AdminPresenter

  # expects project.tasks 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.
  # `object` refers to the object being presented
  def title
    h.link_to object.title, object
  end
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 Showcase::Presenter.

Traits

Please read the tests 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:

class ProjectPresenter < Showcase::Presenter
  include Showcase::Traits::Record
end
#dom_id
present(@project).dom_id # => "project_12"
#dom_class
present(@project).dom_class # => "project"
#box

Super useful in acceptance testing to check the presence of a record inside a view:

<% present(@project).box(class: 'big') do %>
  <p>Hi there!</p>
<% end %>

Produces the following:

<div class="project big" id="project_12">
  <p>Hi there</p>
</div>

Additional HTML attributes can be optionally specified within a config block inside the presenter:

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.

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:

<%= 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:

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:

<%= 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 URLs):

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_url(self)
  end
end

In your views:

<% content_for(:head) do %>
  <%= present(@project).seo_tags(title_suffix: ' - BaseClump') %>
<% end %>

Testing

Install gems:

$ bundle
$ bundle exec appraisal

Launch tests:

bundle exec appraisal rake

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

About

A barebone and framework agnostic exhibit pattern implementation

Resources

License

Packages

No packages published

Languages

You can’t perform that action at this time.