iUI Documentation

Copyright (c) 2007-10, iUI Project Members. See LICENSE.txt for licensing terms. Version @VERSION@

This version of iUI has a partial implementation of the busy flag for Issue #191, it will not work with webapps that call iui.showPage() or iui.showPageByHref() directly. This issue will be resolved in a later version.

For a gentler introduction to iUI, check out the Getting Started Tutorial .

Event Handling

On Load

On load, iUI will determine which page to display primarily based on the anchor part of the URL (everything after #_ ) and secondarily based on the top-level (child of the body ) element with the selected attribute set to true . If these both exist, iui.showPage() will be called twice, but the anchor-based load will win because it is done second.

Link Click Handling

iUI captures all clicks on a elements and goes through a series of checks to determine what to do:

1. If the link has a href="#..." , iUI will navigate to the panel ID specified after the # (no underscore).
2. If the link's ID is backButton , iUI will navigate to the previous screen (see iui.goBack() ).
3. If the link has a type="submit" , iUI will find the parent form element, gather up all the input values and submit the form via AJAX (see iui.showPageByHref() ).
4. If the link has a type="cancel" , iUI will cancel the parent form element dialog.
5. If the link has a target="_replace" , iUI will do an AJAX call based on the href of the link and replace the panel that the link is in with the contents of the AJAX response.
6. If the link is a native URL (see iui.isNativeURL() ), iUI will do nothing.
7. If the link has a target="_webapp" , iUI will perform a normal link, navigating completely away from the iUI app and pointing the browser to the linked-to webapp instead.
8. If there is no target attribute, iUI will perform a normal (non-replace) AJAX slide (see iui.showPageByHref() ).

Div.toggle Click Handling

iUI also captures div.toggle clicks and displays/hides the element via setting a toggled attribute to true/false.

iUI Custom Events

iUI fires a number of custom events on your panel and dialog elements. Handling these events is the recommended way to do any just-in-time transformations or loading (besides the ajax pre-loading built into iUI).

Dialogs receive a focus event when they are shown and a blur event when hidden. Currently they don't receive any load or unload events.

Panels receive focus and blur events and also receive a load event and (only when going backwards away from a panel) an unload event.

When new pages are inserted into the DOM after an AJAX load, the body element receives a beforeinsert event with { fragment: frag } parameters and afterwards receives an afterinsert event with {insertedNode: docNode} parameters.

Both panels involved in a slide animation receive beforetransition and aftertransition events. The panel being navigated from receives event parameters { out :true } , the panel being navigated to receives { out: false }

.

Properties

iui.busy

This is set to true if a slide animation is in progress.

iui.animOn

Determines whether to do horizontal slide animations with CSS transitions (http://www.w3.org/TR/css3-2d-transforms/ ) where supported (defaults to true ). Otherwise, manual setInterval() style animations are performed (vertical slide animations are always done manually).

iui.ajaxErrHandler

If defined, this user-set function will be called when an AJAX call returns with an HTTP status other than 200 (currently all HTTP statuses other than 200 , even including 200-level statuses like 201 Created , are seen as errors).

iui.httpHeaders

An object defining headers to be sent with Ajax requests. This defaults to:

	  { 'X-Requested-With': 'XMLHttpRequest' }

Methods

iui.showPage(page[, backwards=false])

showPage() should probably be an internal function, outside callers should call showPageById() instead. showPage() doesn't set the busy flag because it is already set by the public-facing functions.

page is the html element to show. If backwards is set to true , it will display a right-to-left animation instead of the default left-to-right.

If the currently-displayed page is passed, iui will do nothing. showPage() is used for both panel-type pages and dialog-type pages (dialogs float on top of the panels, have a cancel button and do not participate in sliding animations). Panel-type pages receive blur/focus events and load/unload events, but dialog-type pages only receive blur/focus events.

iui.showPageById(pageId)

Looks up the page element by the id and checks the internal history to determine if the page is on the stack -- if so, it will call showPage() with backwards set to true , reversing the direction of the animation.

iui.goBack()

Navigates to the previous page in the history stack.

iui.replacePage(pageId)

Loads a new page at the same level in the history stack. Currently it will do a slide-in animation, but replaces the current page in the navStack. It should probably use a different animation (slide-up/slide-down).

iui.showPageByHrefExt(href, args, method, replace, cb)

Outside callers should use this version to do an ajax load programmatically from your webapp. In a future version, this will be renamed to showPageByHref() (once the old method and all its calls are renamed).

href is a URL string, method is the HTTP method (defaults to GET ), args is an Object of key-value pairs that are used to generate the querystring, replace is an existing element that either is the panel or is a child of the panel that the incoming HTML will replace (if not supplied, iUI will append the incoming HTML to the body ), and cb is a user-supplied callback function.

iui.showPageByHref(href, args, method, replace, cb)

This one should only be used by iUI internally. It should be renamed and possibly moved into the closure.

iui.ajax(url, args, method, cb)

Handles ajax requests and also fires a setTimeout() call to abort the request if it takes longer than 30 seconds. See showPageByHrefExt() above for a description of the various arguments (url is the same as href

).

iui.param(o)

Stripped-down, simplified object-only version of a jQuery function that converts an object of keys/values into a URL-encoded querystring.

iui.insertPages(frag)

If an AJAX call (showPageByHref() ) is made without supplying a replace element, insertPages() is called to insert the newly-created element fragment into the page DOM. Each child-node of the HTML fragment is a panel and if any of them are already in the DOM, they will be replaced by the incoming elements.

iui.getSelectedPage()

Returns the panel element that is currently being viewed. Each panel must be a direct child of the body element. A panel is set as the selected panel by setting the selected attribute to true

.

iui.isNativeUrl(href)

Determines whether the supplied URL string launches a native iPhone app (maps, YouTube, phone, email, etc). If so, iUI does nothing (doesn't attempt to load a page or slide to it) and allows the phone to handle it the click natively.

iui.hasClass(self, name)

Convenience function to determine if the given element (self ) has the class name .

iui.addClass(self, name)

Convenience function to add the given class name to element self

.

iui.removeClass(self, name)

Convenience function to remove the given class name to element self .