This repository has been archived by the owner on Oct 8, 2021. It is now read-only.
/
page-links.html
147 lines (99 loc) · 12.1 KB
/
page-links.html
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
<!DOCTYPE html>
<html class="ui-mobile-rendering">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>jQuery Mobile Docs - Linking Pages</title>
<link rel="stylesheet" href="../../css/themes/default/jquery.mobile.css" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="../../js/jquery.js"></script>
<script src="../../docs/_assets/js/jqm-docs.js"></script>
<script src="../../js/"></script>
</head>
<body>
<div data-role="page" class="type-interior">
<div data-role="header" data-theme="f">
<h1>Linking pages</h1>
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
<a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
</div><!-- /header -->
<div data-role="content">
<div class="content-primary">
<h2>Linking pages</h2>
<p>jQuery Mobile is designed to work with simple page linking conventions. Essentially, you can link pages and assets as you normally would, and jQuery Mobile will automatically handle page requests in a single-page model, using Ajax when possible. When Ajax isn't possible (such as a non-same-domain url, or if specified using certain attributes on the link), a normal http request is used instead.</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>Default link behavior: Ajax</h2>
<p>To enable animated page transitions, all links that point to an external page (ex. products.html) will be loaded via Ajax. To do this unobtrusively, the framework parses the link's <code>href</code> to formulate an Ajax request (Hijax) and displays the loading spinner. All this happens automatically by jQuery Mobile.</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>
<p><strong>Note:</strong> that you cannot link <strong>to</strong> multipage document with Ajax navigation active because the framework will only load the first page it finds, not the full set of internal pages. In these cases, you must link without Ajax (see next section) for a full page refresh to prevent potential hash collisions. There is currently a <a href="https://github.com/ToddThomson/jQuery-Mobile-Subpage-Widget" rel="external">subpage plugin</a> that makes it possible to load in multi-page documents.</p>
<h2>Linking without Ajax</h2>
<p>Links that point to other domains or that have <code>rel="external"</code>, <code>data-ajax="false"</code> or <code>target</code> attributes will not be loaded with Ajax. Instead, these links will cause a full page refresh with no animated transition. Both attributes (<code>rel="external"</code> and <code>data-ajax="false"</code>) have the same effect, but a different semantic meaning: <code>rel="external"</code> should be used when linking to another site or domain, while <code>data-ajax="false"</code> is useful for simply opting a page within your domain from being loaded via Ajax. Because of security restrictions, the framework always opts links to external domains out of the Ajax behavior.</p>
<p>In version 1.1, we've added support for using <code>data-ajax="false"</code> on a parent container which allows you to excluded a large number of links from the Ajax navigation system. This avoids the need to add this attribute to every link in a container.</p>
<p>Note: When building a jQuery Mobile application where the Ajax navigation system is disabled globally or frequently disabled on individual links, we recommend disabling the <code>$.mobile.pushStateEnabled</code> global <a href="../api/globalconfig.html">configuration option</a> to avoid inconsistent navigation behavior in some browsers.</p>
<h2>Linking within a multi-page document</h2>
<p>A single HTML document can contain one or many 'page' containers simply by stacking multiple divs with a <code> data-role</code> of <code>"page"</code>. This allows you to build a small site or application within a single HTML document; jQuery Mobile will simply display the first 'page' it finds in the source order when the page loads.</p>
<p>If a link in a multi-page document points to an anchor (<code>#foo</code>), the framework will look for a page wrapper with that ID (<code>id="foo"</code>). If it finds a page in the HTML document, it will transition the new page into view. You can seamlessly navigate between local, internal "pages" and external pages in jQuery Mobile. Both will look the same to the end user except that external pages will display the Ajax spinner while loading. In either situation, jQuery Mobile updates the page's URL hash to enable Back button support, deep-linking and bookmarking. </p>
<p>It's important to note that if you are linking from a mobile page that was loaded via Ajax to a page that contains 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 (<code>#</code>) to track the Ajax history, while multiple internal pages use the hash to indicate internal pages so there will be conflicts in the hash between these two modes.</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>
<h2>"Back" button links</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 <code>href</code>. This is particularly useful when generating "back" buttons with JavaScript, such as a button to close a dialog.
When using this feature in your source markup, although browsers that support this feature will not use the specified <code>href</code> attribute, <strong>be sure to still provide a meaningful value that actually points to the URL of the referring page to allow the feature to work for users in C-Grade browsers</strong>. If users can reach this page from more than one referring pages, specify a sensible <code>href</code> so that the navigation remains logical for all users.
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.
Note: <code>data-direction="reverse"</code> is meant to simply run the backwards version of the transition that will run on that page change, while <code>data-rel="back"</code> makes the link functionally equivalent to the browser's back button and all the standard back button logic applies. Adding <code>data-direction="reverse"</code> to a link with <code>data-rel="back"</code> <b>will not</b> reverse the reversed page transition and produce the "normal" version of the transition.
</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="page-navmodel.html">Ajax, hashes and history</a> in jQuery mobile.</p>
<h2>Link examples</h2>
<p>All standard HTML link types are supported in jQuery Mobile in addition to the types outlined above. Here is a sampler of many common link types:</p>
<ul data-role="listview" data-inset="true" data-theme="d" data-divider-theme="d">
<li data-role="list-divider">Links that will be Ajax-loaded with page transitions</li>
<li><a href="../../index.html">Link in the same domain</a></li>
<li><a href="../pages/dialog.html" data-rel="dialog">Dialog link: data-rel="dialog" (not tracked in history)</a></li>
<li data-role="list-divider">Links that will refresh the page</li>
<li><a href="http://www.jquery.com">External domain</a></li>
<li><a href="../../index.html" rel="external">Link with rel="external"</a></li>
<li><a href="index.html" data-ajax="false">link with [data-ajax="false"]</a></li>
<li><a href="../../index.html" target="foo">Link with target="foo"</a></li>
<li data-role="list-divider">Email links</li>
<li><a href="mailto:jdoe@foo.com">Basic email: mailto:jdoe@foo.com</a></li>
<li><a href="mailto:jdoe@foo.com?cc=bill@bar.com&bcc=mark@abc.com&subject=Happy%20Birthday&body=Best%20wishes!">Mailto with a cc:, bcc:, subject and body pre-filled</a></li>
<li data-role="list-divider">Phone links</li>
<li><a href="tel:15555555555">Phone: tel:15555555555</a></li>
<li data-role="list-divider">Other</li>
<li><a href="#">A href="#" will return false</a></li>
</ul>
</div><!--/content-primary -->
<div class="content-secondary">
<div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
<h3>More in this section</h3>
<ul data-role="listview" data-theme="c" data-dividertheme="d">
<li data-role="list-divider">Pages & Dialogs</li>
<li><a href="page-anatomy.html">Anatomy of a page</a></li>
<li><a href="page-template.html" data-ajax="false">Single page template</a></li>
<li><a href="multipage-template.html" data-ajax="false">Multi-page template</a></li>
<li><a href="page-titles.html">Page titles</a></li>
<li data-theme="a"><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
<li><a href="page-cache.html">Prefetching & caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes & history</a></li>
<li><a href="page-dynamic.html">Dynamically injecting pages</a></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="phonegap.html">PhoneGap apps</a></li>
<li><a href="touchoverflow.html">touchOverflow feature</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
</ul>
</div>
</div>
</div><!-- /content -->
<div data-role="footer" class="footer-docs" data-theme="c">
<p>© 2011 The jQuery Project</p>
</div>
</div><!-- /page -->
</body>
</html>