HTML Elements as ERB Helper-Methods
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
MIT-LICENSE
README
Rakefile
init.rb
install.rb
uninstall.rb

README

= Elemental

=== HTML Element Names as Helper Methods
    
=== Summary
Introduces builder-like syntax to rhtml:
    
    <%= p @item.content %>
    <%= p span @person.first_name, :id => dom_id(@person, "name_") %>

or even

    <% table do @list.each do |item| tr do %>
      <%= td item.name %>
      <%= td item.content %>
    <% end end end %>

Elemental allows you to use XHTML Transitional tags as helper methods in your rhtml. With traditional ERb, the code above would be written:

    
    <p><%= @item.content %></p>
    <p><span id="<%= dom_id(@person, "name_") %>"><%= @person.first_name %></span></p>

and

    <table>
      <% @list.each do |item| -%>
      <tr>
        <td><%= item.name %></td>
        <td><%= item.content %></td>
      </tr>
      <% end %>
    </table>
   
That's more code, more noise as angle-brackets (especially embedded inside the html tag), and more lines. Elemental's syntax is also cleaner and terser than when using _content_tag_:


    <%= content_tag "p", @item.content %>
    <%= content_tag "p", content_tag "span", @person.first_name, :id => dom_id(@person, "name_") %>

and you can't send a block to _content_tag_

    <table>
      <% @list.each do |item| -%>
      <tr>
        <%= content_tag "td", item.name %>
        <%= content_tag "td", item.content %>
      </tr>
      <% end %>
    </table>
    <table>
    
=== Usage

Elemental has three basic usages:

  1. Self-closing tags: no argument, or hash only for argument: 
      <% br %>
      <% br :class => "someClass" %>
      
  2. Content tags: first argument is the value of the content: 
      <%= p "some content" %>
      <%= p "some content", :id => dom_id(@object) %>
      
  3. Content tags with a block argument:
      <% div :class => "some-class" do %>
        ...
      <% end %>

You can nest Elemental methods:

    <%= p span @object.value %>
      or
    <%= p(span(@object.value)) %>
      generates:
    <p><span>the object's value</span></p>

The same thing with attributes (pay attention to your parentheses):

    <%= p span @object.value, :id => "some_id", :class => "some_class" %>
      generates:
    <p><span id="some_id" class="some_class">the object's value</span></p>
      while
    <%= p span(@object.value, :id => "some_id"), :class => "some_class" %>
      generates:
    <p class="some_class"><span id="some_id">the object's value</span></p>
    
You can nest the methods in blocks:

    <% p do %>
      <% span :class => "someClass" do %>
        Lorem ipsum dolor sit amet, consectetur adipisicing elit, 
        sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
      <% end %>
    <% end %>
    or
    <% p do span :class => "someClass" do %>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, 
      sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    <% end end %>
      which both generate:
    <p>
      <span class="someClass">
        Lorem ipsum dolor sit amet, consectetur adipisicing elit, 
        sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
      </span>
    </p>

This is useful for loops:

    <% ul do ['one', 'two', 'three'].each do |item| %>
      <%= li item %>
    <% end end %>
      which generates:
    <ul>
      <li>one</li>
      <li>two</li>
      <li>three</li>
    </ul>

=== Options/Attributes Hash
Options are converted to regular html attributes. None are filtered, so you can certainly insert invalid attributes.

    <%= span :id => "some_id", :bogus_attribute => "some_value"%>
      generates:
    <span id="some_id" bogus_attribute="some_value"></span>
    
=== Omitted Tags
Rails' ActionView::Helpers already defines _form_, _select_, and _input_, so these are omitted from Elemental.

=== Motivation
Afer using Markaby a bit, I decided there were situations where I wanted a Markaby or Builder-type syntax within rhtml's context. I had been using _content_tag_ quite a bit for convenience, but wanted more _legible_ and _concise_ code, espcially for loops.

=== Acknowledgments
_why for Markaby and its list of XHTML and XHTML Transitional tag lists, which I used.