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
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>jQuery Mobile Docs - Events</title>
<link rel="stylesheet" href="../../css/themes/default/jquery.mobile-1.2.0.css" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="../../js/jquery.js"></script>
<script src="../../docs/_assets/js/jqm-docs.js"></script>
<script src="../../js/jquery.mobile-1.2.0.js"></script>
</head>
<body>
<div data-role="page" class="type-interior">
<div data-role="header" data-theme="f">
<h1>Events</h1>
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse">Home</a>
<a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog" data-transition="fade">Search</a>
</div><!-- /header -->
<div data-role="content">
<div class="content-primary">
<p>jQuery Mobile offers several custom events that build upon native events to create useful hooks for development. Note that these events employ various touch, mouse, and window events, depending on event existence, so you can bind to them for use in both handheld and desktop environments. You can bind to these events like you would with other jQuery events, using <code>live()</code> or <code>bind()</code>.</p>
<div class="ui-body ui-body-e">
<h4 style="margin:.5em 0">Important: Use <code>$(document).bind('pageinit')</code>, not <code>$(document).ready()</code></h4>
<p>The first thing you learn in jQuery is to call code inside the <code>$(document).ready()</code> function so everything will execute as soon as the DOM is loaded. However, in jQuery Mobile, Ajax is used to load the contents of each page into the DOM as you navigate, and the DOM ready handler only executes for the first page. To execute code whenever a new page is loaded and created, you can bind to the <code>pageinit</code> event. This event is explained in detail at the bottom of this page.</p></div>
<p> </p>
<div class="ui-body ui-body-e">
<h4 style="margin:.5em 0">Important: <code>$(document).bind('pagecreate')</code> vs <code>$(document).bind('pageinit')</code></h4>
<p> Prior to Beta 2 the recommendation to users wishing to manipulate jQuery Mobile enhanced pages and child widget markup was to bind to the <code>pagecreate</code> event. In Beta 2 an internal change was made to decouple each of the widgets by binding to the <code>pagecreate</code> event in place of direct calls to the widget methods. As a result, users binding to the <code>pagecreate</code> in <code>mobileinit</code> would find their binding executing before the markup had been enhanced by each of the plugins. In keeping with the lifecycle of the jQuery UI Widget Factory, the initialization method is invoked <strong>after</strong> the create method, so the <code>pageinit</code> event provides the correct timing for post enhancement manipulation of the DOM and/or Javascript objects.
In short, if you were previously using <code>pagecreate</code> to manipulate the enhanced markup before the page was shown, it's very likely you'll want to migrate to 'pageinit'.
</p></div>
<h2>Touch events</h2>
<dl>
<dt><code>tap</code></dt>
<dd><p>Triggers after a quick, complete touch event.</p>
</dd>
<dt><code>taphold</code></dt>
<dd><p>Triggers after a held complete touch event.</p>
<ul>
<li><code>$.event.special.tap.tapholdThreshold</code> (default: 750ms) – This value dictates how long the user must hold their tap before the taphold event is fired on the target element.</li>
</ul>
</dd>
<dt><code>swipe</code></dt>
<dd><p>Triggers when a horizontal drag of 30px or more (and less than 75px vertically) occurs within 1 second duration but these can be configured:</p>
<ul>
<li><code>$.event.special.swipe.scrollSupressionThreshold</code> (default: 10px) – More than this horizontal displacement, and we will suppress scrolling.</li>
<li><code>$.event.special.swipe.durationThreshold</code> (default: 1000ms) – More time than this, and it isn't a swipe.</li>
<li><code>$.event.special.swipe.horizontalDistanceThreshold</code> (default: 30px) – Swipe horizontal displacement must be more than this.</li>
<li><code>$.event.special.swipe.verticalDistanceThreshold</code> (default: 75px) – Swipe vertical displacement must be less than this.</li>
</ul>
</dd>
<dt><code>swipeleft</code></dt>
<dd>Triggers when a swipe event occurred moving in the left direction.</dd>
<dt><code>swiperight</code></dt>
<dd>Triggers when a swipe event occurred moving in the right direction.</dd>
</dl>
<h2>Virtual mouse events</h2>
<p>We provide a set of "virtual" mouse events that attempt to abstract away mouse and touch events. This allows the developer to register listeners for the basic mouse events, such as mousedown, mousemove, mouseup, and click, and the plugin will take care of registering the correct listeners behind the scenes to invoke the listener at the fastest possible time for that device. In touch environments, the plugin retains the order of event firing that is seen in traditional mouse environments, so for example, vmouseup is always dispatched before vmousedown, and vmousedown before vclick, etc. The virtual mouse events also normalize how coordinate information is extracted from the event, so in touch based environments, coordinates are available from the pageX, pageY, screenX, screenY, clientX, and clientY properties, directly on the event object.</p>
<dl>
<dt><code>vmouseover</code></dt>
<dd>Normalized event for handling touch or <code>mouseover</code> events</dd>
<dt><code>vmouseout</code></dt>
<dd>Normalized event for handling touch or <code>mouseout</code> events</dd>
<dt><code>vmousedown</code></dt>
<dd>Normalized event for handling touchstart or <code>mousedown</code> events</dd>
<dt><code>vmousemove</code></dt>
<dd>Normalized event for handling touchmove or <code>mousemove</code> events</dd>
<dt><code>vmouseup</code></dt>
<dd>Normalized event for handling touchend or <code>mouseup</code> events</dd>
<dt><code>vclick</code></dt>
<dd>Normalized event for handling touchend or mouse <code>click</code> events. On touch devices, this event is dispatched *AFTER* vmouseup. </dd>
<dt><code>vmousecancel</code></dt>
<dd>Normalized event for handling touch or mouse <code>mousecancel</code> events</dd>
</dl>
<div class="ui-body ui-body-e">
<h4 style="margin:.5em 0">Warning: Use vclick with caution</h4>
<p> Use vclick with caution on touch devices. Webkit based browsers synthesize <code>mousedown</code>, <code>mouseup</code>, and <code>click</code> events roughly 300ms after the <code>touchend</code> event is dispatched. The target of the synthesized mouse events are calculated at the time they are dispatched and are based on the location of the touch events and, in some cases, the implementation specific heuristics which leads to different target calculations on different devices and even different OS versions for the same device. This means the target element within the original touch events could be different from the target element within the synthesized mouse events.</p>
<p>We recommend using <code>click</code> instead of <code>vclick</code> anytime the action being triggered has the possibility of changing the content underneath the point that was touched on screen. This includes page transitions and other behaviors such as collapse/expand that could result in the screen shifting or content being completely replaced.</p>
</div>
<p> </p>
<div class="ui-body ui-body-e">
<h4 style="margin:.5em 0">Canceling an element's default click behavior</h4>
<p>Applications can call <code>preventDefault()</code> on a <code>vclick</code> event to cancel an element's default click behavior. On mouse based devices, calling <code>preventDefault()</code> on a <code>vclick</code> event equates to calling <code>preventDefault()</code> on the real <code>click</code> event during the bubble event phase. On touch based devices, it's a bit more complicated since the actual <code>click</code> event is dispatched about 300ms after the <code>vclick</code> event is dispatched. For touch devices, calling <code>preventDefault()</code> on a <code>vclick</code> event triggers some code in the vmouse plugin that attempts to catch the next <code>click</code> event that gets dispatched by the browser, during the capture event phase, and calls <code>preventDefault()</code> and <code>stopPropagation()</code> on it. As mentioned in the warning above, it is sometimes difficult to match up a touch event with its corresponding mouse event because the targets can differ. For this reason, the vmouse plugin also falls back to attempting to identify a corresponding <code>click</code> event by coordinates. There are still cases where both target and coordinate identification fail, which results in the <code>click</code> event being dispatched and either triggering the default action of the element, or in the case where content has been shifted or replaced, triggering a click on a different element. If this happens on a regular basis for a given element/control, we suggest you use <code>click</code> for triggering your action.</p>
</div>
<dd><p>The virtual mouse events can also be configured:</p>
<ul>
<li><code>$.vmouse.moveDistanceThreshold</code> (default: 10px) – More than this, then it is a scroll event. The vmousecancel event is called and the TouchMove event is cancelled.</li>
<li><code>$.vmouse.clickDistanceThreshold</code> (default: 10px) – If a vclick event was already captured and is in the block list, then vclicks less than this distance are ignored.</li>
<li><code>$.vmouse.resetTimerDuration</code> (default: 1500ms) – More time than this, then it is not a touch event. Scroll, TouchMove and TouchEnd events use this. The block list is cleared.</li>
</ul>
</dd>
<h2>Orientation change event</h2>
<dl>
<dt><code>orientationchange</code></dt>
<dd>Triggers when a device orientation changes (by turning it vertically or horizontally). When bound to this event, the callback function has one argument, the event object. The event object contains an <code>orientation</code> property equal to either "portrait" or "landscape". Note that we currently bind to the resize event when <code>orientationchange</code> is not natively supported, or when <code>$.mobile.orientationChangeEnabled</code> is set to false.</dd>
<div class="ui-body ui-body-e">
<h4>orientationchange timing</h4>
<p> The timing of the <code>orientationchange</code> with relation to the change of the client height and width is different between browsers, though the current implementation will give you the correct value for <code>event.orientation</code> derived from <code>window.orientation</code>. This means that if your bindings are dependent on the height and width values you may want to disable <code>orientationChange</code> all together with <code>$.mobile.orientationChangeEnabled = false</code> to let the fallback resize code trigger your bindings.</p>
</div>
</dl>
<h2>Scroll events</h2>
<dl>
<dt><code>scrollstart</code></dt>
<dd>Triggers when a scroll begins. Note that iOS devices freeze DOM manipulation during scroll, queuing them to apply when the scroll finishes. We're currently investigating ways to allow DOM manipulations to apply before a scroll starts.</dd>
</dl>
<dl>
<dt><code>scrollstop</code></dt>
<dd>Triggers when a scroll finishes.</dd>
</dl>
<h2>Page load events</h2>
<p>Whenever an external page is loaded into the application DOM, 2 events are fired. The first is <code>pagebeforeload</code>. The 2nd event will be either <code>pageload</code> or <code>pageloadfailed</code>.</p>
<dl>
<dt><code>pagebeforeload</code></dt>
<dd><p>Triggered before any load request is made. Callbacks bound to this event can call <code>preventDefault()</code> on the event to indicate that they are handling the load request. Callbacks that do this *MUST* make sure they call <code>resolve()</code> or <code>reject()</code> on the deferred object reference contained in the data object passed to the callback.</p>
<p>The data object, passed as the 2nd arg to the callback function contains the following properties:</p>
<ul>
<li><code>url</code> (string)
<ul>
<li>The absolute or relative URL that was passed into $.mobile.loadPage() by the caller.</li>
</ul>
</li>
<li><code>absUrl</code> (string)
<ul>
<li>The absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.</li>
</ul>
</li>
<li><code>dataUrl</code> (string)
<ul>
<li>The filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.</li>
</ul>
</li>
<li><code>deferred</code> (object)
<ul>
<li>Callbacks that call preventDefault() on the event, *MUST* call resolve() or reject() on this object so that changePage() requests resume processing. Deferred object observers expect the deferred object to be resolved like this:</p>
<pre><code>
$( document ).bind( "pagebeforeload", function( event, data ){
// Let the framework know we're going to handle the load.
event.preventDefault();
// ... load the document then insert it into the DOM ...
// at some point, either in this callback, or through
// some other async means, call resolve, passing in
// the following args, plus a jQuery collection object
// containing the DOM element for the page.
data.deferred.resolve( data.absUrl, data.options, page );
});</code></pre>
<p>or rejected like this:
<pre><code>
$( document ).bind( "pagebeforeload", function( event, data ){
// Let the framework know we're going to handle the load.
event.preventDefault();
// ... load the document then insert it into the DOM ...
// at some point, if the load fails, either in this
// callback, or through some other async means, call
// reject like this:
data.deferred.reject( data.absUrl, data.options );
});</code></pre>
</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the options that were passed into $.mobile.loadPage().</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pageload</code></dt>
<dd>Triggered after the page is successfully loaded and inserted into the DOM. Callbacks bound to this event will be passed a data object as its 2nd arg. This object contains the following information:
<ul>
<li><code>url</code> (string)
<ul>
<li>The absolute or relative URL that was passed into $.mobile.loadPage() by the caller.</li>
</ul>
</li>
<li><code>absUrl</code> (string)
<ul>
<li>The absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.</li>
</ul>
</li>
<li><code>dataUrl</code> (string)
<ul>
<li>The filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the options that were passed into $.mobile.loadPage().</li>
</ul>
</li>
<li><code>xhr</code> (object)
<ul>
<li>The jQuery XMLHttpRequest object used when attempting to load the page. This is what gets passed as the 3rd argument to the framework's $.ajax() success callback.</li>
</ul>
</li>
<li><code>textStatus</code> (null or string)
<ul>
<li>According to the jQuery Core <a href="http://api.jquery.com/jQuery.ajax/">documentation</a>, this will be a string describing the status. This is what gets passed as the 2nd argument to the framework's $.ajax() error callback.</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pageloadfailed</code></dt>
<dd>Triggered if the page load request failed. By default, after dispatching this event, the framework will display a page failed message and call reject() on the deferred object contained within the event's data object. Callbacks can prevent this default behavior from executing by calling preventDefault() on the event.
<p>The data object, passed as the 2nd arg to the callback function contains the following properties:</p>
<ul>
<li><code>url</code> (string)
<ul>
<li>The absolute or relative URL that was passed into $.mobile.loadPage() by the caller.</li>
</ul>
</li>
<li><code>absUrl</code> (string)
<ul>
<li>The absolute version of the url. If url was relative, it is resolved against the url used to load the current active page.</li>
</ul>
</li>
<li><code>dataUrl</code> (string)
<ul>
<li>The filtered version of absUrl to be used when identifying the page and updating the browser location when the page is made active.</li>
</ul>
</li>
<li><code>deferred</code> (object)
<ul>
<li>Callbacks that call preventDefault() on the event, *MUST* call resolve() or reject() on this object so that changePage() requests resume processing. Deferred object observers expect the deferred object to be resolved like this:</p>
<pre><code>
$( document ).bind( "pageloadfailed", function( event, data ){
// Let the framework know we're going to handle things.
event.preventDefault();
// ... attempt to load some other page ...
// at some point, either in this callback, or through
// some other async means, call resolve, passing in
// the following args, plus a jQuery collection object
// containing the DOM element for the page.
data.deferred.resolve( data.absUrl, data.options, page );
});</code></pre>
<p>or rejected like this:
<pre><code>
$( document ).bind( "pageloadfailed", function( event, data ){
// Let the framework know we're going to handle things.
event.preventDefault();
// ... attempt to load some other page ...
// at some point, if the load fails, either in this
// callback, or through some other async means, call
// reject like this:
data.deferred.reject( data.absUrl, data.options );
});</code></pre>
</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the options that were passed into $.mobile.loadPage().</li>
</ul>
</li>
<li><code>xhr</code> (object)
<ul>
<li>The jQuery XMLHttpRequest object used when attempting to load the page. This is what gets passed as the first argument to the framework's $.ajax() error callback.</li>
</ul>
</li>
<li><code>textStatus</code> (null or string)
<ul>
<li>According to the jQuery Core <a href="http://api.jquery.com/jQuery.ajax/">documentation</a>, possible values for this property, aside from null, are "timeout", "error", "abort", and "parsererror". This is what gets passed as the 2nd argument to the framework's $.ajax() error callback.</li>
</ul>
</li>
<li><code>errorThrown</code> (null, string, object)
<ul>
<li>According to the jQuery Core <a href="http://api.jquery.com/jQuery.ajax/">documentation</a>, this property may be an exception object if one occurred, or if an HTTP error occurred this will be set to the textual portion of the HTTP status. This is what gets passed as the 3rd argument to the framework's $.ajax() error callback.</li>
</ul>
</li>
</ul>
</dd>
</dl>
<h2>Page change events</h2>
<p>Navigating between pages in the application is usually accomplished through a call to <code>$.mobile.changePage()</code>. This function is responsible for making sure that the page to which we are navigating is loaded and inserted into the DOM, and then kicking off the transition animations between the current active page, and the page the caller wants to make active. During this process, which is usually asynchronous, changePage() will fire off 2 events. The first is <code>pagebeforechange</code>. The second event depends on the success or failure of the change request. It will either be <code>pagechange</code> or <code>pagechangefailed</code>.</p>
<dl>
<dt><code>pagebeforechange</code></dt>
<dd>This event is triggered prior to any page loading or transition. Callbacks can prevent execution of the changePage() function by calling preventDefault on the event object passed into the callback. The callback also receives a data object as its 2nd arg. The data object has the following properties:
<ul>
<li><code>toPage</code> (object or string)
<ul>
<li>This property represents the page the caller wishes to make active. It can be either a jQuery collection object containing the page DOM element, or an absolute/relative url to an internal or external page. The value exactly matches the 1st arg to the changePage() call that triggered the event.</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the configuration options to be used for the current changePage() call.</li>
</ul>
</li>
</ul>
<p>It should be noted that callbacks can modify both the <code>toPage</code> and <code>options</code> properties to alter the behavior of the current <code>changePage()</code> call. So for example, the <code>toPage</code> can be mapped to a different url from within a callback to do a sort of redirect.</p>
</dd>
<dt><code>pagechange</code></dt>
<dd>This event is triggered after the <code>changePage()</code> request has finished loading the page into the DOM and all page transition animations have completed. Note that any pageshow or pagehide events will have fired *BEFORE* this event is triggered. Callbacks for this particular event will be passed a data object as the 2nd arg. The properties for this object are as follows:
<ul>
<li><code>toPage</code> (object or string)
<ul>
<li>This property represents the page the caller wishes to make active. It can be either a jQuery collection object containing the page DOM element, or an absolute/relative url to an internal or external page. The value exactly matches the 1st arg to the changePage() call that triggered the event.</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the configuration options to be used for the current changePage() call.</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pagechangefailed</code></dt>
<dd>This event is triggered when the <code>changePage()</code> request fails to load the page. Callbacks for this particular event will be passed a data object as the 2nd arg. The properties for this object are as follows:
<ul>
<li><code>toPage</code> (object or string)
<ul>
<li>This property represents the page the caller wishes to make active. It can be either a jQuery collection object containing the page DOM element, or an absolute/relative url to an internal or external page. The value exactly matches the 1st arg to the changePage() call that triggered the event.</li>
</ul>
</li>
<li><code>options</code> (object)
<ul>
<li>This object contains the configuration options to be used for the current changePage() call.</li>
</ul>
</li>
</ul>
</dd>
</dl>
<h2>Page transition events</h2>
<p>Page transitions are used to animate the change from the current active page (fromPage) to a new page (toPage). Events are triggered before and after these transitions so that observers can be notified whenever pages are shown or hidden. The events triggered are as follows:</p>
<dl>
<dt><code>pagebeforeshow</code></dt>
<dd>Triggered on the "toPage" we are transitioning to, before the actual transition animation is kicked off. Callbacks for this event will receive a data object as their 2nd arg. This data object has the following properties on it:
<ul>
<li><code>prevPage</code> (object)
<ul>
<li>A jQuery collection object that contains the page DOM element that we are transitioning away from. Note that this collection is empty when the first page is transitioned in during application startup.</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pagebeforehide</code></dt>
<dd>Triggered on the "fromPage" we are transitioning away from, before the actual transition animation is kicked off. Callbacks for this event will receive a data object as their 2nd arg. This data object has the following properties on it:
<ul>
<li><code>nextPage</code> (object)
<ul>
<li>A jQuery collection object that contains the page DOM element that we are transitioning to.</li>
</ul>
</li>
</ul>
<p>Note that this event will not be dispatched during the transition of the first page at application startup since there is no previously active page.</p>
</dd>
<dt><code>pageshow</code></dt>
<dd>Triggered on the "toPage" after the transition animation has completed. Callbacks for this event will receive a data object as their 2nd arg. This data object has the following properties on it:
<ul>
<li><code>prevPage</code> (object)
<ul>
<li>A jQuery collection object that contains the page DOM element that we just transitioned away from. Note that this collection is empty when the first page is transitioned in during application startup.</li>
</ul>
</li>
</ul>
</dd>
<dt><code>pagehide</code></dt>
<dd>Triggered on the "fromPage" after the transition animation has completed. Callbacks for this event will receive a data object as their 2nd arg. This data object has the following properties on it:
<ul>
<li><code>nextPage</code> (object)
<ul>
<li>A jQuery collection object that contains the page DOM element that we just transitioned to.</li>
</ul>
</li>
</ul>
<p>Note that this event will not be dispatched during the transition of the first page at application startup since there is no previously active page.</p>
</dd>
</dl>
<p>You can access the <code>prevPage</code> or <code>nextPage</code> properties via the second argument of a bound callback function. For example: </p>
<pre><code>
$( 'div' ).live( 'pageshow',function(event, ui){
alert( 'This page was just hidden: '+ ui.prevPage);
});
$( 'div' ).live( 'pagehide',function(event, ui){
alert( 'This page was just shown: '+ ui.nextPage);
});
</code></pre>
<p>Also, for these handlers to be invoked during the initial page load, you must bind them before jQuery Mobile executes. This can be done in the <code>mobileinit</code> handler, as described on the <a href="globalconfig.html">global config</a> page.
<h2>Page initialization events</h2>
<p>Internally, jQuery Mobile auto-initializes plugins based on the markup conventions found in a given "page". For example, an <code>input</code> element with a <code>type</code> of <code>range</code> will automatically generate a custom slider control.</p>
<p>This auto-initialization is controlled by the "page" plugin, which dispatches events before and after it executes, allowing you to manipulate a page either pre-or-post initialization, or even provide your own initialization behavior and prevent the auto-initializations from occurring. Note that these events will only fire once per "page", as opposed to the show/hide events, which fire every time a page is shown and hidden.</p>
<dl>
<dt><code>pagebeforecreate</code></dt>
<dd>
<p>Triggered on the page being initialized, before most plugin auto-initialization occurs.</p>
<pre><code>
$( '#aboutPage' ).live( 'pagebeforecreate',function(event){
alert( 'This page was just inserted into the dom!' );
});
</code></pre>
<p>Note that by binding to <code>pagebeforecreate</code>, you can manipulate markup before jQuery Mobile's default widgets are auto-initialized. For example, say you want to add data attributes via JavaScript instead of in the HTML source, this is the event you'd use.</p>
<pre><code>
$( '#aboutPage' ).live( 'pagebeforecreate',function(event){
// manipulate this page before its widgets are auto-initialized
});
</code></pre>
</dd>
<dt><code>pagecreate</code></dt>
<dd>
<p>Triggered when the page has been created in the DOM (via ajax or other) but before all widgets have had an opportunity to enhance the contained markup. This event is most useful for user's wishing to create their own custom widgets for child markup enhancement as the jquery mobile widgets do.</p>
<pre><code>
$( '#aboutPage' ).live( 'pagecreate',function(event){
( ":jqmData(role='sweet-plugin')" ).sweetPlugin();
});
</code></pre>
</dd>
<dt><code>pageinit</code></dt>
<dd>
<p>Triggered on the page being initialized, after initialization occurs. We recommend binding to this event instead of DOM ready() because this will work regardless of whether the page is loaded directly or if the content is pulled into another page as part of the Ajax navigation system.</p>
<pre><code>
$( '#aboutPage' ).live( 'pageinit',function(event){
alert( 'This page was just enhanced by jQuery Mobile!' );
});
</code></pre>
</dd>
</dl>
<h2>Page remove events</h2>
<p>By default, the framework removes any non active dynamically loaded external pages from the DOM as soon as the user navigates away to a different page. The <code>pageremove</code> event is dispatched just before the framework attempts to remove the page from the DOM.</p>
<dl>
<dt><code>pageremove</code></dt>
<dd>This event is triggered just before the framework attempts to remove an external page from the DOM. Event callbacks can call preventDefault on the event object to prevent the page from being removed.
</dd>
</dl>
<h2>Layout events</h2>
<p>Some components within the framework, such as collapsible and listview search, dynamically hide and show content based on user events. This hiding/showing of content affects the size of the page and may result in the browser adjusting/scrolling the viewport to accommodate the new page size. Since this has the potential to affect other components such as fixed headers and footers, components like collapsible and listview trigger a custom <code>updatelayout</code> event to notify other components that they may need to adjust their layouts in response to their content changes. Developers who are building dynamic applications that inject, hide, or remove content from the page, or manipulate it in any way that affects the dimensions of the page, can also manually trigger this <code>updatelayout</code> event to ensure components on the page update in response to the changes.</p>
<dl>
<dt><code>updatelayout</code></dt>
<dd>This event is triggered by components within the framework that dynamically show/hide content, and is meant as a generic mechanism to notify other components that they may need to update their size or position. Within the framework, this event is fired on the component element whose content was shown/hidden, and bubbles all the way up to the document element.
<pre><code>
$( '#foo' ).hide().trigger( 'updatelayout' );
</code></pre>
</dd>
</dl>
<h2>Animation Events</h2>
<p>jQuery Mobile exposes the <code>animationComplete</code> plugin, which you can utilize after adding or removing a class that applies a CSS transition. It can be used with page transition events. For example:</p>
<pre><code>
$(document).bind("pagehide", function(event, ui) {
$(ui.nextPage).animationComplete(function() {
alert('Animation completed');
});
});
</pre></code>
</div><!--/content-secondary -->
<div class="content-secondary">
<div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
<h3>More in this section</h3>
<ul data-role="listview" data-theme="c" data-dividertheme="d">
<li data-role="list-divider">API</li>
<li><a href="../../docs/api/globalconfig.html">Configuring defaults</a></li>
<li data-theme="a"><a href="../../docs/api/events.html">Events</a></li>
<li><a href="../../docs/api/methods.html">Methods & Utilities</a></li>
<li><a href="../../docs/api/data-attributes.html">Data attribute reference</a></li>
<li><a href="../../docs/api/themes.html">Theme framework</a></li>
</ul>
</div>
</div>
</div><!-- /content -->
<div data-role="footer" class="footer-docs" data-theme="c">
<p class="jqm-version"></p>
<p>© 2012 jQuery Foundation and other contributors</p>
</div>
</div><!-- /page -->
</body>
</html>
|
