How to use jQuery Templates and JSON APIs with jQuery Mobile

You want to use APIs? Want to create dynamically pages on the fly? Want to do it without overwhelming the browser? Here's how....

Note: Here is this same example done with jsRender. jsRender is now the stated direction for templating by the jQuery team. Thanks to @ziodave for pointing this out. Despite that, I am leaving this original post intact because it may still be useful to somebody.

Author's Note:

Creating Mobile Apps with jQuery Mobile by Shane GliserPackt Publishing recruited me to write a book on jQuery Mobile!

Once you've read this article and found it useful, you should order my book. It's full of real world examples that span several industries and technologies using jQuery Mobile. The eBook editions are cheap and obviously, you know where to come if you have follow up questions ;-)

Check out Creating Mobile Apps with jQuery Mobile

For the base page, let's start out with the basic starting page from jquery mobile.

For an API, let's go with the example for getJSON from jQuery.

Next, call in the tempalte engine scripts...
<script src="http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.min.js"></script>

Then, create a spot for your templated content to live...
<script id="flickrTemplate" type="text/x-jquery-tmpl">

When we make our getJSON call, we'll transform the contents of the template with the returned data from the API call and add it wherever we like.
$("#flickrTemplate").tmpl(data).appendTo(document.body);

Here is the finished code but please don't stop at just viewing the source, I've got a few key takeaways afterwards.

view this example in action

Important consideration for creating dynamic pages in jquery mobile

  • jQuery Mobile does not (by default) instantly remove dynamically created pages like it does with pages that are simply ajaxed in through normal page-to-page navigation. This can be a blessing and a curse. It gives you something to go back to quickly so you don't have to re-render the content. However the more pages you create the closer you come to the point where your poor little mobile phone wont be able to take the strain due to the number of DOM elements. To make dynamically generated pages auto-remove like normal pages would, you'll need to execute this line of script from the example. newpage.attr( "data-" + $.mobile.ns + "external-page", true ).one( 'pagecreate', $.mobile._bindPageRemove );

  • The source shows two differnet $.mobile.changePage calls.
    The first one: $.mobile.changePage("#"+data.pageId); will find the page through selectors and then transition to. The change will also be reflected in the URL and thus show up in history.
    The second one: $.mobile.changePage(newpage); is being passed a direct jquery object reference to the page. Using this method will cause a page transition to the new content but will not affect the URL and thus not show up as an update in history.

  • jQuery Template content is held within a script tag and refernced by ID. <script id="flickrTemplate" type="text/x-jquery-tmpl"> jQuery Mobile does not try to parse or enhance the contents of these script files. The example is a single page example, even with these templates. It is not until templates are transformed with the data and the results are appended to the DOM that you can navigate to the pages.

  • This example is creating full pages. However, there is no reason that you could not use these same techniques to create page fragments and inject them into any portion of any jquery mobile page. For instance, if you were hitting some API on a regular interval and only updating a page's listview, you could simply use a template transformation and replace or append to the current listview and then call $("#some_list").listview("refresh");

  • jQuery Templates are relatively simple to use and have some powerful controlls including normal programming structures like if, else, and each loops. To get the most of our them, you should really read up on the template APIs and examples.

I hope you found this helpful. As always, you can leave a comment or send a message to hello@roughlybrilliant.com.

Now, go be brilliant!