jamieorc / elemental Goto Github PK

= 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.