noelrappin / rails-iui Goto Github PK

rails_iui
========

A Rails wrapper around the iUI library for creating web applications.

This was originally created as a set of examples for some articles that should
be appearing soon. I'm releasing them as a plugin in the hope they'll be 
somewhat useful, even in their current partial state.

4-21-2008: Still functionally incomplete, and somewhat embarrassingly, without
automated tests.

More Info
=========

Details on iUI can be found at http://code.google.com/p/iui/

The URL for this repository is http://github.com/noelrappin/rails-iui/tree/master

The clone URL is git://github.com/noelrappin/rails-iui.git

Contact
=======

Contact the author at noelrappin at gmail.com

Example
=======

The rails_iui plugin does three things.

A series of Rake tasks will download iUI and insert it in the current Rails
project, changing the image URLs in the CSS file to match the standard Rails
layout.

rake iui:install  #download and install
rake iui:install_compact #download and install the compact version of iui
rake iui:clean    #removes iui files

The module ActionController::IphoneController adds support for recognizing
Mobile Safari as the :iphone pseudo-MIME type.

In your controller (can be ApplicationController) add the line

acts_as_iphone_controller

And any respond_to block can include iphone as an option, looking for 
.iphone.erb files in the view directory. Passing the argument true, as in
acts_as_iphone_controller(true) turns on test mode, where all requests are
treated as iphone regardless of user agent string. This is useful for testing
in some of the iPhone simulators. You'll need to restart the server for test
mode changes to take effect.

In your views, several methods from the IuiHelper module are automatically
imported into your application and are available throughout.  

viewport_tag(options = {})
  Builds the Mobile Safari meta viewport tag, pass the option 
  :device_width => true to specify the options for applications optimized for
  iPhone. More options to come.

include_iui_files 
  Place in the header of your layout, includes the tags for the iUI CSS and
  JavaScript files. Also defines the $ function, as in prototype.

button_link_to(name, options, html_options = {})
  Creates a link with the iUI CSS class of "button"
 
link_to_replace(name, options, html_options = {}) 
  An iUI link which replaces the link tag with the result text. Designed to
  be used for an anchor inside a list

link_to_external(name, options, html_options = {}) 
  An iUI link to an external item, this is an regular HTTP request, as 
  opposed to what iUI normally does, which is an Ajax request
  
link_to_target(target, name, options, html_options = {})
  An iUI link of a type based on the target parameter

iui_toolbar(initial_caption, search_url = nil)
  Sets the toolbar -- the caption is the heading. If there is a search_url,
  then a search button is added to the right side

iui_list(items, options = {}) 
  Creates an iPhone style of list. The items are expected to respond to the
  methods :caption -- the text display for the list, and :url, the url to
  go to when the item is selected. The :top and :bottom options specify
  text to be displayed above or below the list items. The :more option 
  specifies an item to go at the end of the list as a link_to_replace. The
  :as_replace options sends the list items without a surrounding ul tag, to
  be the response to a link_to_replace.
  
iui_grouped_list(items, options = {}, &group_by_block)
  Same as iui_list, but groups each item by their response to the 
  group_by_block
  
fieldset(&block)
  Wrapper around the iUI usage of a fieldset tag
  
row(label_text = "", &block)
  Wrapper around the iUI row (inside a fieldset) for rounded rectangles
  
row_label(&block)
  Wrapper for an iUI row that is just a label
  
panel(&block)
  Wrapper for an iUI div class panel

dialog(&block)
  Wrapper for an iUI div class dialog

servicelink_tel(telno)
  Creates a service link when a correctly formatted telephone number string is given (telno).
  Triggres the iPhone Phone App so that a call is initiated.

servicelink_email(email)
  Creates a service link when to the mail application. A mailto type link is created
  Triggres the iPhone Email App.

servicebutton_map(gadr,caption)
  Creates a service button to the maps application. The gadr parameter is a correctly 
  formatted google adress string. 
  A good place to implement the gadr method is in your people/adress model. Like so:
	def gadr
		 "#{street},#{zip} #{city},#{country}"
	end
  caption is the text that goes into the button 

observe_orientation_change(url_options = {})
  Place in the layout header file, the url_options is any Rails URL format.
  The URL gets a callback when the iPhone's orientation changes. The 
  parameter "position" is set to "0" for upright, "90" for counter-clockwise
  landscape, and "-90" for clockwise landscape
  
register_orientation_change
  Must be placed inside the body tag for the layout for observe_orientation_change
  to work.


Upcoming
========

Tests
Better documentation

Better JavaScript effects



Copyright (c) 2008 Noel Rappin, released under the MIT license