gestart-showcase

A simple but powerful exhibit/presenter implementation.

This is a maintenance fork. gestart-showcase is Gestart's fork of showcase 0.2.5, whose last upstream release is dated 16/03/2014. It exists because the presenter layer sits under roughly 430 call sites in Gestart, and upstream will get no further fixes.

It gets repaired, not extended. It is fixed when Rails breaks it, and nothing more.

Compared to upstream: the namespace is GestartShowcase::, and the LinkTo, Seo and Share traits, the SeoMetaBuilder and FirstNonblank helpers and the presenter generator are gone — Gestart never called them. Traits::Record stays, box included. See CHANGELOG.md.

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 'gestart-showcase'

And then execute:

$ bundle

Or install it yourself as:

$ gem install gestart-showcase

Usage

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

helpers do
  include GestartShowcase::Helpers::Present
end

You can now instantiate new presenters in your controller/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 < GestartShowcase::Presenter
  # automatically wraps the attribute into a PersonPresenter
  presents :person

  # 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
  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

Traits

Please read the tests for a detailed explanation of each method available.

`GestartShowcase::Traits::Record`

To be used to present ActiveModel-based records. Inside your presenter, include the trait like this:

class ProjectPresenter < GestartShowcase::Presenter
  include GestartShowcase::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 < GestartShowcase::Presenter
  include GestartShowcase::Traits::Record

  box do |c|
    c.html_options class: 'another-class', role: 'project'
  end
end

Testing

Install gems:

$ bundle
$ rake appraisal:install

Launch tests:

rake appraisal

Contributing

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