Emy Documentation
Getting Started
You probably never heard about it, but Emy is initially a fork of a library called "iUI", created by Joe Hewitt. As he notes in the
iUI introductory blog post, it's intended to convert "ordinary standards-based HTML" into a polished UI that looks like a native iPhone app (this is not 2007 anymore so let's rather talk about "Mobile webapps"). if you are already using iUI, we created Switch to Emy from iUI for you.
Introduction
First, thanks for your interest in Emy Mobile web librarY!
In order to start playing with Emy, you first need to create a basic HTML file that pulls in Emy's CSS and Javascript, plus a couple of meta tags. Here's what it looks like:
Everything else will be done inside the body tag. The basic type of view in Emy is the panel-type view, which must be a top-level section element (i.e. directly under the body element) with a "panel" class. Let's start with a couple of views to scroll between and a toolbar (be sure to set selected="true" on the first view to display it by default or you won't see anything):
This should ends up looking something like this:
While this technically works, the link doesn't exactly look like a native app, nor does it comply with the Apple Human Interface Guidelines. For that, we should put the link in a table view. In Emy, a table view is an unordered list (ul), like this:
This should ends up looking something like this:
Of course, it doesn't do you a whole lot of good to have two screens without a way to navigate between them. Let's add a link, a third screen and a couple of IDs:
Now you should have a link on your first screen that does a smooth sideways animation to the second screen, which should look like this:
Congratulations! You've just created your first, working Emy application!
This sample app code is available here.
Advanced navigation
Navigating from a view to another is very simple using IDs. But if your app is made of dozens (or hundreds) of views containing images or a lot of texts, the initial loading time might quickly be a problem. Some of your views might also need to be generated on-demand when the user navigates to it.
To load an external view or a group of views from an external file, just put its URL in the href attribute, just like for regular web link. The two following files are 1) the main view 2) the external view.
index.html
view.frag
Emy loads asynchronously the content of the external file, adds it to the DOM and do a transition from the current view to this newly loaded view. While loading, Emy does set the selected attribute on the tapped link to "progress" rather than "selected". By default (iOS theme), it changes the arrow by a progress spinning loader (once loaded, "progress" is replaced by "selected").
This sample navigation code is available here (and view.frag)
You might also want to add some list items to the current list. This is mostly seen as a "Load more" link (but might be used anywhere else actually). By doing so, it loads its content from an external file just like in the previous example, but replaces the link element by what's in this external file.
index.html
more-links.frag
It should works like the following:
This sample navigation code is available here (and more-links.frag)
Congratulations again, you now know a lot about how simple it is to create a web application using Emy! See additionnal notes & links if you need more informations.
Additional notes
About .frag files, you can use .txt or .html as those file fragment extension. We use .frag since it contains a fragment of an HTML document so it does not sounds right to use .html without a proper header & body in this file. Feel free to use another extension if your server can't handle .frag, it just has to return a plain/text file stream like a .txt would do (and no, .frag has nothing to do with the Microsoft XPS file format).