Updated the stable version with pageload and pagebeforechange events.

The documentation was also updated with a 'common mistakes' paragraph
azicchetti · May 28, 2012 · edf70f0 · edf70f0
1 parent 5905d14
commit edf70f0
Show file tree

Hide file tree

Showing 14 changed files with 437 additions and 318 deletions.
diff --git a/README.md b/README.md
@@ -28,6 +28,7 @@ In addition, if you want to use standard hashchange-based routers, you have to d
 
 What's new in the latest versions
 =====================
+* support for pagebeforechange, pagebeforeload, pageload
 * Added a parameter in the configuration object to execute only the first route handler found
 * Support for a different syntax defining your routes
 * Added a nice getParams() function to actually 'parse' parameters in the hash and get
@@ -302,6 +303,42 @@ Your handlers will be called with the following arguments:
 	removed from the dom during the pageremove event.
 
 
+Common mistakes
+--------------
+jQuery Mobile is a wonderful framework and it seems really easy to use at first.
+While this may be true for server-side generated mobile pages, things are very different
+once you have to do a full client-side web application, using backbone.js or spine.js and
+possibly Phonegap/Cordova.
+
+The whole hash handling performed by jQuery Mobile may be confusing, dynamic page loading/injection
+must be understood in order to be successfully exploited, and you should also know the jQM
+event system to have a fine grained control over page switching.
+
+Here is a list of things you should check when you're in trouble, based on my experience but,
+more importantly, on the email I've received from other users of the jQM router.
+
+* the router should be instantiated as soon as possible, possibly just after loading jquery mobile.
+This ensures that even the first pageinit event can be catched and handled by the router
+
+* please make sure that the router is not instantiated multiple times by mistake. This will lead to
+routes being fired twice, at least
+
+* do not call $.mobile.changePage during a page transition with the destination page being the one
+the framework is already transitioning to.
+That is to say, if you click on a link to #foo and you have a pagebeforeshow route bound to it,
+DO NOT invoke $.mobile.changePage("#foo") in your handler (the result will be an epic failure due to
+a bug in jquery mobile)
+
+* DOUBLE CHECK your REGULAR EXPRESSIONS! A typical mistake is forgetting the $ operator.
+If you have two pages, such as #product and #productList, a hypothetical route "#product" would
+match both pages, leading to unexpected behaviors. Use the $ operator when unsure: "#product$"
+
+* use setTimeout to avoid doing time-consuming tasks in a page-transition handler. If you have
+a route bound to pagebeforeshow (or even other events) and your code takes too much to execute
+(for instance, very long foreach loops, synchronous ajax calls, complex manupulations
+of markers in a google map), jquery mobile may throw an error.
+
+
 Public methods
 --------------
 

diff --git a/examples/__subTestAjax.html b/examples/__subTestAjax.html
@@ -2,9 +2,9 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
-        <script type="text/javascript" src="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
 </head>
 
 <body>

diff --git a/examples/__subTestAjax3.html b/examples/__subTestAjax3.html
@@ -2,9 +2,9 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
-        <script type="text/javascript" src="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
 </head>
 
 <body>

diff --git a/examples/test-bC.html b/examples/test-bC.html
@@ -2,10 +2,10 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
-        <script type="text/javascript" src="../js/jquery.mobile.router-dev.js"></script>
+        <script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
-        <script type="text/javascript" src="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
         <script type="text/javascript">
 	var router=new $.mobile.Router([
 		{ "#localpage2(?:[?/](.*))?": {handler: "localpage", events: "bc,c,i,bs,s,bh,h"} },

diff --git a/examples/test-bl.html b/examples/test-bl.html
@@ -2,10 +2,10 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
-        <script type="text/javascript" src="../js/jquery.mobile.router-dev.js"></script>
+        <script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
-        <script type="text/javascript" src="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
         <script type="text/javascript">
 	var router=new $.mobile.Router([
 		{ "#index": { 

diff --git a/examples/test.html b/examples/test.html
@@ -2,10 +2,10 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
         <script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
-        <script type="text/javascript" src="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
         <script type="text/javascript">
 	var router=new $.mobile.Router({
 		"#localpage2(?:[?/](.*))?": {handler: "localpage", events: "bc,c,i,bs,s,bh,h"},

diff --git a/examples/testAjax.html b/examples/testAjax.html
@@ -2,7 +2,7 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
         <script type="text/javascript">
 	$(document).bind("mobileinit",function(){
@@ -12,7 +12,7 @@
 	});
         </script>
 	<script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
-	<script type="text/javascript" src="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.js"></script>
+	<script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
         <script type="text/javascript">
 	var router=new $.mobile.Router({
 		"/testAjax.html(?:[?](.*))?": {handler: "ajaxPage", events: "bc,c,bs,s,h"},

diff --git a/examples/testArraySyntax.html b/examples/testArraySyntax.html
@@ -2,10 +2,10 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
         <script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
-        <script type="text/javascript" src="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
         <script type="text/javascript">
 	var router=new $.mobile.Router([
 		{ "#localpage2(?:[?/](.*))?": {handler: "localpageA", events: "bc,c,i"} },

diff --git a/examples/testBackButton.html b/examples/testBackButton.html
@@ -0,0 +1,58 @@
+<html>
+<head>
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
+        <script type="text/javascript" src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
+        <script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
+<script>
+var actions = {
+    showSite: function(eventType, matchObj, ui, page, evt) {
+	console.log('showSite');
+	console.log(matchObj);
+    },
+    showSection: function(eventType, matchObj, ui, page, evt) {
+	console.log('showSection');
+	console.log(matchObj);
+    },
+    showChunk: function(eventType, matchObj, ui, page, evt) {
+	console.log('showChunk');
+	console.log(matchObj);
+    }
+};
+
+
+new $.mobile.Router(
+{
+    "#site": { handler: "showSite", events: "bs" },
+    "#section([?].*)?": { handler: "showSection", events: "bs" },
+    "#chunk([?].*)?": { handler: "showChunk", events: "bs" },
+},
+actions);
+</script>
+</head>
+
+<body>
+<div id="site" data-role="page" data-add-back-btn="true">
+    <div data-role="header"><h1>Site</h1></div>
+    <div data-role="content">
+        <ul data-role="listview">
+            <li><a href="#section?id=1">Section 1</a></li>
+        </ul>
+    </div>
+</div>
+
+<div id="section" data-role="page" data-add-back-btn="true">
+    <div data-role="header"><h1>Section</h1></div>
+    <div data-role="content">
+        <ul data-role="listview">
+             <li><a href="#chunk?id=1">Chunk 1</a></li>
+        </ul>
+    </div>
+</div>
+
+<div id="chunk" data-role="page" data-add-back-btn="true">
+    <div data-role="header"><h1>Chunk</h1></div>
+    <div data-role="content"></div>
+</div>
+</body>
+</html>
diff --git a/examples/testChangePage.html b/examples/testChangePage.html
@@ -2,10 +2,10 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
         <script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
-        <script type="text/javascript" src="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
         <script type="text/javascript">
 	var router=new $.mobile.Router({
 		"#localpage2(?:[?/](.*))?": {

diff --git a/examples/testChangePageAjax.html b/examples/testChangePageAjax.html
@@ -2,7 +2,7 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
         <script type="text/javascript">
 	$(document).bind("mobileinit",function(){
@@ -13,7 +13,7 @@
 	});
         </script>
 	<script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
-	<script type="text/javascript" src="http://code.jquery.com/mobile/1.0.1/jquery.mobile-1.0.1.min.js"></script>
+	<script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
         <script type="text/javascript">
 	var router=new $.mobile.Router({
 		"/testChangePageAjax.html(?:[?](.*))?": {handler: "ajaxPage", events: "bc,c,bs,s,h"},

diff --git a/examples/testSamePage.html b/examples/testSamePage.html
@@ -2,10 +2,10 @@
 <html>
         <head>
         <title>Page Title</title>
-        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
+        <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.css" />
         <script type="text/javascript" src="http://code.jquery.com/jquery-1.6.4.min.js"></script>
         <script type="text/javascript" src="../js/jquery.mobile.router.js"></script>
-        <script type="text/javascript" src="http://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
+        <script type="text/javascript" src="http://code.jquery.com/mobile/1.1.0/jquery.mobile-1.1.0.min.js"></script>
         <script type="text/javascript">
 	var router=new $.mobile.Router({
 		"#localpage2(?:[?/](.*))?": "localpage2",