forked from azicchetti/jquerymobile-router
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
229 lines (165 loc) · 6.7 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
================================================================================
jquerymobile-router
================================================================================
jQuery Mobile router is a plugin for jQuery Mobile to enhance the framework
with a client side router/controller that works with jQuery Mobile events
(pagebeforecreate, pagecreate, pagebeforeshow, pageshow, pagebeforehide, pagehide).
In addition, it extends jQM with a client-side parameters in the hash part of the url
(yay!!!)
The jQuery Mobile router javascript file must be loaded before jQuery Mobile.
This plugin can be used alone or (better) with Backbone.js or Spine.js, because it's
originally meant to replace their router with something integrated with jQM.
=====================
What's new in the latest versions
=====================
* Added a nice getParams() function to actually 'parse' parameters in the hash and get
a simple object to play with them.
* Support for the pageinit event.
* Bugfixes to support events for the first displayed page.
=====================
Upgrade notes
=====================
0.3 to 0.4
The main javascript file has been renamed to jquery.mobile.router.js
0.2 to 0.3
There's no need to use the data-params="true" anymore in your anchors since hash params
are enabled by default.
The reuseQueriedAjaxPages extension was removed since it wasn't so useful and
a similar behaviour can be achieved with the new jquery mobile caching mechanism
(but if you need it please mail me).
=====================
The router/controller
=====================
Whenever jQuery Mobile changes the url (usually the fragment part) the router checks
if that particular url matches one of your routes and calls the handler you've
provided with a bunch of useful arguments.
When you define a route, you'll provide:
* a regular expression to test the url/hash against
* an handler (a function)
* 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)
The plugin exports a class in $.mobile.Router and you can instantiate your routers
with the following arguments:
var approuter=new $.mobile.Router(myRoutes, myHandlers, options);
* myRoutes is an object defining your routes
* myHandlers is an object with your function handlers
* options is an object with a certain configuration (see below)
---------------
myRoutes object
---------------
myRoutes supports the following formats:
* 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
in the myHandlers object
{
"regularExpression": "handlerName",
/* or */
"regularExpression": function(){
// your inline function here ...
}
/* or */
"regularExpression": someobject.functionReference
}
* this is the full syntax to specify various jQM events you want your route to be
bound to.
The object defines an "handler" property with a string value: this is the name
of a function defined in the myHandlers object. Again, you may also put an inline
function in the "handler" property instead of a string.
The object also defines an "events" property with a string value: this is a list
of (shortened) jQM events, separated by a ",". Your route will be called only when
these events are fired.
{
"regularExpression": {
handler: "handlerName",
events: "bc,c,bs,s,bh,h"
},
/* or */
"regularExpression": {
handler: function(){ ... },
events: "bc,c,bs,s,bh,h"
},
}
Please refer to the following schema to understand event codes (it's really
straightforward)
bc => pagebeforecreate
c => pagecreate
i => pageinit
bs => pagebeforeshow
s => pageshow
bh => pagebeforehide
h => pagehide
This is an example of a common myRoutes object:
{
"#localpage(?:[?/](.*))?": {
handler: "localpage", events: "bs,bh"
},
"ajaxPage.html(?:[?](.*))?": {
handler: "ajaxPage", events: "c,bs"
}
}
-----------------
myHandlers object
-----------------
There isn't much to say about this object. Simply provide the function handlers you've
specified in the myRoutes object.
For example:
{
handlerName: function(eventType,matchObj,ui,page){
// your code here
}
}
Your handlers will be called with the following arguments:
* eventType: the name of the jQM event that's triggering the handler (pagebeforeshow,
pagecreate, pagehide, etc)
* matchObj: the handler is called when your regular expression matches the current
url or fragment. This is the match object of the regular expression.
If the regular expression uses groups, they will be available in this object.
Cool eh?
* ui: this is the second argument provided by the jQuery Mobile event. Usually holds
the reference to either the next page (nextPage) or previous page (prevPage).
More information here: http://jquerymobile.com/demos/1.0b1/docs/api/events.html
* page: the dom element that originated the jquery mobile page event
--------------
Public methods
--------------
Router objects have the following public methods:
add(myRoutes,myHandlers):
You can dynamically add routes on an already instantiated router.
The myRoutes and myHandlers objects were already described above.
destroy():
Unbind events and deactivate this router instance
getParams(hashPartOfTheUrl):
Returns an object with the parameters encoded in the url or null
if nothing's found.
For instance, if you have something like:
#detail?id=3&foo=bar
and call routerInstance.getParams("?id=3&foo=bar")
you'll get:
{
id: "3",
foor: "bar"
}
There's an example under examples/backbone-example !
==============
jQM Configuration
==============
jQuery Mobile Router supports the following parameters:
ajaxApp: tells the plugin to use the full page path for its matches instead of
the hash part of the url
You can pass an object with the above properties to the single router instance or set it
globally with this code (must be used BEFORE loading jquery.mobile.router.js):
$(document).bind("mobileinit",function(){
$.mobile.jqmRouter={
ajaxApp: true
};
});
==============
Notes on jQM router
==============
Have you ever wanted client-side parameters in the hash part of the url in jQuery Mobile?
Well, jquery mobile router automatically enables this feature for you, using an official
"hack"* provided in the jQM documentation.
* This hack isn't quite different from the one previously used by this plugin. But since
there's something 'official', we'll be guaranteed that our code will be supported in future
releases and I'm extremely happy about this.
For bugs, comments, patches and requests mail me!