From bd0bdfd77e969a4f5e75eb98d549560da3d40276 Mon Sep 17 00:00:00 2001 From: Mat Marquis Date: Mon, 16 Jan 2012 17:51:11 -0500 Subject: [PATCH] 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. --- docs/pages/page-customtransitions.html | 181 +++++++++++++++++++++++++ docs/pages/page-transitions.html | 172 ++++------------------- 2 files changed, 209 insertions(+), 144 deletions(-) create mode 100644 docs/pages/page-customtransitions.html diff --git a/docs/pages/page-customtransitions.html b/docs/pages/page-customtransitions.html new file mode 100644 index 00000000..1a9a782e --- /dev/null +++ b/docs/pages/page-customtransitions.html @@ -0,0 +1,181 @@ + + + + + + jQuery Mobile Docs - Transitions + + + + + + + + +
+ +
+

Transitions

+ Home +
+ +
+
+ +

Creating custom JavaScript-based transitions

+ +

When a user clicks on a link within a page, jQuery Mobile checks if the link specifies a @data-transition 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 @data-transition attribute, the transition name specified by the configuration option $.mobile.defaultPageTransition is used for pages, and $.mobile.defaultDialogTransition is used for dialogs.

+ +

After the new page is loaded, the $.mobile.transitionHandlers 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 $.mobile.defaultTransitionHandler is invoked.

+ +

By default, the $.mobile.transitionHandlers 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 "ui-page-active" 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.

+ +

The $.mobile.defaultTransitionHandler points to a handler function that assumes the name is a CSS class name, and implements the "Pure CSS3 Based Transitions" section above.

+ +

The default transition handler is available on the $.mobile namespace:

+ + 

+$.mobile.transitionHandlers[ "default" ];
+
+ +

Transition Handlers

+ +

A transition handler is a function with the following call signature:

+ + 
function myTransitionHandler(name, reverse, $to, $from)
+{
+    var deferred = new $.Deferred();
+
+    // Perform any actions or set-up necessary to kick-off
+    // your transition here. The only requirement is that
+    // whenever the transition completes, your code calls
+    // deferred.resolve(name, reverse, $to, $from).
+
+    // Return a promise.
+    return deferred.promise();
+}
+
+ +

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 deferred.resolve() at the correct time. If you are new to Deferred objects, you can find documentation here.

+ +

Registering and Invoking Your Transition Handler

+ +

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 $.mobile.transitionHandlers 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 @data-transition attribute of any navigation links.

+ + 
// Define your transition handler:
+
+function myTransitionHandler(name, reverse, $to, $from)
+{
+    var deferred = new $.Deferred();
+
+    // Perform any actions or set-up necessary to kick-off
+    // your transition here. The only requirement is that
+    // whenever the transition completes, your code calls
+    // deferred.resolve(name, reverse, $to, $from).
+
+    // Return a promise.
+    return deferred.promise();
+}
+
+// Register it with jQuery Mobile:
+
+$.mobile.transitionHandlers["myTransition"] = myTransitionHandler;
+
+ +

Once you've registered your handler, you can invoke your transition by placing a data-transition attribute on a link:

+ + 
<a href="#page2" data-transition="myTransition">Page 2</a>
+
+ +

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.

+ +

Overriding a CSS Transition With Your Own Handler

+ +

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:

+ + 
// Define your transition handler:
+
+function myTransitionHandler(name, reverse, $to, $from)
+{
+    var deferred = new $.Deferred();
+
+    // Perform any actions or set-up necessary to kick-off
+    // your transition here. The only requirement is that
+    // whenever the transition completes, your code calls
+    // deferred.resolve(name, reverse, $to, $from).
+
+    // Return a promise.
+    return deferred.promise();
+}
+
+// Register it with jQuery Mobile:
+
+$.mobile.transitionHandlers["slide"] = myTransitionHandler;
+
+ +

Once you do this, anytime the "slide" transition is invoked, your handler, instead of the default one, will be called to perform the transition.

+ +

Overriding the Default Transition Handler

+ +

The $.mobile.css3TransitionHandler function is the default transition handler that gets invoked when a transition name is used and not found in the $.mobile.transitionHandlers dictionary. If you want to install your own custom default handler, you simply set the $.mobile.defaultTransitionHandler to your handler:

+ + 
// Define your default transition handler:
+
+function myTransitionHandler(name, reverse, $to, $from)
+{
+    var deferred = new $.Deferred();
+
+    // Perform any actions or set-up necessary to kick-off
+    // your transition here. The only requirement is that
+    // whenever the transition completes, your code calls
+    // deferred.resolve(name, reverse, $to, $from).
+
+    // Return a promise.
+    return deferred.promise();
+}
+
+$.mobile.defaultTransitionHandler = myTransitionHandler;
+
+ +

Once you do this, your handler will be invoked any time a transition name is used but not found within the $.mobile.transitionHandlers dictionary.

+ +

A model for Custom transition handler development

+

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 jquery.mobile.transitions.js as a coding reference.

+ +

Transitions and scroll position

+

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.

+ + +
+ +
+ +
+ +

More in this section

+ + +
+
+ +
+ + + + diff --git a/docs/pages/page-transitions.html b/docs/pages/page-transitions.html index 3f01018d..a2ea0936 100755 --- a/docs/pages/page-transitions.html +++ b/docs/pages/page-transitions.html @@ -194,124 +194,8 @@

Creating custom JavaScript-based transitions

-

When a user clicks on a link within a page, jQuery Mobile checks if the link specifies a @data-transition 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 @data-transition attribute, the transition name specified by the configuration option $.mobile.defaultPageTransition is used for pages, and $.mobile.defaultDialogTransition is used for dialogs.

+

jQuery Mobile allows for the addition of custom transitions to the $.mobile.transitionHandlers dictionary. -

After the new page is loaded, the $.mobile.transitionHandlers 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 $.mobile.defaultTransitionHandler is invoked.

- -

By default, the $.mobile.transitionHandlers 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 "ui-page-active" 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.

- -

The $.mobile.defaultTransitionHandler points to a handler function that assumes the name is a CSS class name, and implements the "Pure CSS3 Based Transitions" section above.

- -

The default transition handler is available on the $.mobile namespace:

- - 

-$.mobile.transitionHandlers[ "default" ];
-
- -

Transition Handlers

- -

A transition handler is a function with the following call signature:

- - 
function myTransitionHandler(name, reverse, $to, $from)
-{
-    var deferred = new $.Deferred();
-
-    // Perform any actions or set-up necessary to kick-off
-    // your transition here. The only requirement is that
-    // whenever the transition completes, your code calls
-    // deferred.resolve(name, reverse, $to, $from).
-
-    // Return a promise.
-    return deferred.promise();
-}
-
- -

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 deferred.resolve() at the correct time. If you are new to Deferred objects, you can find documentation here.

- -

Registering and Invoking Your Transition Handler

- -

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 $.mobile.transitionHandlers 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 @data-transition attribute of any navigation links.

- - 
// Define your transition handler:
-
-function myTransitionHandler(name, reverse, $to, $from)
-{
-    var deferred = new $.Deferred();
-
-    // Perform any actions or set-up necessary to kick-off
-    // your transition here. The only requirement is that
-    // whenever the transition completes, your code calls
-    // deferred.resolve(name, reverse, $to, $from).
-
-    // Return a promise.
-    return deferred.promise();
-}
-
-// Register it with jQuery Mobile:
-
-$.mobile.transitionHandlers["myTransition"] = myTransitionHandler;
-
- -

Once you've registered your handler, you can invoke your transition by placing a data-transition attribute on a link:

- - 
<a href="#page2" data-transition="myTransition">Page 2</a>
-
- -

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.

- -

Overriding a CSS Transition With Your Own Handler

- -

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:

- - 
// Define your transition handler:
-
-function myTransitionHandler(name, reverse, $to, $from)
-{
-    var deferred = new $.Deferred();
-
-    // Perform any actions or set-up necessary to kick-off
-    // your transition here. The only requirement is that
-    // whenever the transition completes, your code calls
-    // deferred.resolve(name, reverse, $to, $from).
-
-    // Return a promise.
-    return deferred.promise();
-}
-
-// Register it with jQuery Mobile:
-
-$.mobile.transitionHandlers["slide"] = myTransitionHandler;
-
- -

Once you do this, anytime the "slide" transition is invoked, your handler, instead of the default one, will be called to perform the transition.

- -

Overriding the Default Transition Handler

- -

The $.mobile.css3TransitionHandler function is the default transition handler that gets invoked when a transition name is used and not found in the $.mobile.transitionHandlers dictionary. If you want to install your own custom default handler, you simply set the $.mobile.defaultTransitionHandler to your handler:

- - 
// Define your default transition handler:
-
-function myTransitionHandler(name, reverse, $to, $from)
-{
-    var deferred = new $.Deferred();
-
-    // Perform any actions or set-up necessary to kick-off
-    // your transition here. The only requirement is that
-    // whenever the transition completes, your code calls
-    // deferred.resolve(name, reverse, $to, $from).
-
-    // Return a promise.
-    return deferred.promise();
-}
-
-$.mobile.defaultTransitionHandler = myTransitionHandler;
-
- -

Once you do this, your handler will be invoked any time a transition name is used but not found within the $.mobile.transitionHandlers dictionary.

- -

A model for Custom transition handler development

-

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 jquery.mobile.transitions.js as a coding reference.

-

Transitions and scroll position

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.

@@ -423,48 +307,48 @@ $.mobile.defaultTransitionHandler = myTransitionHandler;
-
+

Page

That was an animated page transition effect to a page that we added with a data-transition attribute on the link. This uses a different background theme swatch to see how that looks with the transitions.

-

Since it uses CSS animations, this should be hardware accelerated on many devices. To see transitions, 3D transform support is required so if you only saw a fade transition that's the reason.

+

Since it uses CSS animations, this should be hardware accelerated on many devices. To see transitions, 3D transform support is required so if you only saw a fade transition that's the reason.

-
+ +

Here's a few form elements

-

Here's a few form elements

+

These are here to see if this slows down rendering.

-

These are here to see if this slows down rendering.

+
+ + +
-
- - -
+
+ + +
-
- - -
+
+ + +
-
- - -
- -
- - -
+
+ + +
-
+ + Take me back
-
+