README

Uberkit
=======

The Uberkit is a set of helpers to ease the development of common UI
practices.

Installation
------------

Uberkit is available both as a gem and as a traditional plugin. To use
it as a gem, add this to your environment.rb:

  config.gem 'mbleigh-uberkit', :lib => 'uberkit', :source => 'http://gems.github.com/'
  
To install it as a plugin (Rails 2.1 or later):

  script/plugin install git://github.com/mbleigh/uberkit.git
  
UberForms
---------

UberForms provide a simple context for building forms in a DRYer
manner by abstracting the markup into a simple, CSS-styleable
format. It is available as a form builder as Uberkit::Forms::Builder,
but is likely more useful when used in one of the helper forms:
uberform_for or remote_uberform_for.

=== Basic Example

<% uberform_for :user do |f| %>
  <%= f.text_field :login %>
  <%= f.password_field :password %>
  <%= f.submit "Submit"%>
<% end %>

Becomes...

<form method="post" class="uberform" action="/users">
  <div class="field_row">
    <label for="user_login">Login:</label>
    <input type="text" size="30" name="user[login]" id="user_login" class="text_field"/>
    <br/>
  </div>
  <div class="field_row">
    <label for="user_password">Password:</label>
    <input type="password" size="30" name="user[password]" id="user_password" class="password_field"/>
    <br/>
  </div>
  <button type="submit">Submit</button>
</form>

=== Labels, Help, and Descriptions

You can pass options into a given field to set a custom label,
some help text, or a description of the field.

<%= f.text_field :login, :label => "Username", 
                         :help => "Only a-z and underscores.", 
                         :description => "The name you will use to log in." %>

Becomes...

<div class="field_row">
  <label for="user_login">Username:</label>
  <input type="text" size="30" name="user[login]" label="Username" id="user_login" help="Only a-z and underscores." description="The name you will use to log in." class="text_field"/>
  <span class="help">Only a-z and underscores.</span>
  <span class="description">The name you will use to log in.</span>
  <br/>
</div>

=== Custom Fields

Maybe the built-in form helpers won't do it for you. In that case, you
can use the custom helper to insert arbitrary HTML that still plays
nice with the rest of UberForms:

<% f.custom :label => "State", :for => "user_state" do |f| %>
  <%= state_select :user, :state %>
<% end %>

Becomes...

<div class="field_row">
  <label for="user_state">State:</label>
  <div class="pseudo_field">
    <select id="user_state">...</select>
  </div> 
  <br/>
</div>

UberMenu
--------

UberMenu is the simplest way to generate the markup for CSS menus,
including state representation and special hooks for cross-browser
advanced CSS needs.

=== Basic Example

<% ubermenu do |m| %>
  <% m.action 'Home', '/' %>
  <% m.action 'Users', users_path %>
  <% m.action 'Log Out', logout_path, :class => "special" %>
<% end %>

Becomes...

<ul>
  <li class="first current first_current"><a href="/">Home</a></li>
  <li><a href="/users">Users</a></li>
  <li class="special last"><a href="/logout">Log Out</a></li>
</ul>

=== Submenus

You can nest ubermenus for subnavigation using the 'submenu' method.
If you pass :delegate instead of a url to the submenu option, it will
automatically pick up the url of the first action in the submenu instead.

<% ubermenu 'nav' do |m| %>
  <% m.action 'Home', home_path %>
  <% m.submenu 'Services', services_home_path do |s| %>
    <% s.action 'Service A', service_path('a') %>
    <% s.action 'Service B', service_path('b') %>
  <% end %>
<% end %>

=== State

UberMenus automatically retain state using the current_page? helper.
You can specify further by passing a :current boolean expression to 
evaluate whether or not the menu item is selected:

<% ubermenu 'nav' do |m| %>
  <% m.action 'Users', users_path, :current => controller.controller_name == 'users' %>
<% end %>

=== Method Listing

* action - like link_to with additional options (see below)
    :current - a boolean expression to determine whether this menu option is selected,
        works with current_page? (if current_page? is true this will be true regardless)
    :force_current - boolean expression that ignores the current_page?
    :disabled - adds 'disabled' to class and forces non-current
* remote_action - like link_to_remote
* custom_action - only builds the outer <li>, accepts block for contents
* submenu - accepts a block yielding a new menu object

Copyright (c) 2008 Michael Bleigh and Intridea, Inc., released under the MIT license