libs/js/jquery-mobile-1.1.0/docs/pages/page-customtransitions.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/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>Transitions</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
  28                                 <h2>Creating custom CSS-based transitions</h2>
  29
  30
  31                                 <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>
  32
  33                                 <pre><code>
  34                 .slide.in {
  35                         -webkit-transform: translateX(0);
  36                         -moz-transform: translateX(0);
  37                         -webkit-animation-name: slideinfromright;
  38                         -moz-animation-name: slideinfromright;
  39                 }
  40
  41                 .slide.out {
  42                         -webkit-transform: translateX(-100%);
  43                         -moz-transform: translateX(-100%);
  44                         -webkit-animation-name: slideouttoleft;
  45                         -moz-animation-name: slideouttoleft;
  46                 }
  47
  48                 @-webkit-keyframes slideinfromright {
  49                         from { -webkit-transform: translateX(100%); }
  50                         to { -webkit-transform: translateX(0); }
  51                 }
  52
  53                 @-webkit-keyframes slideouttoleft {
  54                         from { -webkit-transform: translateX(0); }
  55                         to { -webkit-transform: translateX(-100%); }
  56                 }
  57
  58                 @-moz-keyframes slideinfromright {
  59                         from { -moz-transform: translateX(100%); }
  60                         to { -moz-transform: translateX(0); }
  61                 }
  62
  63                 @-moz-keyframes slideouttoleft {
  64                         from { -moz-transform: translateX(0); }
  65                         to { -moz-transform: translateX(-100%); }
  66                 }
  67
  68                                 </code></pre>
  69
  70                                 <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. As of jQuery Mobile version 1.1, animation class additions are queued, rather than simultaneous, producing an out-then-in sequence, which is friendlier for mobile rendering than our previous simultaneous transition sequence.</p>
  71
  72                                 <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>
  73
  74                                 <pre><code>
  75                 .slide.in.reverse {
  76                         -webkit-transform: translateX(0);
  77                         -moz-transform: translateX(0);
  78                         -webkit-animation-name: slideinfromleft;
  79                         -moz-animation-name: slideinfromleft;
  80                 }
  81
  82                 .slide.out.reverse {
  83                         -webkit-transform: translateX(100%);
  84                         -moz-transform: translateX(100%);
  85                         -webkit-animation-name: slideouttoright;
  86                         -moz-animation-name: slideouttoright;
  87                 }
  88
  89                 @-webkit-keyframes slideinfromleft {
  90                         from { -webkit-transform: translateX(-100%); }
  91                         to { -webkit-transform: translateX(0); }
  92                 }
  93
  94                 @-webkit-keyframes slideouttoright {
  95                         from { -webkit-transform: translateX(0); }
  96                         to { -webkit-transform: translateX(100%); }
  97                 }
  98
  99                 @-moz-keyframes slideinfromleft {
 100                         from { -moz-transform: translateX(-100%); }
 101                         to { -moz-transform: translateX(0); }
 102                 }
 103
 104                 @-moz-keyframes slideouttoright {
 105                         from { -moz-transform: translateX(0); }
 106                         to { -moz-transform: translateX(100%); }
 107                 }
 108
 109                                 </code></pre>
 110
 111                                 <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>
 112
 113                                 <pre><code>&lt;a href="#page2" data-transition="slide"&gt;Page 2&lt;/a&gt;
 114                                 </code></pre>
 115
 116                                 <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>
 117
 118                                 <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>
 119
 120                                 <pre><code>
 121                 .in {
 122                         -webkit-animation-timing-function: ease-out;
 123                         -webkit-animation-duration: 350ms;
 124                         -moz-animation-timing-function: ease-out;
 125                         -moz-animation-duration: 350ms;
 126                 }
 127
 128                 .out {
 129                         -webkit-animation-timing-function: ease-in;
 130                         -webkit-animation-duration: 225ms;
 131                         -moz-animation-timing-function: ease-in;
 132                         -moz-animation-duration: 225;
 133                 }
 134                                 </code></pre>
 135
 136                                 <p>If you need to specify a different easing or duration, simply add the appropriate CSS3 property to your custom page transition rules.</p>
 137
 138
 139                 <h2>Creating custom JavaScript-based transitions</h2>
 140
 141                 <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>
 142
 143                 <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>
 144
 145                 <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>
 146
 147                 <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>
 148
 149                 <p>The default transition handler is available on the $.mobile namespace:</p>
 150
 151                 <pre><code>
 152 $.mobile.transitionHandlers[ "default" ];
 153                 </code></pre>
 154
 155                 <h3>Transition Handlers</h3>
 156
 157                 <p>A transition handler is a function with the following call signature:</p>
 158
 159                 <pre><code>
 160 function myTransitionHandler(name, reverse, $to, $from)
 161 {
 162     var deferred = new $.Deferred();
 163
 164     // Perform any actions or set-up necessary to kick-off
 165     // your transition here. The only requirement is that
 166     // whenever the transition completes, your code calls
 167     // deferred.resolve(name, reverse, $to, $from).
 168
 169     // Return a promise.
 170     return deferred.promise();
 171 }
 172                 </code></pre>
 173
 174                 <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>
 175
 176                 <h3>Registering and Invoking Your Transition Handler</h3>
 177
 178                 <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>
 179
 180                 <pre><code>
 181 // Define your transition handler:
 182
 183 function myTransitionHandler(name, reverse, $to, $from)
 184 {
 185     var deferred = new $.Deferred();
 186
 187     // Perform any actions or set-up necessary to kick-off
 188     // your transition here. The only requirement is that
 189     // whenever the transition completes, your code calls
 190     // deferred.resolve(name, reverse, $to, $from).
 191
 192     // Return a promise.
 193     return deferred.promise();
 194 }
 195
 196 // Register it with jQuery Mobile:
 197
 198 $.mobile.transitionHandlers["myTransition"] = myTransitionHandler;
 199                 </code></pre>
 200
 201                 <p>Once you've registered your handler, you can invoke your transition by placing a <code>data-transition</code> attribute on a link:</p>
 202
 203                 <pre><code>&lt;a href="#page2" data-transition="myTransition"&gt;Page 2&lt;/a&gt;
 204                 </code></pre>
 205
 206                 <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>
 207
 208                 <h3>Overriding a CSS Transition With Your Own Handler</h3>
 209
 210                 <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>
 211
 212                 <pre><code>// Define your transition handler:
 213
 214 function myTransitionHandler(name, reverse, $to, $from)
 215 {
 216     var deferred = new $.Deferred();
 217
 218     // Perform any actions or set-up necessary to kick-off
 219     // your transition here. The only requirement is that
 220     // whenever the transition completes, your code calls
 221     // deferred.resolve(name, reverse, $to, $from).
 222
 223     // Return a promise.
 224     return deferred.promise();
 225 }
 226
 227 // Register it with jQuery Mobile:
 228
 229 $.mobile.transitionHandlers["slide"] = myTransitionHandler;
 230                 </code></pre>
 231
 232                 <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>
 233
 234                 <h3>Overriding the Default Transition Handler</h3>
 235
 236                 <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>
 237
 238                 <pre><code>// Define your default transition handler:
 239
 240 function myTransitionHandler(name, reverse, $to, $from)
 241 {
 242     var deferred = new $.Deferred();
 243
 244     // Perform any actions or set-up necessary to kick-off
 245     // your transition here. The only requirement is that
 246     // whenever the transition completes, your code calls
 247     // deferred.resolve(name, reverse, $to, $from).
 248
 249     // Return a promise.
 250     return deferred.promise();
 251 }
 252
 253 $.mobile.defaultTransitionHandler = myTransitionHandler;
 254                 </code></pre>
 255
 256                 <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>
 257
 258                 <h2>A model for Custom transition handler development</h2>
 259                 <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>
 260
 261                 <h2>Transitions and scroll position</h2>
 262                 <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>
 263
 264
 265                 </div><!--/content-primary -->
 266
 267                 <div class="content-secondary">
 268
 269                         <div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
 270
 271                                         <h3>More in this section</h3>
 272
 273                                         <ul data-role="listview" data-theme="c" data-dividertheme="d">
 274                                                 <li data-role="list-divider">Pages &amp; Dialogs</li>
 275                                                 <li><a href="page-anatomy.html">Anatomy of a page</a></li>
 276                                                 <li><a href="page-template.html" data-ajax="false">Single page template</a></li>
 277                                                 <li><a href="multipage-template.html" data-ajax="false">Multi-page template</a></li>
 278                                                 <li><a href="page-titles.html">Page titles</a></li>
 279                                                 <li><a href="page-links.html">Linking pages</a></li>
 280                                                 <li><a href="page-transitions.html">Page transitions</a></li>
 281                                                 <li><a href="page-dialogs.html">Dialogs</a></li>
 282                                                 <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
 283                                                 <li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
 284                                                 <li><a href="page-dynamic.html">Dynamically injecting pages</a></li>
 285                                                 <li><a href="page-scripting.html">Scripting pages</a></li>
 286                                                 <li><a href="phonegap.html">PhoneGap apps</a></li>
 287                                                 <li><a href="touchoverflow.html">touchOverflow feature</a></li>
 288                                                 <li><a href="pages-themes.html">Theming pages</a></li>
 289                                         </ul>
 290                         </div>
 291                 </div>
 292
 293         </div><!-- /content -->
 294
 295 </body>
 296 </html>
 297