forked from jquery-archive/jquery-mobile
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathdocs-pages.html
More file actions
executable file
·193 lines (132 loc) · 11 KB
/
docs-pages.html
File metadata and controls
executable file
·193 lines (132 loc) · 11 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>jQuery Mobile Docs - Pages</title>
<link rel="stylesheet" media="only all" href="../../themes/default/" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script type="text/javascript" src="../../js/jquery.js"></script>
<script type="text/javascript" src="../../js/"></script>
</head>
<body>
<div data-role="page">
<div data-role="header">
<h1>Anatomy of a Page</h1>
</div><!-- /header -->
<div data-role="content">
<p>The jQuery Mobile "page" structure is optimized to support either single pages, or local internal linked "pages" within a page.</p>
<p>The goal of this model is to allow developers to create websites using best practices — where ordinary links will "just work" without any special configuration — while creating a rich, native-like experience that can't be achieved with standard HTTP requests.</p>
<h2>Mobile page structure</h2>
<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.) In the 'head', references to jQuery, jQuery Mobile and the mobile theme CSS are all required to start things off:</p>
<pre><code>
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a2/jquery.mobile-1.0a2.min.css" />
<script type="text/javascript" src="http://code.jquery.com/jquery-1.4.4.min.js"></script>
<script type="text/javascript" src="http://code.jquery.com/mobile/1.0a2/jquery.mobile-1.0a2.min.js"></script>
</head>
<body>
...
</body>
</html>
</code></pre>
<p>Inside the <code><body></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:</p>
<div class="highlight">
<pre><span class="nt"><div</span> <span class="na">data-role=</span><span class="s">"page"</span><span class="nt">></span>
...
<span class="nt"></div></span>
</pre>
</div>
<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>
<div class="highlight">
<pre><span class="nt"><div</span> <span class="na">data-role=</span><span class="s">"page"</span><span class="nt">></span>
<span class="nt"><div</span> <span class="na">data-role=</span><span class="s">"header"</span><span class="nt">></span>...<span class="nt"></div></span>
<span class="nt"><div</span> <span class="na">data-role=</span><span class="s">"content"</span><span class="nt">></span>...<span class="nt"></div></span>
<span class="nt"><div</span> <span class="na">data-role=</span><span class="s">"footer"</span><span class="nt">></span>...<span class="nt"></div></span>
<span class="nt"></div></span>
</pre>
</div>
<h2>Complete single page template</h2>
<p>Putting it all together, this is the standard boilerplate page template you should start with:</p>
<pre><code>
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a2/jquery.mobile-1.0a2.min.css" />
<script type="text/javascript" src="http://code.jquery.com/jquery-1.4.3.min.js"></script>
<script type="text/javascript" src="http://code.jquery.com/mobile/1.0a2/jquery.mobile-1.0a2.min.js"></script>
</head>
<body>
<div data-role="page">
<div data-role="header">
<h1>Page Title</h1>
</div><!-- /header -->
<div data-role="content">
<p>Page content goes here.</p>
</div><!-- /content -->
<div data-role="footer">
<h4>Page Footer</h4>
</div><!-- /footer -->
</div><!-- /page -->
</body>
</html>
</code></pre>
<a href="page-template.html" data-inline="true" data-theme="b" data-role="button">View boilerplate template</a>
<h2>External page linking</h2>
<p>jQuery Mobile automates the process of building Ajax powered sites and applications. </p>
<p>By default, when you click on a link that points to an external page (ex. products.html), the framework will parse the link's <code>href</code> to formulate an Ajax request (Hijax) and displays the loading spinner.</p>
<p>If the Ajax request is successful, the new page content is added to the DOM, all mobile widgets are auto-initialized, then the new page is animated into view with a page transition.</p>
<p>If the Ajax request fails, the framework will display a small error message overlay (styled in the "e" swatch) that disappears after a brief time so this doesn't break the navigation flow. View an <a href="notapage.html">example of the error message</a>.</p>
<h2>Local, internal linked "pages"</h2>
<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>
<p>It's important to note if you are linking from a mobile page that was loaded via Ajax to a page with multiple internal pages, you need to add a <code>rel="external"</code> or <code>data-ajax="false"</code> to the link. This tells the framework to do a full page reload to clear out the Ajax hash in the URL. This is critical because Ajax pages use the hash (#) to track the Ajax history, while multiple internal pages use the hash to indicate internal pages so there will be a conflicts.</p>
<p>For example, a link to a page containing multiple internal pages would look like this:</p>
<code><a href="multipage.html" rel="external">Multi-page link</a></code>
<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>
<pre><code>
<body>
<!-- Start of first page -->
<div data-role="page" id="foo">
<div data-role="header">
<h1>Foo</h1>
</div><!-- /header -->
<div data-role="content">
<p>I'm first in the source order so I'm shown as the page.</p>
<p>View internal page called <a href="#bar">bar</a></p>
</div><!-- /content -->
<div data-role="footer">
<h4>Page Footer</h4>
</div><!-- /header -->
</div><!-- /page -->
<!-- Start of second page -->
<div data-role="page" id="bar">
<div data-role="header">
<h1>Bar</h1>
</div><!-- /header -->
<div data-role="content">
<p>I'm first in the source order so I'm shown as the page.</p>
<p><a href="#foo">Back to foo</a></p>
</div><!-- /content -->
<div data-role="footer">
<h4>Page Footer</h4>
</div><!-- /header -->
</div><!-- /page -->
</body>
</code></pre>
<a href="multipage-template.html" data-inline="true" data-theme="b" data-role="button" rel="external">View multi-page template</a>
<p> </p>
<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>
<h2>Back linking</h2>
<p>If you use the attribute <code>data-rel="back"</code> on an anchor, any clicks on that anchor will mimic the back button, going back one history entry and ignoring the anchor's default href. This is particularly useful when linking back to a named page, such as a link that says "home", or when generating "back" buttons with JavaScript, such as a button to close a dialog. When using this feature in your source markup, <strong>be sure to provide a meaningful href that actually points to the URL of the referring page (this will allow the feature to work for users in C-Grade browsers</strong>. Also, please keep in mind that if you just want a reverse transition without actually going back in history, you should use the <code>data-direction="reverse"</code> attribute instead.</p>
<h2>Redirects and linking to directories</h2>
<p>When linking to directory indexes (such as href="typesofcats/" instead of href="typesofcats/index.html"), you must provide a trailing slash. This is because jQuery Mobile assumes the section after the last "/" character in a url is a filename, and it will remove that section when creating base urls from which future pages will be referenced.</p>
<p>However, you can work around this issue by returning your page div with a <code>data-url</code> attribute already specified. When you do this, jQuery Mobile will use that attribute's value for updating the URL, instead of the url used to request that page. This also allows you to return urls that change as the result of a redirect, for example, you might post a form to "/login.html" but return a page from the url "/account" after a successful submission. This tool allows you to take control of the jQuery Mobile history stack in these situations. Here's an example:</p>
<p>The following link points to "docs-links-urltest/index.html": <a href="docs-links-urltest/index.html">Test Link</a> which is a directory with an index page. The return page will update the hash as "docs/pages/docs-links-urltest/" with a trailing slash. This is done via the data-url attribute in that page's source. Keep in mind that the value will replace the entire hash, and it is up to you to replace it with a URL that actually resolves to the correct page when requested via refresh or deep link.</p>
<p>Learn more about the technical details of the navigation model and <a href="docs-navmodel.html">Ajax, hashes and history</a> in jQuery mobile.</p>
</div><!-- /content -->
</div><!-- /page -->
</body>
</html>