Skip to content

Commit bd0bdfd

Browse files
WiltoWilto
committed
Removed fixed header/footer on transition pages that was previously causing Android to render box-shadows incorrectly/sulk in the corner; created separate page for custom transition documentation.
1 parent 0172ff8 commit bd0bdfd

File tree

2 files changed

+214
-149
lines changed

2 files changed

+214
-149
lines changed

‎docs/pages/page-customtransitions.html‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
<!DOCTYPE html>
2+
<html class="ui-mobile-rendering">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>jQuery Mobile Docs - Transitions</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 data-main="../../js/jquery.mobile.docs" src="../../external/requirejs/require.js"></script>
11+
<script src="../../js/jquery.js"></script>
12+
</head>
13+
<body>
14+
15+
<div data-role="page" class="type-interior">
16+
17+
<div data-role="header" data-theme="f">
18+
<h1>Transitions</h1>
19+
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
20+
</div><!-- /header -->
21+
22+
<div data-role="content">
23+
<div class="content-primary">
24+
25+
<h2>Creating custom JavaScript-based transitions</h2>
26+
27+
<p>When a user clicks on a link within a page, jQuery Mobile checks if the link specifies a <code>@data-transition</code> attribute. The value of this attribute is the name of the transition to use when displaying the page referred to by the link. If there is no <code>@data-transition</code> attribute, the transition name specified by the configuration option <code>$.mobile.defaultPageTransition</code> is used for pages, and <code>$.mobile.defaultDialogTransition</code> is used for dialogs.</p>
28+
29+
<p>After the new page is loaded, the <code>$.mobile.transitionHandlers</code> dictionary is used to see if any transition handler function is registered for the given transition name. If a handler is found, that handler is invoked to start and manage the transition. If no handler is found the handler specified by the configuration option <code>$.mobile.defaultTransitionHandler</code> is invoked.</p>
30+
31+
<p>By default, the <code>$.mobile.transitionHandlers</code> dictionary is only populated with a single handler entry called "default". This handler plays a dual purpose of either executing a "none" transition, which removes the <code>"ui-page-active"</code> class from the page we are transitioning "from", and places it on the page we are transitioning "to", or a Queued CSS3 Animated Transition, such as the one explained above. If the transition is "none", it will be instantaneous; no animation, no fanfare.</p>
32+
33+
<p>The <code>$.mobile.defaultTransitionHandler</code> points to a handler function that assumes the name is a CSS class name, and implements the "Pure CSS3 Based Transitions" section above.</p>
34+
35+
<p>The default transition handler is available on the $.mobile namespace:</p>
36+
37+
<pre><code>
38+
$.mobile.transitionHandlers[ "default" ];
39+
</code></pre>
40+
41+
<h3>Transition Handlers</h3>
42+
43+
<p>A transition handler is a function with the following call signature:</p>
44+
45+
<pre><code>function myTransitionHandler(name, reverse, $to, $from)
46+
{
47+
var deferred = new $.Deferred();
48+
49+
// Perform any actions or set-up necessary to kick-off
50+
// your transition here. The only requirement is that
51+
// whenever the transition completes, your code calls
52+
// deferred.resolve(name, reverse, $to, $from).
53+
54+
// Return a promise.
55+
return deferred.promise();
56+
}
57+
</code></pre>
58+
59+
<p>Your handler must create a Deferred object and return a promise to the caller. The promise is used to communicate to the caller when your transition is actually complete. It is up to you to call <code>deferred.resolve()</code> at the correct time. If you are new to Deferred objects, you can find documentation <a href="http://api.jquery.com/category/deferred-object/" rel="nofollow">here</a>.</p>
60+
61+
<h3>Registering and Invoking Your Transition Handler</h3>
62+
63+
<p>Once you have created a transition handler function, you need to tell jQuery Mobile about it. To do this, simply add your handler to the <code>$.mobile.transitionHandlers</code> dictionary. Remember, the key used should be the name of your transition. This name is also the same name that will be used within the <code>@data-transition</code> attribute of any navigation links.</p>
64+
65+
<pre><code>// Define your transition handler:
66+
67+
function myTransitionHandler(name, reverse, $to, $from)
68+
{
69+
var deferred = new $.Deferred();
70+
71+
// Perform any actions or set-up necessary to kick-off
72+
// your transition here. The only requirement is that
73+
// whenever the transition completes, your code calls
74+
// deferred.resolve(name, reverse, $to, $from).
75+
76+
// Return a promise.
77+
return deferred.promise();
78+
}
79+
80+
// Register it with jQuery Mobile:
81+
82+
$.mobile.transitionHandlers["myTransition"] = myTransitionHandler;
83+
</code></pre>
84+
85+
<p>Once you've registered your handler, you can invoke your transition by placing a <code>data-transition</code> attribute on a link:</p>
86+
87+
<pre><code>&lt;a href="#page2" data-transition="myTransition"&gt;Page 2&lt;/a&gt;
88+
</code></pre>
89+
90+
<p>When the user clicks the link above, your transition handler will be invoked after the page is loaded and it is ready to be shown.</p>
91+
92+
<h3>Overriding a CSS Transition With Your Own Handler</h3>
93+
94+
<p>As previously mentioned the default transition handler assumes that any transition name other than "none" is a CSS class to be placed on the "from" and "to" elements to kick off a CSS3 animation. If you would like to override one of these built-in CSS transitions, you simply register your own handler with the same name as the CSS page transition you want to override. So for example, if I wanted to override the built-in "slide" CSS transition with my own JavaScript based transition, I would simply do the following:</p>
95+
96+
<pre><code>// Define your transition handler:
97+
98+
function myTransitionHandler(name, reverse, $to, $from)
99+
{
100+
var deferred = new $.Deferred();
101+
102+
// Perform any actions or set-up necessary to kick-off
103+
// your transition here. The only requirement is that
104+
// whenever the transition completes, your code calls
105+
// deferred.resolve(name, reverse, $to, $from).
106+
107+
// Return a promise.
108+
return deferred.promise();
109+
}
110+
111+
// Register it with jQuery Mobile:
112+
113+
$.mobile.transitionHandlers["slide"] = myTransitionHandler;
114+
</code></pre>
115+
116+
<p>Once you do this, anytime the "slide" transition is invoked, your handler, instead of the default one, will be called to perform the transition.</p>
117+
118+
<h3>Overriding the Default Transition Handler</h3>
119+
120+
<p>The <code>$.mobile.css3TransitionHandler</code> function is the default transition handler that gets invoked when a transition name is used and not found in the <code>$.mobile.transitionHandlers</code> dictionary. If you want to install your own custom default handler, you simply set the <code>$.mobile.defaultTransitionHandler</code> to your handler:</p>
121+
122+
<pre><code>// Define your default transition handler:
123+
124+
function myTransitionHandler(name, reverse, $to, $from)
125+
{
126+
var deferred = new $.Deferred();
127+
128+
// Perform any actions or set-up necessary to kick-off
129+
// your transition here. The only requirement is that
130+
// whenever the transition completes, your code calls
131+
// deferred.resolve(name, reverse, $to, $from).
132+
133+
// Return a promise.
134+
return deferred.promise();
135+
}
136+
137+
$.mobile.defaultTransitionHandler = myTransitionHandler;
138+
</code></pre>
139+
140+
<p>Once you do this, your handler will be invoked any time a transition name is used but not found within the <code>$.mobile.transitionHandlers</code> dictionary.</p>
141+
142+
<h2>A model for Custom transition handler development</h2>
143+
<p>Transition handlers involve a number of critical operations, such as hiding any existing page, showing the new page, scrolling either to the top or a remembered scroll position on that new page, setting focus on the new page, and any animation and timing sequences you'd like to add. During development, we would recommend using <code>jquery.mobile.transitions.js</code> as a coding reference.</p>
144+
145+
<h2>Transitions and scroll position</h2>
146+
<p>One of the key things jQuery Mobile does is store your scroll position before starting a transition so it can restore you to the same place once you return to the page when hitting the Back button or closing a dialog. Here are the same buttons from the top to test the scrolling logic.</p>
147+
148+
149+
</div><!--/content-primary -->
150+
151+
<div class="content-secondary">
152+
153+
<div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
154+
155+
<h3>More in this section</h3>
156+
157+
<ul data-role="listview" data-theme="c" data-dividertheme="d">
158+
<li data-role="list-divider">Pages &amp; Dialogs</li>
159+
<li><a href="page-anatomy.html">Anatomy of a page</a></li>
160+
<li><a href="page-template.html" data-ajax="false">Single page template</a></li>
161+
<li><a href="multipage-template.html" data-ajax="false">Multi-page template</a></li>
162+
<li><a href="page-titles.html">Page titles</a></li>
163+
<li><a href="page-links.html">Linking pages</a></li>
164+
<li><a href="page-transitions.html">Page transitions</a></li>
165+
<li><a href="page-dialogs.html">Dialogs</a></li>
166+
<li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
167+
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
168+
<li><a href="page-dynamic.html">Dynamically injecting pages</a></li>
169+
<li><a href="page-scripting.html">Scripting pages</a></li>
170+
<li><a href="phonegap.html">PhoneGap apps</a></li>
171+
<li><a href="touchoverflow.html">touchOverflow feature</a></li>
172+
<li><a href="pages-themes.html">Theming pages</a></li>
173+
</ul>
174+
</div>
175+
</div>
176+
177+
</div><!-- /content -->
178+
179+
</body>
180+
</html>
181+

0 commit comments

Comments
 (0)