uberkit

= 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 'uberkit'

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
• , accepts block for contents
• submenu - accepts a block yielding a new menu object

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