Permalink
Browse files

update docs to reflect pagecreate -> pageinit migration with examples…

… of when to use either
  • Loading branch information...
1 parent c613544 commit 265ffb68e4897d74135d8fe0d39c00fccb0283fb @johnbender johnbender committed Sep 16, 2011
Showing with 78 additions and 60 deletions.
  1. +78 −60 docs/api/events.html
View
@@ -1,17 +1,17 @@
-<!DOCTYPE html>
-<html>
+<!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="../../themes/default/" />
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>jQuery Mobile Docs - Events</title>
+ <link rel="stylesheet" href="../../themes/default/" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="../../js/jquery.js"></script>
<script src="../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
<script src="../_assets/js/jqm-docs.js"></script>
<script src="../../js/"></script>
-</head>
-<body>
+</head>
+<body>
<div data-role="page" class="type-interior">
@@ -24,19 +24,27 @@
<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 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>
-
+ <h4 style="margin:.5em 0">Important: Use pageInit(), 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>pageinit</strong></code> event. This event is explained in detail at the bottom of this page.</div>
+
+ <p>
+ <div class="ui-body ui-body-e">
+ <h4 style="margin:.5em 0">Important: pageCreate() vs pageInit()</h4>
+ Prior to Beta 2 the recommendation to users wishing to manipulate jQuery Mobile enhanced page and child widget markup was to bind to the <code><strong>pagecreate</strong></code> event. In Beta 2 an internal change was made to decouple each of the widgets by binding to the <code><strong>pagecreate</strong></code> event in place of direct calls to the widget methods. As a result, users binding to the <code><strong>pagecreate</strong></code> in <code><strong>mobileinit</code></strong> 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><strong>pageinit</code></strong> event provides the correct timing for post enhancement manipulation of the DOM and/or Javascript objects.
+
+ In short, if you were previously using <code><strong>pagecreate</code></strong> to manipulate the enhanced markup before the page was shown its very likely you'll want to migrate to 'pageinit'.
+ </div></p>
+
<h2>Touch events</h2>
<dl>
<dt><code>tap</code></dt>
<dd>Triggers after a quick, complete touch event.</dd>
-
+
<dt><code>taphold</code></dt>
<dd>Triggers after a held complete touch event (close to one second).</dd>
-
+
<dt><code>swipe</code></dt>
<dd><p>Triggers when a horizontal drag of 30px or more (and less than 20px vertically) occurs within 1 second duration but these can be configured:</p>
<ul>
@@ -46,10 +54,10 @@ <h4 style="margin:.5em 0">Important: Use pageCreate(), not $(document).ready()</
<li><code>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>
@@ -58,7 +66,7 @@ <h4 style="margin:.5em 0">Important: Use pageCreate(), not $(document).ready()</
<dt><code>orientationchange</code></dt>
<dd>Triggers when a device orientation changes (by turning it vertically or horizontally). When bound to this event, your callback function can leverage a second argument, which contains an <code>orientation</code> property equal to either "portrait" or "landscape". These values are also added as classes to the HTML element, allowing you to leverage them in your CSS selectors. Note that we currently bind to the resize event when orientationChange is not natively supported.</dd>
</dl>
-
+
<h2>Scroll events</h2>
<dl>
<dt><code>scrollstart</code></dt>
@@ -67,128 +75,138 @@ <h4 style="margin:.5em 0">Important: Use pageCreate(), not $(document).ready()</
<dl>
<dt><code>scrollstop</code></dt>
<dd>Triggers when a scroll finishes.</dd>
- </dl>
-
+ </dl>
+
<h2>Page show/hide events</h2>
<p>Whenever a page is shown or hidden in jQuery Mobile, two events are triggered on that page. The events triggered depend on whether that page is being shown or hidden, so when a page transition occurs, there are actually 4 events triggered: 2 for each page. </p>
<dl>
<dt><code>pagebeforeshow</code></dt>
<dd>Triggered on the page being shown, before its transition begins.</dd>
-
+
<dt><code>pagebeforehide</code></dt>
<dd>Triggered on the page being hidden, before its transition begins.</dd>
-
+
<dt><code>pageshow</code></dt>
<dd>Triggered on the page being shown, after its transition completes.</dd>
-
+
<dt><code>pagehide</code></dt>
<dd>Triggered on the page being hidden, after its transition completes.</dd>
-
+
</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>
-$('div').live('pageshow',function(event, ui){
- alert('This page was just hidden: '+ ui.prevPage);
+$( '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);
+$( '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 intialization behavior and prevent the auto-initializations from occuring. 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>
-
+
+ <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 intialization behavior and prevent the auto-initializations from occuring. 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!');
+$( '#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){
+$( '#aboutPage' ).live( 'pagebeforecreate',function(event){
// manipulate this page before its widgets are auto-initialized
});
-</code></pre>
+</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('pagecreate',function(event){
- alert('This page was just enhanced by jQuery Mobile!');
+$( '#aboutPage' ).live( 'pageinit',function(event){
+ alert( 'This page was just enhanced by jQuery Mobile!' );
});
</code></pre>
</dd>
</dl>
-
-
+
+
<h2>Virtual mouse events</h2>
<p>We provide a set of "virtual" click events that normalize 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. This still retains the order of event firing in the traditional mouse environment, should multiple handlers be registered on the same element for different events.</p>
<dl>
<dt><code>vmouseover</code></dt>
<dd>Normalized event for handling touch or mouse <code>mouseover</code> events</dd>
-
+
<dt><code>vmousedown</code></dt>
<dd>Normalized event for handling touch or mouse <code>mousedown</code> events</dd>
-
+
<dt><code>vmousemove</code></dt>
<dd>Normalized event for handling touch or mouse <code>mousemove</code> events</dd>
-
+
<dt><code>vmouseup</code></dt>
<dd>Normalized event for handling touch or mouse <code>mouseup</code> events</dd>
-
+
<dt><code>vclick</code></dt>
<dd>Normalized event for handling touch or mouse <code>click</code> events</dd>
-
+
<dt><code>vmousecancel</code></dt>
<dd>Normalized event for handling touch or mouse <code>mousecancel</code> events</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.</p>
- </div><!--/content-secondary -->
-
+ </div><!--/content-secondary -->
+
<div class="content-secondary">
-
+
<div data-role="collapsible" data-collapsed="true" data-theme="b">
-
+
<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 &amp; Utilities</a></li>
- <li><a href="../../docs/api/mediahelpers.html">Responsive Layout</a></li>
+ <li><a href="../../docs/api/mediahelpers.html">Responsive Layout</a></li>
<li><a href="../../docs/api/themes.html">Theme framework</a></li>
-
+
</ul>
</div>
- </div>
+ </div>
</div><!-- /content -->
<div data-role="footer" class="footer-docs" data-theme="c">
<p>&copy; 2011 The jQuery Project</p>
</div>
-
+
</div><!-- /page -->
</body>
-</html>
+</html>

0 comments on commit 265ffb6

Please sign in to comment.