libs/js/jquery-mobile-1.0.1pre/docs/pages/page-transitions.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 - Transitions</title>
   7         <link rel="stylesheet"  href="../../css/themes/default/" />
   8         <link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
   9         <script src="../../js/jquery.js"></script>
  10         <script src="../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
  11         <script src="../_assets/js/jqm-docs.js"></script>
  12         <script src="../../js/"></script>
  13 </head>
  14 <body>
  15
  16         <div data-role="page" class="type-interior">
  17
  18                 <div data-role="header" data-theme="f">
  19                 <h1>Transitions</h1>
  20                 <a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
  21         </div><!-- /header -->
  22
  23         <div data-role="content">
  24                 <div class="content-primary">
  25                 <h2>Page transitions</h2>
  26
  27                 <p>The jQuery Mobile framework includes a set of six CSS-based transition effects that can be applied to any page link or form submission with Ajax navigation: </p>
  28
  29
  30 <div class="ui-grid-a">
  31         <div class="ui-block-a">
  32                 <a href="#dialog" data-role="button" data-rel="dialog" data-transition="slide">slide</a>
  33                 <a href="#dialog" data-role="button" data-rel="dialog" data-transition="slideup">slideup</a>
  34                 <a href="#dialog" data-role="button" data-rel="dialog" data-transition="slidedown">slidedown</a>
  35         </div>
  36         <div class="ui-block-b">
  37             <a href="#dialog" data-role="button" data-rel="dialog" data-transition="pop">pop</a>
  38                 <a href="#dialog" data-role="button" data-rel="dialog" data-transition="fade">fade</a>
  39                 <a href="#dialog" data-role="button" data-rel="dialog" data-transition="flip">flip*</a>
  40         </div>
  41 </div><!-- /grid-a -->
  42
  43 <p><strong>Transitions from <a href="http://www.jqtouch.com/">jQtouch</a></strong> (<em>with small modifications</em>): Built by David Kaneda and maintained by Jonathan Stark.</p>
  44
  45 <p>NOTE: The flip transition isn't rendered correctly on most versions of Android because it lacks 3D CSS transform capabilities. Unfortunately, instead of ignoring the flip, Android makes the page "cartwheel" away by rotating instead of flipping. We recommend using this transition sparingly until support improves.</p>
  46
  47
  48         <h2>Setting a transition on a link or form submit</h2>
  49         <p>By default, the framework applies the right to left <strong>slide</strong> transition. To set a custom transition effect, add the <code>data-transition</code> attribute to the link. </p>
  50
  51 <code><code>
  52 &lt;a href=&quot;index.html&quot; <strong>data-transition=&quot;pop&quot;</strong>&gt;I'll pop&lt;/a&gt;
  53 </code></code>
  54
  55                 <p>When the Back button is pressed, the framework will automatically apply the reverse version of the transition that was used to show the page. To specify that the reverse version of a transition should be used, add the <code>data-direction="reverse"</code> attribute to a link. Note: (this was formerly <code>data-back="true"</code>, which will remain supported until 1.0)</p>
  56
  57                 <p>For smoother page transitions, consider enabling the <a href="touchoverflow.html">touchOverflow</a> feature.</p>
  58
  59                 <h2>Global configuration of transitions</h2>
  60
  61                 <p>Set the <code>defaultPageTransition</code> <a href="../api/globalconfig.html">global option</a> if you'd prefer a different default transition. Dialogs have a different option called <code>defaultDialogTransition</code> that can also set configured.</p>
  62
  63
  64
  65
  66                 <h2>Creating custom CSS-based transitions</h2>
  67
  68
  69                 <p>To create a custom CSS transition, select a class name that corresponds to the name of your transition, for example "slide", and then define your "in" and "out" CSS rules to take advantage of transitions or animation keyframes:</p>
  70
  71                 <pre><code>.slide.in {
  72             -webkit-transform: translateX(0);
  73             -webkit-animation-name: slideinfromright;
  74         }
  75
  76         .slide.out {
  77             -webkit-transform: translateX(-100%);
  78             -webkit-animation-name: slideouttoleft;
  79         }
  80
  81         @-webkit-keyframes slideinfromright {
  82             from { -webkit-transform: translateX(100%); }
  83             to { -webkit-transform: translateX(0); }
  84         }
  85         @-webkit-keyframes slideouttoleft {
  86             from { -webkit-transform: translateX(0); }
  87             to { -webkit-transform: translateX(-100%); }
  88         }
  89                 </code></pre>
  90
  91                 <p>During a CSS-based page transition, jQuery Mobile will place the class name of the transition on both the "from" and "to" pages involved in the transition. It then places an "out" class on the "from" page, and "in" class on the "to" page. The presence of these classes on the "from" and "to" page elements then triggers the animation CSS rules defined above.</p>
  92
  93                 <p>If your transition supports a reverse direction, you need to create CSS rules that use the <code>reverse</code> class in addition to the transition class name and the "in" and "out" classes:</p>
  94
  95                 <pre><code>.slide.in.reverse {
  96                     -webkit-transform: translateX(0);
  97                     -webkit-animation-name: slideinfromleft;
  98                 }
  99
 100                 .slide.out.reverse {
 101                     -webkit-transform: translateX(100%);
 102                     -webkit-animation-name: slideouttoright;
 103                 }
 104
 105                 @-webkit-keyframes slideinfromleft {
 106                     from { -webkit-transform: translateX(-100%); }
 107                     to { -webkit-transform: translateX(0); }
 108                 }
 109
 110                 @-webkit-keyframes slideouttoright {
 111                     from { -webkit-transform: translateX(0); }
 112                     to { -webkit-transform: translateX(100%); }
 113                 }
 114                 </code></pre>
 115
 116                 <p>After the CSS rules are in place, you simply specify the name of your transition within the @data-transition attribute of a navigation link:</p>
 117
 118                 <pre><code>&lt;a href="#page2" data-transition="slide"&gt;Page 2&lt;/a&gt;
 119                 </code></pre>
 120
 121                 <p>When the user clicks on the navigation link, jQuery Mobile will invoke your transition when it navigates to the page mentioned within the link.</p>
 122
 123                 <p>In case you were wondering why none of the CSS rules above specified any easing or duration, it's because the CSS for jQuery Mobile defines the default easing and duration in the following rules:</p>
 124
 125                 <pre><code>
 126 .in, .out {
 127     -webkit-animation-timing-function: ease-in-out;
 128     -webkit-animation-duration: 350ms;
 129 }
 130                 </code></pre>
 131
 132                 <p>If you need to specify a different easing or duration, simply add the appropriate CSS3 property to your custom page transition rules.</p>
 133
 134                 <h2>Creating custom JavaScript-based transitions</h2>
 135
 136                 <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>
 137
 138                 <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>
 139
 140                 <p>By default, the <code>$.mobile.transitionHandlers</code> dictionary is only populated with a single handler entry called "none". This handler simply 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". The transition is instantaneous; no animation, no fanfare.</p>
 141
 142                 <p>The <code>$.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>
 143
 144                 <p>Both the "none" and "css3" transition handlers are available off of the $.mobile namespace:</p>
 145
 146                 <pre><code>
 147 $.mobile.noneTransitionHandler
 148 $.mobile.css3TransitionHandler
 149                 </code></pre>
 150
 151                 <h3>Transition Handlers</h3>
 152
 153                 <p>A transition handler is a function with the following call signature:</p>
 154
 155                 <pre><code>function myTransitionHandler(name, reverse, $to, $from)
 156 {
 157     var deferred = new $.Deferred();
 158
 159     // Perform any actions or set-up necessary to kick-off
 160     // your transition here. The only requirement is that
 161     // whenever the transition completes, your code calls
 162     // deferred.resolve(name, reverse, $to, $from).
 163
 164     // Return a promise.
 165     return deferred.promise();
 166 }
 167                 </code></pre>
 168
 169                 <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>
 170
 171                 <h3>Registering and Invoking Your Transition Handler</h3>
 172
 173                 <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>
 174
 175                 <pre><code>// Define your transition handler:
 176
 177 function myTransitionHandler(name, reverse, $to, $from)
 178 {
 179     var deferred = new $.Deferred();
 180
 181     // Perform any actions or set-up necessary to kick-off
 182     // your transition here. The only requirement is that
 183     // whenever the transition completes, your code calls
 184     // deferred.resolve(name, reverse, $to, $from).
 185
 186     // Return a promise.
 187     return deferred.promise();
 188 }
 189
 190 // Register it with jQuery Mobile:
 191
 192 $.mobile.transitionHandlers["myTransition"] = myTransitionHandler;
 193                 </code></pre>
 194
 195                 <p>Once you've registered your handler, you can invoke your transition by placing a <code>data-transition</code> attribute on a link:</p>
 196
 197                 <pre><code>&lt;a href="#page2" data-transition="myTransition"&gt;Page 2&lt;/a&gt;
 198                 </code></pre>
 199
 200                 <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>
 201
 202                 <h3>Overriding a CSS Transition With Your Own Handler</h3>
 203
 204                 <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>
 205
 206                 <pre><code>// Define your transition handler:
 207
 208 function myTransitionHandler(name, reverse, $to, $from)
 209 {
 210     var deferred = new $.Deferred();
 211
 212     // Perform any actions or set-up necessary to kick-off
 213     // your transition here. The only requirement is that
 214     // whenever the transition completes, your code calls
 215     // deferred.resolve(name, reverse, $to, $from).
 216
 217     // Return a promise.
 218     return deferred.promise();
 219 }
 220
 221 // Register it with jQuery Mobile:
 222
 223 $.mobile.transitionHandlers["slide"] = myTransitionHandler;
 224                 </code></pre>
 225
 226                 <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>
 227
 228                 <h3>Overriding the Default Transition Handler</h3>
 229
 230                 <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>
 231
 232                 <pre><code>// Define your default transition handler:
 233
 234 function myTransitionHandler(name, reverse, $to, $from)
 235 {
 236     var deferred = new $.Deferred();
 237
 238     // Perform any actions or set-up necessary to kick-off
 239     // your transition here. The only requirement is that
 240     // whenever the transition completes, your code calls
 241     // deferred.resolve(name, reverse, $to, $from).
 242
 243     // Return a promise.
 244     return deferred.promise();
 245 }
 246
 247 $.mobile.defaultTransitionHandler = myTransitionHandler;
 248                 </code></pre>
 249
 250                 <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>
 251
 252
 253                                 </div><!--/content-primary -->
 254
 255                                 <div class="content-secondary">
 256
 257                                         <div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
 258
 259                                                         <h3>More in this section</h3>
 260
 261                                                         <ul data-role="listview" data-theme="c" data-dividertheme="d">
 262                                                                 <li data-role="list-divider">Pages &amp; Dialogs</li>
 263                                                                 <li><a href="page-anatomy.html">Anatomy of a page</a></li>
 264                                                                 <li><a href="page-template.html" data-ajax="false">Single page template</a></li>
 265                                                                 <li><a href="multipage-template.html" data-ajax="false">Multi-page template</a></li>
 266                                                                 <li><a href="page-titles.html">Page titles</a></li>
 267                                                                 <li><a href="page-links.html">Linking pages</a></li>
 268                                                                 <li data-theme="a"><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
 269                                                                 <li><a href="page-dialogs.html">Dialogs</a></li>
 270                                                                 <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
 271                                                                 <li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
 272                                                                 <li><a href="page-dynamic.html">Dynamically injecting pages</a></li>
 273                                                                 <li><a href="page-scripting.html">Scripting pages</a></li>
 274                                                                 <li><a href="phonegap.html">PhoneGap apps</a></li>
 275                                                                 <li><a href="touchoverflow.html">touchOverflow feature</a></li>
 276                                                                 <li><a href="pages-themes.html">Theming pages</a></li>
 277                                                         </ul>
 278                                         </div>
 279                                 </div>
 280
 281                         </div><!-- /content -->
 282
 283                         <div data-role="footer" class="footer-docs" data-theme="c">
 284                                         <p>&copy; 2011 The jQuery Project</p>
 285                         </div>
 286
 287                         </div><!-- /page -->
 288
 289
 290
 291
 292
 293                         <div data-role="page" id="dialog"><!-- dialog-->
 294
 295                                 <div data-role="header" data-theme="e">
 296                                         <h1>Ta-da!</h1>
 297                                 </div><!-- /header -->
 298
 299                                 <div data-role="content" data-theme="e">
 300                                         <p>That was an animated page transition effect that we added with a <code>data-transition</code> attribute on the link.</p>
 301                                         <p>Since it uses CSS transforms, this should be hardware accelerated on many mobile devices.</p>
 302                                         <p>What do you think?</p>
 303                                         <a href="docs-transitions.html" data-role="button" data-theme="b" data-rel="back">I like it</a>
 304                                 </div>
 305                         </div>
 306
 307                         </body>
 308                         </html>