libs/js/jquery-mobile-1.1.0/docs/pages/page-anatomy.html

   1 <!DOCTYPE html>
   2 <html>
   3         <head>
   4         <meta charset="utf-8">
   5         <meta name="viewport" content="width=device-width, initial-scale=1">
   6         <title>jQuery Mobile Docs - Anatomy of a Page</title>
   7         <link rel="stylesheet"  href="../../css/themes/default/jquery.mobile.css" />
   8         <link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
   9
  10         <script src="../../js/jquery.js"></script>
  11         <script src="../../docs/_assets/js/jqm-docs.js"></script>
  12         <script src="../../js/"></script>
  13
  14 </head>
  15 <body>
  16
  17         <div data-role="page" class="type-interior">
  18
  19                 <div data-role="header" data-theme="f">
  20                 <h1>Anatomy of a Page</h1>
  21                 <a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
  22                 <a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
  23         </div><!-- /header -->
  24
  25         <div data-role="content">
  26                 <div class="content-primary">
  27                         <p>The jQuery Mobile "page" structure is optimized to support either single pages, or local internal linked "pages" within a page.</p>
  28
  29                         <p>The goal of this model is to allow developers to create websites using best practices &mdash; where ordinary links will "just work" without any special configuration &mdash; while creating a rich, native-like experience that can't be achieved with standard HTTP requests.</p>
  30
  31                         <h2>Mobile page structure</h2>
  32
  33                         <p>A jQuery Mobile site must start with an HTML5 'doctype' to take full advantage of all of the framework's features. (Older devices with browsers that don't understand HTML5 will safely ignore the 'doctype' and various custom attributes.) </p>
  34                         <p>In the 'head', references to jQuery, jQuery Mobile and the mobile theme CSS are all required to start things off. jQuery Mobile 1.1 works with both 1.6.4 and 1.7.1 versions of jQuery core. We recommend linking to the files hosted on the jQuery CDN for best performance: </p>
  35
  36 <pre><code>
  37 <strong>&lt;!DOCTYPE html&gt; </strong>
  38 &lt;html&gt;
  39         &lt;head&gt;
  40         &lt;title&gt;Page Title&lt;/title&gt;
  41
  42         &lt;meta name=&quot;viewport&quot; content=&quot;width=device-width, initial-scale=1&quot;&gt;
  43
  44         &lt;link rel=&quot;stylesheet&quot; href=&quot;http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css&quot; /&gt;
  45         &lt;script src=&quot;http://code.jquery.com/jquery-1.7.1.min.js&quot;&gt;&lt;/script&gt;
  46         &lt;script src=&quot;http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js&quot;&gt;&lt;/script&gt;
  47 &lt;/head&gt;
  48
  49 &lt;body&gt;
  50 ...content goes here...
  51 &lt;/body&gt;
  52 &lt;/html&gt;
  53 </code></pre>
  54
  55                         <h2>Viewport meta tag</h2>
  56                         <p>Note above that there is a meta <code>viewport</code> tag in the <code>head</code> to specify how the browser should display the page zoom level and dimensions. If this isn't set, many mobile browsers will use a "virtual" page width around 900 pixels to make it work well with existing desktop sites but the screens may look zoomed out and too wide. By setting the viewport attributes to <code>content=&quot;width=device-width, initial-scale=1&quot;</code>, the width will be set to the pixel width of the device screen. </p>
  57
  58                         <pre><code>&lt;meta name=&quot;viewport&quot; content=&quot;width=device-width, initial-scale=1&quot;&gt; </code></pre>
  59
  60                         <p>These settings do not disable the user's ability to zoom the pages, which is nice from an accessibility perspective. There is a minor issue in iOS that doesn't properly set the width when changing orientations with these viewport settings, but this will hopefully be fixed in a future release. You can set other viewport values to disable zooming if required since this is part of your page content, not the library. </p>
  61
  62                         <h2>Inside the body: Pages</h2>
  63                         <p>Inside the <code>&lt;body&gt;</code> tag, each view or "page" on the mobile device is identified with an element (usually a <code>div</code>) with the <code> data-role="page"</code> attribute. View the <a href="../api/data-attributes.html">data- attribute reference</a> to see all the possible attributes you can add to pages.</p>
  64
  65 <div class="highlight">
  66 <pre><span class="nt">&lt;div</span> <span class="na">data-role=</span><span class="s">"page"</span><span class="nt">&gt;</span>
  67         ...
  68 <span class="nt">&lt;/div&gt;</span>
  69 </pre>
  70 </div>
  71
  72                         <p>Within the "page" container, any valid HTML markup can be used, but for typical pages in jQuery Mobile, the immediate children of a "page" are divs with data-roles of <code>"header"</code>, <code>"content"</code>, and <code>"footer"</code>.</p>
  73
  74 <div class="highlight">
  75 <pre><span class="nt">&lt;div</span> <span class="na">data-role=</span><span class="s">"page"</span><span class="nt">&gt;</span>
  76         <span class="nt">&lt;div</span> <span class="na">data-role=</span><span class="s">"header"</span><span class="nt">&gt;</span>...<span class="nt">&lt;/div&gt;</span>
  77         <span class="nt">&lt;div</span> <span class="na">data-role=</span><span class="s">"content"</span><span class="nt">&gt;</span>...<span class="nt">&lt;/div&gt;</span>
  78         <span class="nt">&lt;div</span> <span class="na">data-role=</span><span class="s">"footer"</span><span class="nt">&gt;</span>...<span class="nt">&lt;/div&gt;</span>
  79 <span class="nt">&lt;/div&gt;</span>
  80 </pre>
  81 </div>
  82
  83
  84 <h2>Putting it together: Basic single page template</h2>
  85
  86 <p>Putting it all together, this is the standard boilerplate page template you should start with on a project: </p>
  87
  88 <pre><code>
  89 &lt;!DOCTYPE html&gt;
  90 &lt;html&gt;
  91         &lt;head&gt;
  92         &lt;title&gt;Page Title&lt;/title&gt;
  93
  94         &lt;meta name=&quot;viewport&quot; content=&quot;width=device-width, initial-scale=1&quot;&gt;
  95
  96         &lt;link rel=&quot;stylesheet&quot; href=&quot;http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css&quot; /&gt;
  97         &lt;script src=&quot;http://code.jquery.com/jquery-1.7.1.min.js&quot;&gt;&lt;/script&gt;
  98         &lt;script src=&quot;http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js&quot;&gt;&lt;/script&gt;
  99 &lt;/head&gt;
 100 &lt;body&gt;
 101
 102 &lt;div data-role=&quot;page&quot;&gt;
 103
 104         &lt;div data-role=&quot;header&quot;&gt;
 105                 &lt;h1&gt;Page Title&lt;/h1&gt;
 106         &lt;/div&gt;&lt;!-- /header --&gt;
 107
 108         &lt;div data-role=&quot;content&quot;&gt;
 109                 &lt;p&gt;Page content goes here.&lt;/p&gt;
 110         &lt;/div&gt;&lt;!-- /content --&gt;
 111
 112         &lt;div data-role=&quot;footer&quot;&gt;
 113                 &lt;h4&gt;Page Footer&lt;/h4&gt;
 114         &lt;/div&gt;&lt;!-- /footer --&gt;
 115 &lt;/div&gt;&lt;!-- /page --&gt;
 116
 117 &lt;/body&gt;
 118 &lt;/html&gt;
 119 </code></pre>
 120
 121                         <a href="page-template.html" data-inline="true" data-theme="b" data-role="button">View boilerplate template</a>
 122
 123
 124                 <h2>Multi-page template structure</h2>
 125
 126                         <p>A single HTML document can contain multiple 'pages' that are loaded together by stacking multiple divs with a <code> data-role</code> of <code>"page"</code>. Each 'page' block needs a unique ID (<code>id="foo"</code>) that will be used to link internally between 'pages' (<code>href="#foo"</code>). When a link is clicked, the framework will look for an internal 'page' with the ID and transition it into view.</p>
 127
 128                         <p>Here is an example of a 2 "page" site built with two jQuery Mobile divs navigated by linking to an ID placed on each page wrapper. Note that the IDs on the page wrappers are only needed to support the internal page linking, and are optional if each page is a separate HTML document. Here is what two pages look inside the <code>body</code> element.</p>
 129
 130 <pre><code>
 131 &lt;body&gt;
 132
 133 &lt;!-- Start of first page --&gt;
 134 &lt;div data-role=&quot;page&quot; id=&quot;foo&quot;&gt;
 135
 136         &lt;div data-role=&quot;header&quot;&gt;
 137                 &lt;h1&gt;Foo&lt;/h1&gt;
 138         &lt;/div&gt;&lt;!-- /header --&gt;
 139
 140         &lt;div data-role=&quot;content&quot;&gt;
 141                 &lt;p&gt;I&#x27;m first in the source order so I&#x27;m shown as the page.&lt;/p&gt;
 142                 &lt;p&gt;View internal page called &lt;a href=&quot;#bar&quot;&gt;bar&lt;/a&gt;&lt;/p&gt;
 143         &lt;/div&gt;&lt;!-- /content --&gt;
 144
 145         &lt;div data-role=&quot;footer&quot;&gt;
 146                 &lt;h4&gt;Page Footer&lt;/h4&gt;
 147         &lt;/div&gt;&lt;!-- /footer --&gt;
 148 &lt;/div&gt;&lt;!-- /page --&gt;
 149
 150
 151 &lt;!-- Start of second page --&gt;
 152 &lt;div data-role=&quot;page&quot; id=&quot;bar&quot;&gt;
 153
 154         &lt;div data-role=&quot;header&quot;&gt;
 155                 &lt;h1&gt;Bar&lt;/h1&gt;
 156         &lt;/div&gt;&lt;!-- /header --&gt;
 157
 158         &lt;div data-role=&quot;content&quot;&gt;
 159                 &lt;p&gt;I&#x27;m the second in the source order so I&#x27;m hidden when the page loads. I&#x27;m just shown if a link that references my ID is beeing clicked.&lt;/p&gt;
 160                 &lt;p&gt;&lt;a href=&quot;#foo&quot;&gt;Back to foo&lt;/a&gt;&lt;/p&gt;
 161         &lt;/div&gt;&lt;!-- /content --&gt;
 162
 163         &lt;div data-role=&quot;footer&quot;&gt;
 164                 &lt;h4&gt;Page Footer&lt;/h4&gt;
 165         &lt;/div&gt;&lt;!-- /footer --&gt;
 166 &lt;/div&gt;&lt;!-- /page --&gt;
 167 &lt;/body&gt;
 168 </code></pre>
 169
 170                 <a href="../../docs/pages/multipage-template.html" data-inline="true" data-theme="b" data-role="button" rel="external">View multi-page template</a>
 171
 172                 <p> </p>
 173
 174                 <p>PLEASE NOTE: Since we are using the hash to track navigation history for all the Ajax 'pages', it's not currently possible to deep link to an anchor (<code>index.html#foo</code>) on a page in jQuery Mobile, because the framework will look for a 'page' with an <code>ID</code> of <code>#foo</code> instead of the native behavior of scrolling to the content with that <code>ID</code>.</p>
 175
 176
 177 <h2>Conventions, not requirements</h2>
 178
 179 <p>Although the page structure outlined above is a recommended approach for a standard web app built with jQuery Mobile, the framework is very flexible with document structure. The page, header, content, and footer data-role elements are optional and are mostly helpful for providing some basic formatting and structure. The page wrapper that used to be required for auto-initialization to work is now optional for single page documents, so there isn't any required markup at all. For a web page with a custom layout, all of these structural elements can be omitted and the Ajax navigation and all widgets will work just like they do in the boilerplate structure. Behind the scenes, the framework will inject the page wrapper if it's not included in the markup because it’s needed for managing pages, but the starting markup can now be extremely simple. </p>
 180
 181 <p>Note that in a multi-page setup, you are required to have page wrappers in your markup in order to group the content into multiple pages.</p>
 182
 183
 184
 185
 186                                 </div><!--/content-primary -->
 187
 188                                 <div class="content-secondary">
 189
 190                                         <div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
 191
 192                                                         <h3>More in this section</h3>
 193
 194                                                         <ul data-role="listview" data-theme="c" data-dividertheme="d">
 195
 196                                                                 <li data-role="list-divider">Pages &amp; Dialogs</li>
 197                                                                 <li data-theme="a"><a href="page-anatomy.html">Anatomy of a page</a></li>
 198                                                                 <li><a href="page-template.html" data-ajax="false">Single page template</a></li>
 199                                                                 <li><a href="multipage-template.html" data-ajax="false">Multi-page template</a></li>
 200                                                                 <li><a href="page-titles.html">Page titles</a></li>
 201                                                                 <li><a href="page-links.html">Linking pages</a></li>
 202                                                                 <li><a href="page-transitions.html">Page transitions</a></li>
 203                                                                 <li><a href="page-dialogs.html">Dialogs</a></li>
 204                                                                 <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
 205                                                                 <li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
 206                                                                 <li><a href="page-dynamic.html">Dynamically injecting pages</a></li>
 207                                                                 <li><a href="page-scripting.html">Scripting pages</a></li>
 208                                                                 <li><a href="phonegap.html">PhoneGap apps</a></li>
 209                                                                 <li><a href="touchoverflow.html">touchOverflow feature</a></li>
 210                                                                 <li><a href="pages-themes.html">Theming pages</a></li>
 211
 212                                                         </ul>
 213                                         </div>
 214                                 </div>
 215
 216                         </div><!-- /content -->
 217
 218                         <div data-role="footer" class="footer-docs" data-theme="c">
 219                                         <p>&copy; 2011-12 The jQuery Foundation</p>
 220                         </div>
 221
 222                         </div><!-- /page -->
 223
 224                         </body>
 225                         </html>