RubyDoc.info: File: README – Documentation for mbleigh-uberkit (0.0.4)

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…

<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…

<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…

<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