Hopiu/jquery-mobile
1
0
Fork 0
mirror of https://github.com/Hopiu/jquery-mobile.git synced 2026-05-15 10:03:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added clearer messaging about dom ready and how to use pagecreate instead.

Browse source
This commit is contained in:
toddparker 2011-07-28 16:26:34 -04:00
parent 91dfba1d0a
commit aac698520e
1 changed files with 25 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

53
docs/api/events.html
View file

@ -25,6 +25,10 @@
<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 pageCreate(), not $(document).ready()</h4>
The first thing you learn in jQuery is to call code inside the $(document).ready() 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><strong>pagecreate</strong></code> event. This event is explained in detail at the bottom of this page.</div>
<h2>Touch events</h2>
<dl>
<dt><code>tap</code></dt>
@ -76,8 +80,7 @@
</dl>
<p>Note that all four of these events expose a reference to either the next page (<code>nextPage</code>) or previous page (<code>prevPage</code>), depending on whether the page is being shown or hidden, and whether that next or previous page exists (the first ever page shown does not have a previous page to reference, but an empty jQuery object is provided just the same). You can access this reference via the second argument of a bound callback function. For example: </p>
<pre>
<code>
<pre><code>
$('div').live('pageshow',function(event, ui){
alert('This page was just hidden: '+ ui.prevPage);
});
@ -85,8 +88,7 @@ $('div').live('pageshow',function(event, ui){
$('div').live('pagehide',function(event, ui){
alert('This page was just shown: '+ ui.nextPage);
});
</code>
</pre>
</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>
@ -96,39 +98,34 @@ $('div').live('pagehide',function(event, ui){
<dl>
<dt><code>pagebeforecreate</code></dt>
<dd>Triggered on the page being initialized, before initialization occurs.</dd>
<dt><code>pagecreate</code></dt>
<dd>Triggered on the page being initialized, after initialization occurs.</dd>
</dl>
<pre>
<code>
<dd>
<p>Triggered on the page being initialized, before initialization occurs.</p>
<pre><code>
$('#aboutPage').live('pagebeforecreate',function(event){
alert('This page was just inserted into the dom!');
});
$('#aboutPage').live('pagecreate',function(event){
alert('This page was just enhanced by jQuery Mobile!');
});
</code>
</pre>
</code></pre>
<p>Note that by binding to <code>pagebeforecreate</code> and returning <code>false</code>, you can prevent the page plugin from making its manipulations.</p>
<p>Note that by binding to <code>pagebeforecreate</code> and returning <code>false</code>, you can prevent the page plugin from making its manipulations.</p>
<pre>
<code>
<pre><code>
$('#aboutPage').live('pagebeforecreate',function(event){
//run your own enhancement scripting here...
return false;
});
</code></pre>
</dd>
<dt><code>pagecreate</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('pagecreate',function(event){
alert('This page was just enhanced by jQuery Mobile!');
});
</code></pre>
</dd>
</dl>
</code>
</pre>
<div class="ui-body ui-body-e">
<p><strong>Note on Page IDs in Alpha 2 release (<em>no longer an issue</em>): </strong> In jQuery Mobile Alpha 2 and older, page elements utilized the <code>ID</code> attribute for storing the location from which they came. When you place an <code>ID</code> attribute on a page that is brought into jQuery Mobile's single-page environment through Ajax, jQuery Mobile wraps that page with a new "page" <code>div</code> element, preserving any CSS references to your <code>ID</code>. However, this means that your <code>ID</code> attribute is no longer on the "page" element, so you must keep this in mind when binding to page events (<code>pagebeforecreate</code>, <code>pagecreate</code>, etc). To avoid issues, try using a class if possible. </p>
</div>
<h2>Animation Events</h2>