Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 574 lines (422 sloc) 24.819 kb
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
1 jQueryMobile-Router
bcf4d0a @azicchetti first commit
authored
2 ================================================================================
3
4 jQuery Mobile router is a plugin for jQuery Mobile to enhance the framework
5 with a client side router/controller that works with jQuery Mobile events
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
6 (pagebeforecreate, pagecreate, pagebeforeshow, pageshow, pagebeforehide, pagehide,
7 pageremove).
bcf4d0a @azicchetti first commit
authored
8
854dc90 @azicchetti The documentation was updated
authored
9 In addition, it extends jQM with a client-side parameters in the hash part of the url
10 (yay!!!)
bcf4d0a @azicchetti first commit
authored
11
443647e @azicchetti README was updated
authored
12 The jQuery Mobile router javascript file must be loaded before jQuery Mobile.
13
85e4e31 @azicchetti The public method: add() was implemented, so that users can dynamically
authored
14 This plugin can be used alone or (better) with Backbone.js or Spine.js, because it's
15 originally meant to replace their router with something integrated with jQM.
16
9cd50fd @azicchetti Update README.md
authored
17
18 Why
19 =====================
20 A lot of people wonder why this router uses jQuery Mobile events instead of simply listening for hashchange, as a normal controller would do.
e6ac42b @azicchetti Update README.md
authored
21
22 The main reason is to preserve the granularity offered by jQuery Mobile while giving the programmer a simple way to tap into "unusual" page transition states, such as "pageinit" or "pageremove", as if they were standard routes. The outcome is a controller which is more powerful and versatile, in the jQM realm, than its purely hashchange based counterpart.
23
24 Without a tight integration with the framework one would lose a lot of the possibilities offered by jQuery Mobile and this is not only a pity, but also very frustrating, especially when things get complicated (as it always does in real-life projects) and you need to resort to its most advanced functions.
25
26 In addition, if you want to use standard hashchange-based routers, you have to disable some of the features that make jQuery Mobile so unique among similar libraries and do a few things "by hand", just to fill an irreconcilable gap between how jQuery Mobile works and how we are used to handle routes in normal web applications.
9cd50fd @azicchetti Update README.md
authored
27
28
588eeb4 @azicchetti Documentation was updated
authored
29 What's new in the latest versions
30 =====================
4240fdd @azicchetti The "step" option for pagebeforechange events was implemented.
authored
31 * New options for pagebeforechange events: you can choose what kind of `toPage` argument your handler is
32 expecting: a string, a jQuery object or both
203fa6f @azicchetti Changed the way bC events are handled. The user must call e.preventDefau...
authored
33 * Slightly changed the special support for pagebeforechange events. You have to call e.preventDefault()
34 to pause the transition and use the deferred object
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
35 * Added a "special" support for the pagebeforechange event, modeled after the pagebeforeload event
3d47a42 @azicchetti Merge branch 'master' of github.com:azicchetti/jquerymobile-router
authored
36 * Support for jQM 1.3.0. Older jQM version are still supported in the legacy version
37 (jquery.mobile.router-legacy.js)
f92a6f9 @azicchetti Fixed the issue #48.
authored
38 * Form parameters are now correctly handled
edf70f0 @azicchetti Updated the stable version with pageload and pagebeforechange events.
authored
39 * support for pagebeforechange, pagebeforeload, pageload
6ddb709 @azicchetti Added the firstMatchOnly configuration parameter. This prevents the exec...
authored
40 * Added a parameter in the configuration object to execute only the first route handler found
a9ecc44 @azicchetti Support for a different syntax defining user routes.
authored
41 * Support for a different syntax defining your routes
588eeb4 @azicchetti Documentation was updated
authored
42 * Added a nice getParams() function to actually 'parse' parameters in the hash and get
43 a simple object to play with them.
44 * Support for the pageinit event.
45 * Bugfixes to support events for the first displayed page.
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
46 * Default handler support
3ec5bdd @azicchetti The original jqm event is now passed to route handlers (this is
authored
47 * The original jquery mobile event is passed down to route handlers
588eeb4 @azicchetti Documentation was updated
authored
48
854dc90 @azicchetti The documentation was updated
authored
49 Upgrade notes
50 =====================
4240fdd @azicchetti The "step" option for pagebeforechange events was implemented.
authored
51 v20130515 to v20130525
52 Your bC handlers need to explicitly invoke e.preventDefault()
53
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
54 0.5 to 0.6
55 You can define a default handler in the "conf" object. This will be called when
56 no matching routes are found in the set you've provided
57
af098e4 @azicchetti The examples and documentation were updated
authored
58 0.3 to 0.4
59 The main javascript file has been renamed to jquery.mobile.router.js
854dc90 @azicchetti The documentation was updated
authored
60
af098e4 @azicchetti The examples and documentation were updated
authored
61 0.2 to 0.3
62 There's no need to use the data-params="true" anymore in your anchors since hash params
63 are enabled by default.
64
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
65 **The reuseQueriedAjaxPages extension was removed since it wasn't so useful and
66 a similar behaviour can be achieved with the new jquery mobile caching mechanism
67 (but if you need it please mail me).**
bcf4d0a @azicchetti first commit
authored
68
69
70 The router/controller
71 =====================
72
73 Whenever jQuery Mobile changes the url (usually the fragment part) the router checks
74 if that particular url matches one of your routes and calls the handler you've
75 provided with a bunch of useful arguments.
76
77 When you define a route, you'll provide:
9cd50fd @azicchetti Update README.md
authored
78
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
79 * a regular expression to test the url/hash against
9570a9d @mzedeler Fixed typo
mzedeler authored
80 * a handler (a function)
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
81 * when your handler must be called (for example, you may decide to setup a route only when the pagecreate and pagebeforeshow jQM events are dispatched)
bcf4d0a @azicchetti first commit
authored
82
9cd50fd @azicchetti Update README.md
authored
83
bcf4d0a @azicchetti first commit
authored
84 The plugin exports a class in $.mobile.Router and you can instantiate your routers
85 with the following arguments:
86
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
87 `var approuter=new $.mobile.Router(myRoutes, myHandlers, options);`
bcf4d0a @azicchetti first commit
authored
88
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
89 * myRoutes is an object or an array defining your routes
90 * myHandlers is an object with your function handlers
91 * options is an object with a certain configuration (see below)
bcf4d0a @azicchetti first commit
authored
92
93
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
94 Here are a few examples:
95
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
96 ```javascript
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
97 var router=new $.mobile.Router([
98 { "/index.html": { events: "i", handler: "index" } },
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
99 { "/restaurant.html[?]id=(\\d+)": { events: "i", handler: "restaurantDetail" } }, // handwritten regexp
100 { "/events.html(?:[?](.*))?": { events: "i", handler: "events" } }, // handwritten regexp
101 { "/eventDetail.html": { events: "i", handler: "eventDetail", argsre: true } },
102 { "/accomodations.html": { events: "i", handler: "accomodationsTaxonomy", argsre: true } },
103 { "/accomodationList.html(?:[?](.*))?": { events: "i", handler: "accomodations" } } // handwritten regexp
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
104 ], ControllerObject, { ajaxApp: true} );
105
106 var router=new $.mobile.Router([
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
107 { "#ticketPlanner(?:[?](.*))?$": "ticketPlannerShown" },
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
108 { "#ticketConfirm": "ticketConfirmShown" },
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
109 { "#ticketDetail": { handler: "ticketDetailPage", events: "bs,h", argsre: true } },
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
110 { "#ticketHistory": "ticketHistoryShown" },
111 { "#map": { handler: "mapHidden", events: "bh" } },
112 { "#map": { handler: "mapShown", events: "s" } }
113 ], ControllerObject);
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
114 ```
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
115
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
116 **----- IMPORTANT (no kidding!) -----**
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
117
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
118 * By default, the router will match the routes against the hash part of the url.
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
119 If you need the FULL PATH (pathname+search+hash), please set the "ajaxApp" configuration
120 parameter to TRUE (see below)
121
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
122 * If you're using a multipage template in your jquerymobile application, the first displayed page is quite an "anomaly" in the navigation model, because, even if it has its own id, this
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
123 is not reflected in the hash. This doesn't happen for other pages. This "empty hash" problem
124 may come into play when the back button is used by the user.
125 Since writing an "empty" regular expression such as "^$" to match this page seems really
126 strange, the router will accept *only* a route with the page id, for example "#foobar"
127
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
128 * If you need to use backslashes (as in: \d, \s, etc) in your regular expressions, please make sure to escape them (\\\\d, \\\\s). You may test your regexp by using: "path to be matched".match( new RegExp("matching regexp") ).
129 However, you'll hardly need to write any regular expression in your routes. If you want to match parameters, you should use the `argsre` property (or the `defaultArgsRe` configuration setting). See below for an explanation.
529f08c @azicchetti Update README.md
authored
130
131
132
bcf4d0a @azicchetti first commit
authored
133 myRoutes object
134 ---------------
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
135 `myRoutes` supports the following formats:
a9ecc44 @azicchetti Support for a different syntax defining user routes.
authored
136
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
137 1. This one binds a certain route to the pagebeforeshow event and calls the handler, which can be an inline function or a function name (a string) that must be defined
5fb50ba @azicchetti Some bugfixes for pagebeforehide and pagehide events. Added support for ...
authored
138 in the myHandlers object
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
139
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
140 ```javascript
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
141 {
142 "regularExpression": "handlerName",
143
144 /* or */
145
146 "regularExpression": function(){
147 // your inline function here ...
bcf4d0a @azicchetti first commit
authored
148 }
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
149
150 /* or */
151
152 "regularExpression": someobject.functionReference
153 }
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
154 ```
bcf4d0a @azicchetti first commit
authored
155
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
156 2. This is the full syntax to specify various jQM events you want your route to be
bcf4d0a @azicchetti first commit
authored
157 bound to.
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
158 The object defines a "handler" property with a string value: this is the name
5fb50ba @azicchetti Some bugfixes for pagebeforehide and pagehide events. Added support for ...
authored
159 of a function defined in the myHandlers object. Again, you may also put an inline
160 function in the "handler" property instead of a string.
bcf4d0a @azicchetti first commit
authored
161 The object also defines an "events" property with a string value: this is a list
162 of (shortened) jQM events, separated by a ",". Your route will be called only when
163 these events are fired.
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
164
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
165 ```javascript
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
166 {
167 "regularExpression": {
168 handler: "handlerName",
169 events: "bc,c,bs,s,bh,h",
170 argsre: true //a boolean, can be omitted if false. see below
171 },
172
173 /* or */
174
175 "regularExpression": {
176 handler: function(){ ... },
177 events: "bc,c,bs,s,bh,h",
178 argsre: true //a boolean, can be omitted if false. see below
179 },
180 }
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
181 ```
bcf4d0a @azicchetti first commit
authored
182
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
183 Please refer to the following schema to understand event codes (it's really straightforward)
184
185 ```javascript
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
186 bc => pagebeforecreate
187 c => pagecreate
188 i => pageinit
189 bs => pagebeforeshow
190 s => pageshow
191 bh => pagebeforehide
192 h => pagehide
193 rm => pageremove
194 bC => pagebeforechange
195 bl => pagebeforeload
196 l => pageload
c12bb13 @azicchetti The readme was updated to cover some new events
authored
197
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
198 ```
bcf4d0a @azicchetti first commit
authored
199
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
200 * The above syntax, however, doesn't let one use the same regular expression to call different handlers (this is due to the fact that the regexp is a key into an hashmap,
a9ecc44 @azicchetti Support for a different syntax defining user routes.
authored
201 so it must be unique). If you need, for instance, to call the function "foo" when a
202 certain page has been shown, and the function "bar" when the same page has been hidden,
203 you could use the following syntax:
204
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
205 ```javascript
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
206 var approuter=new $.mobile.Router([
207 { "#certainPage": { handler: "foo", events: "s", argsre: true } },
208 { "#certainPage": { handler: "bar", events: "h" } }
209 ], {
210 foo: function(...){...},
211 bar: function(...){...}
212 }, options);
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
213 ```
a9ecc44 @azicchetti Support for a different syntax defining user routes.
authored
214
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
215 By using an array, you can specify the **SAME REGULAR EXPRESSION** multiple times, but for **DIFFERENT EVENT TYPES**.
216
4240fdd @azicchetti The "step" option for pagebeforechange events was implemented.
authored
217 The pagebeforechange event supports an additional parameter `step`, whose values can be:
218
219 * `page`: invoke the handler when `data.toPage` is a jQuery object.
220 This is the default when step is omitted
221
222 * `url` (or `string`): invoke the handler when `data.toPage` is a string
223
224 * `all`: always invoke the handler
225
226 This parameter is a convenient way to let the router know what kind of `data.toPage` parameter your handler is expecting. Please note that when the handler is invoked with a string argument, the `page` argument won't be available for manipulation.
227
a9ecc44 @azicchetti Support for a different syntax defining user routes.
authored
228
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
229 The "argsre" property is a boolean setting you can use to automatically append:
230 ```
231 (?:[?](.*))?$
232 ```
233 to the end of each regular expression.
234 It's a really convenient way to:
235
236 1) avoid the most common mistake in using the router (forgetting the $ operator)
237 2) define a route that supports hash parameters
238 3) use the router even without knowing what a regular expression is
239
240 You'll *hardly* need to write complex regular expressions, everything you may need can be accomplished
241 by setting argsre to true. You can also set the `defaultArgsRe` configuration switch to true,
242 so that every single route will automatically use the arguments-catcher regexp (you can override this
243 setting on a per-route basis with `argsre: false`)
244
245 Please remember that you can split the parameters and get them in a nice javascript object by using:
246 ```
247 routerInstance.getParams(string)
248 ```
249 See below for an example.
250
251
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
252 This is an example of a common `myRoutes` object:
bcf4d0a @azicchetti first commit
authored
253
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
254 Syntax 1:
bcf4d0a @azicchetti first commit
authored
255
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
256 ```javascript
bcf4d0a @azicchetti first commit
authored
257 {
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
258 "#localpage": {
259 handler: "localpage", events: "bs,bh", argsre: true
bcf4d0a @azicchetti first commit
authored
260 },
261
262 "ajaxPage.html(?:[?](.*))?": {
263 handler: "ajaxPage", events: "c,bs"
264 }
265 }
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
266 ```
bcf4d0a @azicchetti first commit
authored
267
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
268 Syntax 2:
269
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
270 ```javascript
a9ecc44 @azicchetti Support for a different syntax defining user routes.
authored
271 [
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
272 { "#localpage": { handler: "localpage", events: "bs,bh", argsre: true } },
a9ecc44 @azicchetti Support for a different syntax defining user routes.
authored
273
274 { "ajaxPage.html(?:[?](.*))?": { handler: "ajaxPage", events: "c,bs" } }
275 ]
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
276 ```
a9ecc44 @azicchetti Support for a different syntax defining user routes.
authored
277
eba4e40 @azicchetti Updated the README.md to document events in jQM
authored
278 Choosing the right event
279 -----------------
280 In order to successfully exploit routing under jQuery Mobile, the developer should have
281 at least a minimal knowledge of its event system (among other things!):
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
282 http://api.jquerymobile.com/category/events/
eba4e40 @azicchetti Updated the README.md to document events in jQM
authored
283
284 Once you're familiar with page change events, you can choose the right one in order to achieve
285 the desired behaviour in your application.
286 I know this may be a difficult choice, at least initially, so I'll try to sort things out for you.
287 Bear in mind that the following are just suggestions that cannot replace a deep knowledge
288 of the jQuery Mobile framework.
289
290 For single-file multipage applications (you have an html file containing a lot of jQM pages):
291
292 * pagebeforeshow or pageshow:
293 These events are called every time a particular page is shown.
294 This is perfect to render and update a page, often using the parameters in the hash part of the url
295
296 * pagebeforehide or pagehide:
297 These events are called every time a particular page is hidden.
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
298 You can use these events to clean views or models, to free resources and clean the DOM
299
300 * pagebeforechange:
301 Use this event if you want to STOP the transition from happening until you resolve a certain deferred
302 object. There's a paragraph describing this technique below
eba4e40 @azicchetti Updated the README.md to document events in jQM
authored
303
304 For ajax applications (multiple files containing a single jQM page):
305
306 * You can still use the events described above... but keep on reading, you may find a better option
307
308 * pagebeforecreate, pagecreate or pageinit:
309 These events are called before/after a jQuery Mobile page has been initialized. Remember that initialization
310 happens ***just once*** for a particular page (unless it's removed from the DOM, see below).
311 If you make changes to the DOM before a page or a widget is initialized, you won't have to update
312 or refresh it. But please note that if your models need to be refreshed through an ajax call,
313 you'll probably get your results back from the remote server when the page has already been widget-ified
314 by jQuery Mobile, so pay attention to this scenario and prefer the "pageinit" event, unless you know
315 what you're doing.
316
317 * pageremove:
318 This one is called when a page is automatically removed from the DOM by the framework. This applies only
319 to pages that were fetched via ajax.
320 When the user navigates away from a certain page, jQuery Mobile will remove it from the DOM to keep its
321 size small, unless otherwise specified (see the data-dom-cache="true" option in the doc).
322 Use this event to clean models and views references.
323
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
324
bcf4d0a @azicchetti first commit
authored
325 myHandlers object
326 -----------------
327 There isn't much to say about this object. Simply provide the function handlers you've
328 specified in the myRoutes object.
fb68ccf @azicchetti Fixed a potential issue with handlers scoping
authored
329 By default, your route handlers are executed in the myHandlers scope.
bcf4d0a @azicchetti first commit
authored
330
331 For example:
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
332
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
333 ```javascript
bcf4d0a @azicchetti first commit
authored
334 {
3ec5bdd @azicchetti The original jqm event is now passed to route handlers (this is
authored
335 handlerName: function(eventType, matchObj, ui, page, evt){
bcf4d0a @azicchetti first commit
authored
336 // your code here
337 }
338 }
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
339 ```
bcf4d0a @azicchetti first commit
authored
340
341 Your handlers will be called with the following arguments:
3ec5bdd @azicchetti The original jqm event is now passed to route handlers (this is
authored
342
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
343 * eventType: the name of the jQM event that's triggering the handler (pagebeforeshow,
3ec5bdd @azicchetti The original jqm event is now passed to route handlers (this is
authored
344 pagecreate, pagehide, etc)
345
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
346 * matchObj: the handler is called when your regular expression matches the current
3ec5bdd @azicchetti The original jqm event is now passed to route handlers (this is
authored
347 url or fragment. This is the match object of the regular expression.
348 If the regular expression uses groups, they will be available in this object.
349 Cool eh?
350
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
351 * ui: this is the second argument provided by the jQuery Mobile event. Usually holds
3ec5bdd @azicchetti The original jqm event is now passed to route handlers (this is
authored
352 the reference to either the next page (nextPage) or previous page (prevPage).
353 More information here: (http://jquerymobile.com/demos/1.0/docs/api/events.html)[http://jquerymobile.com/demos/1.0/docs/api/events.html]
354
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
355 * page: the dom element that originated the jquery mobile page event
bcf4d0a @azicchetti first commit
authored
356
3ec5bdd @azicchetti The original jqm event is now passed to route handlers (this is
authored
357 * evt: the original event that comes from jquery mobile. You can use this to
358 prevent the default behaviour and, for instance, stop a certain page from being
359 removed from the dom during the pageremove event.
360
361
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
362 About pagebeforechange
363 ----------------------
364 This is a special event withing jQuery Mobile, so it deserves a "special" support in the router.
365
366 When you want to "stop" a certain transition until you've done something to the page, this is the
4240fdd @azicchetti The "step" option for pagebeforechange events was implemented.
authored
367 right event to use.
368 Re-routing to another location works as well, more on that later.
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
369
203fa6f @azicchetti Changed the way bC events are handled. The user must call e.preventDefau...
authored
370 I've modeled the way it works after the pagebeforeload event. When your bC route is matched,
371 you can call e.preventDefault() to temporarily stop the transition and make your modifications
372 to the page.
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
373
4240fdd @azicchetti The "step" option for pagebeforechange events was implemented.
authored
374 You should know from jQM documentation that pagebeforechange is usually invoked twice, the first
375 time with a string parameter and eventually with a jQuery object.
376 By specifying the `step` parameter (see above), you can choose if you want your handler to be invoked
377 either with the string url, the page object or both. If `step` is omitted, it defaults to `page`.
378
379 The page reference is normalized by the router whenever it's possible (but when toPage is a string, page is
380 set to null) so that you get a nice jQuery object as if it was a standard pagebeforeshow event.
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
381
382 Take this simple handler as an example:
383 ```
384 beforeChangeHandler: function(type, match, ui, page, e){
203fa6f @azicchetti Changed the way bC events are handled. The user must call e.preventDefau...
authored
385 e.preventDefault();
4240fdd @azicchetti The "step" option for pagebeforechange events was implemented.
authored
386 console.log(page); // this is the page reference or null if ui.toPage is a string
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
387 console.log("Waiting 6 seconds before resolving the deferred...");
388 setTimeout(function(){
389 ui.bCDeferred.resolve();
390 },6000);
391 }
392 ```
393
203fa6f @azicchetti Changed the way bC events are handled. The user must call e.preventDefau...
authored
394 If you invoke preventDefault(), YOU MUST CALL: `ui.bCDeferred.resolve();` to continue the transition.
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
395
203fa6f @azicchetti Changed the way bC events are handled. The user must call e.preventDefau...
authored
396 Please DON'T call $.mobile.changePage(...) in this handler, because the router
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
397 does that for you, but if you're trying to achieve something different (that is to say, the scenario
398 described above does not match your situation) you may have to bind to pagebeforechange yourself and
399 implement your own logic.
400
401 You can also change the ui.toPage property from your handler, in order to re-route the transition
402 to another location. This seems to work but I've not tested it extensively, so use it with caution.
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
403 Remember to also change the ui.options.dataUrl property if you want the url to reflect this change.
397e23a @azicchetti Added a special support for the pagebeforechange event in order to tempo...
authored
404
405
edf70f0 @azicchetti Updated the stable version with pageload and pagebeforechange events.
authored
406 Common mistakes
407 --------------
408 jQuery Mobile is a wonderful framework and it seems really easy to use at first.
409 While this may be true for server-side generated mobile pages, things are very different
410 once you have to do a full client-side web application, using backbone.js or spine.js and
411 possibly Phonegap/Cordova.
412
413 The whole hash handling performed by jQuery Mobile may be confusing, dynamic page loading/injection
414 must be understood in order to be successfully exploited, and you should also know the jQM
415 event system to have a fine grained control over page switching.
416
417 Here is a list of things you should check when you're in trouble, based on my experience but,
418 more importantly, on the email I've received from other users of the jQM router.
419
420 * the router should be instantiated as soon as possible, possibly just after loading jquery mobile.
421 This ensures that even the first pageinit event can be catched and handled by the router
422
423 * please make sure that the router is not instantiated multiple times by mistake. This will lead to
424 routes being fired twice, at least
425
f92a6f9 @azicchetti Fixed the issue #48.
authored
426 * do not assign id's to page divs, unless you're using a single-file multipage template. In fact,
427 ids will interfere with data-url generation (at jquery mobile level) in ajax applications
428
edf70f0 @azicchetti Updated the stable version with pageload and pagebeforechange events.
authored
429 * do not call $.mobile.changePage during a page transition with the destination page being the one
430 the framework is already transitioning to.
431 That is to say, if you click on a link to #foo and you have a pagebeforeshow route bound to it,
432 DO NOT invoke $.mobile.changePage("#foo") in your handler (the result will be an epic failure due to
433 a bug in jquery mobile)
434
f92a6f9 @azicchetti Fixed the issue #48.
authored
435 * pay attention to the ORDER in which events are fired. Remember that pagebeforeshow is fired *before*
436 pagebeforehide, so if you're cleaning the dom when the page is being hidden and do your rendering stuff
437 in pagebeforeshow, you have to be careful during same-page transitions or you'll get a blank page.
438 You can use a certain counter (incremented during *show events and decremented during the hiding) and
439 clean the dom only when it's 0, or examine window.location, or (better) use the "ui" argument passed to
440 the handler (.nextPage is the property that you need)
441
edf70f0 @azicchetti Updated the stable version with pageload and pagebeforechange events.
authored
442 * DOUBLE CHECK your REGULAR EXPRESSIONS! A typical mistake is forgetting the $ operator.
443 If you have two pages, such as #product and #productList, a hypothetical route "#product" would
444 match both pages, leading to unexpected behaviors. Use the $ operator when unsure: "#product$"
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
445 or (better) the `argsre` (or `defaultArgsRe`) property set to true. See the `argsre` explanation above.
edf70f0 @azicchetti Updated the stable version with pageload and pagebeforechange events.
authored
446
447 * use setTimeout to avoid doing time-consuming tasks in a page-transition handler. If you have
448 a route bound to pagebeforeshow (or even other events) and your code takes too much to execute
449 (for instance, very long foreach loops, synchronous ajax calls, complex manupulations
450 of markers in a google map), jquery mobile may throw an error.
451
452
85e4e31 @azicchetti The public method: add() was implemented, so that users can dynamically
authored
453 Public methods
454 --------------
455
456 Router objects have the following public methods:
457
2d10ffa @azicchetti Update README.md
authored
458 * `add(myRoutes,myHandlers)`:
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
459 You can dynamically add routes on an already instantiated router.
460 The myRoutes and myHandlers objects were already described above.
85e4e31 @azicchetti The public method: add() was implemented, so that users can dynamically
authored
461
2d10ffa @azicchetti Update README.md
authored
462 * `destroy()`:
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
463 Unbind events and deactivate this router instance
85e4e31 @azicchetti The public method: add() was implemented, so that users can dynamically
authored
464
2d10ffa @azicchetti Update README.md
authored
465 * `getParams(hashPartOfTheUrl)`:
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
466 Returns an object with the parameters encoded in the url or null
2d10ffa @azicchetti Update README.md
authored
467 if nothing's found. It's particularly useful when used with a general regexp
468 such as the following one:
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
469 `#page(?:[?](.*))?`
470 or with the `argsre` property set to true.
ac2e528 @azicchetti Update README.md
authored
471
472 For instance, if you have this url: `#page?id=3&foo=bar`
473 and call:
2d10ffa @azicchetti Update README.md
authored
474 `routerInstance.getParams("?id=3&foo=bar")`
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
475 or (if you used the regexp or the argsre property)
ac2e528 @azicchetti Update README.md
authored
476 `routerInstance.getParams(match[1])`
477
2d10ffa @azicchetti Update README.md
authored
478 you'll get this object:
479
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
480 ```javascript
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
481 {
482 id: "3",
483 foo: "bar"
484 }
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
485 ```
af098e4 @azicchetti The examples and documentation were updated
authored
486
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
487 **There's an example under examples/backbone-example !**
af098e4 @azicchetti The examples and documentation were updated
authored
488
489
490 jQM Configuration
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
491 ==================
492
af098e4 @azicchetti The examples and documentation were updated
authored
493 jQuery Mobile Router supports the following parameters:
494
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
495 *`ajaxApp`: tells the plugin to use the full page path for its matches instead of
af098e4 @azicchetti The examples and documentation were updated
authored
496 the hash part of the url
497
6ddb709 @azicchetti Added the firstMatchOnly configuration parameter. This prevents the exec...
authored
498 *`firstMatchOnly`: stop searching for other route matches once the first one has been found
499 (only the first handler is executed). Defaults to false
af098e4 @azicchetti The examples and documentation were updated
authored
500
095737e @azicchetti Added the 'argsre' option to routes (and a default conf option called de...
authored
501 *`defaultArgsRe`: always append the default arguments-catcher regular expression to the end of
502 each route, unless argsre is false. *I strongly suggest you set this to true*.
503 Please see the `argsre` explanation above. Defaults to false.
504
e09876c @azicchetti Added support for string function names for the defaultHandler property
authored
505 *`defaultHandler`: a function reference or a function name to be called when no matching
506 route is found. You MUST also define the `defaultHandlerEvents` property when using
38f76c0 @azicchetti Issue #73 has been fixed: users can specify a debugHandler in the config...
authored
507 this one
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
508
ed0a8d1 @garrensmith Needed to rename to README.md for github to pick it up as markdown. Clea...
garrensmith authored
509 *`defaultHandlerEvents`: the defaultHandler will be called for these events, if
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
510 no routes are matched. Please note that THESE EVENTS MUST BE DEFINED
511 AT LEAST ONCE IN ANOTHER ROUTE, otherwise the defaultHandler won't be executed.
512 That is to say, if your routes are defined for "pagebeforeshow" and "pageshow"
513 events only, a defaultHandler for the "pagehide" event won't work!
514
38f76c0 @azicchetti Issue #73 has been fixed: users can specify a debugHandler in the config...
authored
515 *`debugHandler`: a function reference or a function name that will be called with
516 debugging information. If none supplied, this will default to ``console.log`` if
517 such exists. Set this to `false` to disable debugging completely.
518
17eff56 @azicchetti Fixed a problem with the configuration option passed to router instances...
authored
519
af098e4 @azicchetti The examples and documentation were updated
authored
520 You can pass an object with the above properties to the single router instance or set it
521 globally with this code (must be used BEFORE loading jquery.mobile.router.js):
85e4e31 @azicchetti The public method: add() was implemented, so that users can dynamically
authored
522
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
523 ```javascript
af098e4 @azicchetti The examples and documentation were updated
authored
524 $(document).bind("mobileinit",function(){
525 $.mobile.jqmRouter={
526 ajaxApp: true
527 };
528 });
88a579c @garrensmith Update README adding Code tags to Markdown just to make it a little easi...
garrensmith authored
529 ```
85e4e31 @azicchetti The public method: add() was implemented, so that users can dynamically
authored
530
4240fdd @azicchetti The "step" option for pagebeforechange events was implemented.
authored
531
532 Phonegap/Cordova
533 ==============
534
535 There is nothing to do to use the router in a Phonegap/Cordova environment, just include the
536 cordova javascript file and you're done.
537
538 However, you must pay attention to a super-stupid bug of the Android platform that impacts on the
539 ability to use jQuery Mobile (not the router) in "ajax mode" on certain Android 3.x and 4.0.x versions:
540
541 http://code.google.com/p/android/issues/detail?id=17535
542
443d352 @azicchetti Fix for #77.
authored
543 Cordova 2.x includes a workaround for this, but if you need to use an older version for whatever reason,
544 you may experience the dreaded "chromium error: -6".
545 However, there's a simple patch you can apply using the router and the pagebeforeload event.
4240fdd @azicchetti The "step" option for pagebeforechange events was implemented.
authored
546 I won't put it here in the documentation since it's not a general use-case, but if you really need it,
547 just open an issue on github or send me a private email.
548
549
550
854dc90 @azicchetti The documentation was updated
authored
551 Notes on jQM router
bcf4d0a @azicchetti first commit
authored
552 ==============
553
554 Have you ever wanted client-side parameters in the hash part of the url in jQuery Mobile?
555
a82c64e @azicchetti Updated the version string in the file header
authored
556 Well, jquery mobile router automatically enables this feature for you and fixes what's actually
557 broken in the partial support offered by jQM itself.
bcf4d0a @azicchetti first commit
authored
558
559 For bugs, comments, patches and requests mail me!
560
8c52b8f @piscis adding license text to readme
piscis authored
561 License
562 ==============
a14bac8 @piscis adding copyright header
piscis authored
563
564 Copyright 2011 (c) Andrea Zicchetti
565
8c52b8f @piscis adding license text to readme
piscis authored
566 You may use jQueryMobile-Router under the terms of either the MIT License or the GNU General Public License (GPL) Version 2.
567
568 You don’t have to do anything special to choose one license or the other and you don’t have to notify anyone which license you are using. You are free to use a jQueryMobile-Router in commercial projects as long as the copyright header is left intact.
569
9ab696d @piscis changed wording
piscis authored
570 **For more information see:**
8c52b8f @piscis adding license text to readme
piscis authored
571
572 * [MIT License](http://github.com/azicchetti/jquerymobile-router/blob/master/MIT-LICENSE.txt) [(More Information)](http://en.wikipedia.org/wiki/MIT_License)
fb68ccf @azicchetti Fixed a potential issue with handlers scoping
authored
573 * [GPL](http://github.com/azicchetti/jquerymobile-router/blob/master/GPL-LICENSE.txt) [(More Information)](http://en.wikipedia.org/wiki/GNU_General_Public_License)
Something went wrong with that request. Please try again.