Emy Documentation

Core Javascript File

For a gentler introduction to Emy, please check out the Getting Started documentation first.
If you already know and use iUI, our guide Switch to Emy from iUI might helps you a lot.

Event Handling

On Load

On load, Emy determines which view to display based on the top-level (child of the body) element with the selected attribute set to true. This view is set as the homescreen and will then always be the root view. If the anchor part of the URL (everything after #, known as "hash") is empty, this view's id attribute value will be added to the URL. Ex: if selected="true" is set on <section id="home" ... > in index.html, then on load, Emy adds #home, resulting to index.html#home. On load, this is done via location.assign(), so the browser history stack does not change.

The reason Emy does this is because it uses an anchor-based navigation mechanism like most mobile web libraries, which brings an automatic support of the browser's (and device's physical) back button. iPhone users might use Emy's toolbar back button as well as Safari's one, but Android or Blackberry or WindowsPhone users are more likely to use the device's physical back button.

on Click

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

If the link has a href="#...", Emy navigates to the first view in the DOM with an id attribute equals to what is specify after this #.

If the a (link) element has an ID equals to backButton, Emy navigates to the previous screen (see emy.goBack()). This is used only by the toolbar's back button.

If the a (link) has a data-type or an input / button element has a type equals to "submit", Emy looks for the parent form element, gathers up all the input values and submit the form via AJAX (see emy.showViewByHref()).

If the a (link) has a data-type or an input / button element has a type equals to "cancel", Emy cancels the parent form element dialog.

If the a (link) has a target equals to "_replace", Emy does an AJAX call based on the href value of this link, and replaces it with the content of the AJAX responseText.

If the a (link) is a native URL (see emy.isNativeURL()), Emy does nothing and let the browser do its job.

If the a (link) has a target="_webapp", Emy performs a normal link, navigating completely away from the Emy app and pointing the browser to the link. No AJAX call or sliding navigation is performed.

If there is no target attribute, Emy performs an AJAX call based on the href value of this link (see emy.showViewByHref()), adds as many views the responseText contains in its first node (see emy.insertViews()), and slides to the first of the newly created views.

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

Emy Custom Events

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

Focus / Blur

Views receive a focus event when they are shown and a blur event when hidden.

Load / Unload

Views receive a load event and (only when going backwards away from a panel) an unload event.

Dialog views (aka with the class dialog) don't receive any load or unload events.

Beforeinsert / Afterinsert

When new views are inserted into the DOM (see emy.insertViews()), the body element receives a beforeinsert event with { fragment: frag } parameters and afterwards receives an afterinsert event with {insertedNode: docNode} parameters.

Beforetransition / Aftertransition

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

Properties

emy.logging

If set to true, emy.log() performs a console.log() if the browser supports it.
Default value is false.

emy.busy

This is set to true if a slide animation or an AJAX call is in progress.
Default value is false.

emy.transitionMode

Determines whether to do slide animations with CSS3, Javascript with setInterval or no animation at all. Value can then be "css3", "js" or "none" and is checked before each transition. If your browser doesn't support CSS3 transitions, then Emy uses Javascript.
Default value is "css3".

emy.ajaxErrHandler

If defined, this user-set function is 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. A status of 0 is treated as success for file:// URLs).
Default value is null.

emy.httpHeaders

An object defining headers to be sent with Ajax requests.
Default value is { 'X-Requested-With': 'XMLHttpRequest' }.

emy.prefixedProperty

An array containing vendor-prefixed methods for transform, transition, transitionEnd, animationDuration & animationEnd. It is populated by the onLoad event function, and only used by the slideViews() function.
This array has no default value (empty array).

Methods

emy.showView(view, backward)

view: a view element (DOM Element)
backward: true / false (Boolean)

view is the html element to show. If backward is set to true, it performs a right-to-left transition instead of the default left-to-right.

If view is the currently-displayed view, Emy does nothing. showView() is used for both panel-type views and dialog-type views (dialogs float on top of others, have a cancel button and do not participate in sliding animations). Panel-type views receive blur/focus events and load/unload events, but dialog-type views only receive blur/focus events.

emy.showViewById(viewId)

viewId: the ID value of a view (string)

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 showView() with backward set to true, reversing the direction of the animation.

emy.goBack(viewId)

viewId: the ID value of a view (string)

Navigates back to the view in the history stack equals to viewId's id. If viewId is not set, it just goes back to the previous one.

emy.showViewByHref(url, args, method, replace, cb)

url: a valid URL (string)
args: key-value pairs (object)
method: HTTP method (string - "GET" by default)
replace: the element to replace (DOM element)
cb: callback function.

href should be a valid URL to a file, set as a string. If not valid, Emy triggers emy.ajaxErrHandler.
args parameter is an object of key-value pairs that are used to generate the querystring in case of a GET call.
method defines how the Ajax call should send args value, with "GET" & "POST" being the two possible values.
replace parameter is an existing element that either is the panel or is a child of the view that the incoming HTML will replace (if not supplied, Emy appends the incoming HTML to the body.
cb is a user-supplied callback function, triggered when the job is done.

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

url: a valid URL (string)
args: key-value pairs (object)
method: HTTP method (string - "GET" by default)
cb: callback function.

Handles ajax requests and also fires a setTimeout() call to abort the request if it takes longer than ajaxTimeoutVal (default is 30sec).

href should be a valid URL to a file, set as a string. If not valid, Emy triggers emy.ajaxErrHandler.
args parameter is an object of key-value pairs that are used to generate the querystring in case of a GET call.
method defines how the Ajax call should send args value, with "GET" & "POST" being the two possible values.
cb is a user-supplied callback function, triggered when the job is done.

emy.param(o)

o: key-value pairs (object)

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

emy.insertViews(frag)

frag: HTML fragment (fragment)

If an AJAX call (see showViewByHref()) is made without supplying a replace element, insertViews() is called to insert the newly-created element fragment into the DOM. Each child-node of the HTML fragment is a view
Note that if any of them are already in the DOM (aka same id value), they will be replaced by the incoming elements.

emy.getSelectedView()

Returns the currently selected view element, which means its selected attribute equals true.

emy.getAllViews()

Returns all views in the DOM.

emy.isNativeUrl(url)

url: a valid URL (string)

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

emy.hasClass(self, name)

self: a DOM element
name: a string

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

emy.addClass(self, name)

self: a DOM element
name: a string

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

emy.changeClass(self, name)

self: a DOM element
name: a string

Convenience function to change a given class name to element self. You can also use this to remove a class, by simply leave name to an empty string.

emy.$(a)

a: string

Convenience function to select elements in Emy.
if the a parameter's first letter is a "#", it selects the element with the id equals to this string without the "#".
if the a parameter's first letter is a ".", it selects all elements with the class containing this string without the ".".
if the a parameter contains a "." but not at the first letter, it splits the string, uses letters before the "." as a tag element name, then selects all those tag elements with the class containing what's after the ".".
if the a parameter contains nothing but letters, it selects all elements being equal to it.

We uses $ not to mimic JQuery but because one single caracter is quick to type. Since it's inside the emy object, JQuery won't bother if you use/need it.

emy.log(a)

a: string

Alias function of console.log(a). Main difference is that it tests if your browser supports it and if emy.logging is set to true so you can switch back logging even in production.

More ressources

Getting started guide
For a gentler introduction to Emy.
Emy's CSS documentation
For designers, here is the complete guide of default elements and how we style them.
Emy community on Google+
Official community's talks, links, events & discussions about Emy
iPhoneWebDev Google Group / mailing-list
Last but not least, you may find some very useful support from this worldwide community
Follow Emy on Facebook
Like the Emy Facebook page to get latest images, links & news on the biggest network worldwide