# vim: ts=3 sw=3 et ft=org
#+TITLE: Nitrogen's jQuery Mobile Integration Guide
#+STYLE: <LINK href='../stylesheet.css' rel='stylesheet' type='text/css' />
#+AUTHOR: Jesse Gumm (@jessegumm)
#+OPTIONS:   H:2 num:1 toc:1 \n:nil @:t ::t |:t ^:t -:t f:t *:t <:t
#+EMAIL: 
#+TEXT: [[file:./index.org][Getting Started]] | *[[file:./api.org][API]]* | [[file:./elements.org][Elements]] | [[file:./actions.org][Actions]] | [[file:./validators.org][Validators]] | [[file:./handlers.org][Handlers]] | [[file:./config.org][Configuration Options]] | [[file:../about.org][About]]

* jQuery Mobile Integration

   Integrating jQuery Mobile into Nitrogen is a relatively painless process, but it does require making a few changes, particularly to the template.  For convenience, we provide a default template for mobile, coincidentally called "mobile.html".

** Include the necessary javascript.

   There are two new javascript files that must be included in order properly integrate with jQuery Mobile: jQuery mobile itself (jquery-mobile.js) and the Nitrogen jQuery Mobile script (nitrogen_jqm.js), which makes necessary structural changes to the Nitrogen object.

   The <script> elements in the head should look something like this. Please note that the order of these includes does matter.

#+BEGIN_SRC html
   <script type='text/javascript' src='/nitrogen/jquery.js'></script>
   <script type='text/javascript' src='/nitrogen/jquery-mobile.js'></script>
   <script type='text/javascript' src='/nitrogen/nitrogren.js'></script>
   <script type='text/javascript' src='/nitrogen/nitrogen_jqm.js'></script>
#+END_SRC

** Modify the HTML structure to what jQuery mobile expects

   jQuery mobile does some unique things as far as loading scripts, and providing inter-page transitions. However, in order to take advantage of these functionalities, certain strutural changes must happen with your template.

*** Separate the page into a handful of specific divs.

You want to separate the page into three specific divs with a wrapper div.

The wrapper div must have the attributes 'data-role="page"' and 'id="pagediv"'

Contained within the Wrapper div are expected three other divs with the data-roles "header", "content" and "footer".

This is demonstrated below:

#+BEGIN_SRC html
   <body>
      <div data-role="page" id="pagediv">
         <div data-role="header">
            <h1>[[[page:title()]]]</h1>
         </div>
         <div data-role="content">
            [[[page:body()]]]
         </div>
         <div data-role="footer">
            <h4>[[[page:footer()]]]</h4>
         </div>
      </div>
   </body>
#+END_SRC

*** The [[[script]]] tag loading properly.

   The last step in order to ensure the proper loading of javascript from page to page while using transitions, is to include the [[[script]]] section of the template inside a data-code attribute in the wrapper div.

This is demonstrated below:

#+BEGIN_SRC html
   <body>
      <div data-role="page" id="pagediv" data-code="[[[script]]]">
         <div data-role="header">
            <h1>[[[page:title()]]]</h1>
         </div>
         <div data-role="content">
            [[[page:body()]]]
         </div>
         <div data-role="footer">
            <h4>[[[page:footer()]]]</h4>
         </div>
      </div>
   </body>
#+END_SRC

** The Complete Template

To see the completed jQuery mobile template, check out ./site/templates/mobile.html in your Nitrogen instllation, or [[https://github.com/nitrogen/nitrogen/blob/master/rel/overlay/common/site/templates/mobile.html][see it on github]].

** See Also

   + [[./base.html][base element]]

   + [[./jquery_mobile.html][jQuery Mobile Elements]]

   + [[http://jquerymobile.com][jQuery Mobile Homepage]]
