epictetus / show_for Goto Github PK

ShowFor allows you to quickly show a model information with I18n features.

<%= show_for @user do |u| %>
  <%= u.attribute :name %>
  <%= u.attribute :nickname, :in => :profile %>
  <%= u.attribute :confirmed? %>
  <%= u.attribute :created_at, :format => :short %>
  <%= u.attribute :last_sign_in_at, :if_blank => "User did not access yet",
                  :wrapper_html => { :id => "sign_in_timestamp" } %>

  <% u.attribute :photo do %>
    <%= image_tag(@user.photo_url) %>
  <% end %>

  <%= u.association :company %>
  <%= u.association :tags, :to_sentence => true %>
<% end %>

Install the gem:

sudo gem install show_for

Or add ShowFor to your Gemfile and bundle it up:

gem 'show_for'

Run the generator:

rails generate show_for:install

And you are ready to go. Since this branch is aims Rails 3 support, if you want to use it with Rails 2.3 you should check this branch:

http://github.com/plataformatec/show_for/tree/v0.1

ShowFor allows you to quickly show a model information with I18n features.

<%= show_for @admin do |a| %>
  <%= a.attribute :name %>
  <%= a.attribute :confirmed? %>
  <%= a.attribute :created_at, :format => :short %>
  <%= a.attribute :last_sign_in_at, :if_blank => "Administrator did not access yet"
                  :wrapper_html => { :id => "sign_in_timestamp" } %>

  <% a.attribute :photo do %>
    <%= image_tag(@admin.photo_url) %>
  <% end %>

  <% a.value :biography %>
<% end %>

Will generate something like:

<div id="admin_1" class="show_for admin">
  <p class="wrapper admin_name">
    <strong class="label">Name</strong><br />
    José Valim
  </p>
  <p class="wrapper admin_confirmed">
    <strong class="label">Confirmed?</strong><br />
    Yes
  </p>
  <p class="wrapper admin_created_at">
    <strong class="label">Created at</strong><br />
    13/12/2009 - 19h17
  </p>
  <p id="sign_in_timestamp" class="wrapper admin_last_sign_in_at">
    <strong class="label">Last sign in at</strong><br />
    Administrator did not access yet
  </p>
  <p class="wrapper admin_photo">
    <strong class="label">Photo</strong><br />
    <img src="path/to/photo" />
  </p>
  <p class="wrapper admin_biography">
    Etiam porttitor eros ut diam vestibulum et blandit lectus tempor. Donec venenatis fermentum nunc ac dignissim.
    Pellentesque volutpat eros quis enim mollis bibendum. Ut cursus sem ac sem accumsan nec porttitor felis luctus.
    Sed purus nunc, auctor vitae consectetur pharetra, tristique non nisi.
  </p>
</div>

You also have the possibility to show a list of attributes, useful if you don’t need to change any configuration:

<%= show_for @admin do |a| %>
  <%= a.attributes :name, :confirmed?, :created_at %>
<% end %>

To show the proper value, before retrieving the attribute value, show_for first looks if a block without argument was given, otherwise checks if a :“human_#{attribute}” method is defined and, if not, only then retrieve the attribute.

show_for handles a series of options. Those are:

• :escape * - When the attribute should be escaped. True by default.

• :format * - Sent to I18n.localize when the attribute is a date/time object.

• :if_blank * - An object to be used if the value is blank. Not escaped as well.

Besides, all containers (:label, :content and :wrapper) can have their html options configured through the :label_html, :content_html and :wrapper_html options. Containers can have their tags configured on demand as well through :label_tag, :content_tag and :wrapper_tag options.

show_for also exposes the label method. In case you want to use the default human_attribute_name lookup and the default wrapping:

a.label :name                     #=> <strong class="label">Name</strong>
a.label "Name", :id => "my_name"  #=> <strong class="label" id="my_name">Name</strong>

Optionally, if you want to wrap the inner part of the label with some text (e.g. adding a semicolon), you can do so by specifying a proc for ShowFor.label_proc that will be called with any label text. E.g.:

ShowFor.label_proc = lambda { |l| l + ":" }

When taking this route, you can also skip on a per label basis by passing the :wrap_label option with a value of false.

show_for also supports associations.

<%= show_for @artwork do |a| %>
  <%= a.association :artist %>
  <%= a.association :artist, :using => :name_with_title %>
  <%= a.attribute :name_with_title, :in => :artist %>

  <%= a.association :tags %>
  <%= a.association :tags, :to_sentence => true %>
  <% a.association :tags do
    @artwork.tags.map(&:name).to_sentence
  end %>

  <% a.association :fans, :collection_tag => :ol do |fan| %>
    <li><%= link_to fan.name, fan %></li>
  <% end %>
<% end %>

The first is a has_one or belongs_to association, which works like an attribute to show_for, except it will retrieve the artist association and try to find a proper method from ShowFor.association_methods to be used. You can pass the option :using to tell (and not guess) which method from the association to use.

:tags is a has_and_belongs_to_many association which will return a collection. show_for can handle collections by default by wrapping them in list (<ul> with each item wrapped by an <li>). However, it also allows you to give :to_sentence or :join it you want to render them inline.

You can also pass a block which expects an argument to association. In such cases, a wrapper for the collection is still created and the block just iterates over the collection objects.

• José Valim (github.com/josevalim)

• Jonas Grimfelt (github.com/grimen)

If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.

github.com/plataformatec/show_for/issues

MIT License. Copyright 2010 Plataforma Tecnologia. blog.plataformatec.com.br