libs/js/jquery-mobile-1.0.1pre/docs/pages/page-scripting.html

   1 <!DOCTYPE html>
   2 <html>
   3         <head>
   4         <meta charset="utf-8">
   5         <meta name="viewport" content="width=device-width, initial-scale=1">
   6         <title>jQuery Mobile Docs - Scripting pages</title>
   7         <link rel="stylesheet"  href="../../css/themes/default/" />
   8         <link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
   9         <script src="../../js/jquery.js"></script>
  10         <script src="../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
  11         <script src="../_assets/js/jqm-docs.js"></script>
  12         <script src="../../js/"></script>
  13 </head>
  14 <body>
  15
  16         <div data-role="page" class="type-interior">
  17
  18                 <div data-role="header" data-theme="f">
  19                 <h1>Scripting pages</h1>
  20                 <a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
  21         </div><!-- /header -->
  22
  23         <div data-role="content">
  24                 <div class="content-primary">
  25                         <p>Since jQuery Mobile uses an Ajax-powered navigation system, there are a few helpful things to know when writing scripts that manipulate your content. You can explore the mobile API in more detail by reading up on <a href="../api/globalconfig.html">global configuration options</a>, <a href="../api/events.html">events</a>, and <a href="../api/methods.html">methods</a> or dig into the technical details of the <a href="page-navmodel.html">Ajax navigation model</a>.</p>
  26
  27                         <h2>Scripts &amp; styles in the head</h2>
  28
  29                         <p>When the user clicks a link in a jQuery Mobile-driven site, the default behavior of the navigation system is to use that link's <code>href</code> to formulate an Ajax request (instead of allowing the browser's default link behavior of requesting that <code>href</code> with full page load). When that Ajax request goes out, the framework will receive its entire text content, but it will only inject the <em>contents of the response's <code>body</code> element (or more specifically the <code>data-role="page"</code> element, if it's provided)</em>, meaning nothing in the <code>head</code> of the page will be used (with the exception of the page title, which is fetched specifically).</p>
  30
  31                         <p> This means that any scripts and styles referenced the <code>head</code> of a page won't have any effect <em>when a page is loaded via Ajax</em>, but they <strong>will execute if the page is requested normally via HTTP</strong>. When scripting jQuery Mobile sites, both scenarios need to be considered. The reason that the <code>head</code> of a page is ignored when requested via Ajax is that the potential of re-executing the same JavaScript is very high (it's common to reference the same scripts in every page of a site). Due to the complexity of attempting to work around that issue, we leave the task of executing page-specific scripts to the developer, and assume <code>head</code> scripts are only expected to execute once per browsing session.</p>
  32
  33                         <p>The simplest approach when building a jQuery Mobile site is to reference the same set of stylesheets and scripts in the head of every page. If you need to load in specific scripts or styles for a particular page, we recommend binding logic to the <code>pagecreate</code> event (details below) to run  necessary code when a specific page is created (which can be determined by its <code>id</code> attribute, or a number of other ways). Following this approach will ensure that the code executes if the page is loaded directly or is pulled in and shown via Ajax.</p>
  34
  35                         <p>Another approach for page-specific scripting would be to include scripts at the end of the <code>body</code> element. If you include your custom scripting this way, be aware that these scripts will execute when that page is loaded via Ajax or regular HTTP, so if these scripts are the same on every page, you'll likely run into problems. If you're including scripts this way, we'd recommend enclosing your page content in a <code>data-role="page"</code> element, and placing scripts that are referenced on every page outside of that element. Scripts that are unique to that page can be placed in that element, to ensure that they execute when the page is fetched via Ajax.</p>
  36
  37                         <h2>pagecreate = DOM ready</h2>
  38
  39                         <p>One of the first things people learn in jQuery is to use the <code>$(document).ready()</code> function for executing DOM-specific code as soon as the DOM is ready (which often occurs long before the <code>onload</code> event). However, in jQuery Mobile site and apps, pages are requested and injected into the same DOM as the user navigates, so the DOM ready event is not as useful, as it only executes for the first page. To execute code whenever a new page is loaded and created in jQuery Mobile, you can bind to the <a href="../api/events.html"><code>pagecreate</code></a> event. </p>
  40
  41                         <p>The <code>pagecreate</code> event is triggered on a page when it is initialized, right after initialization occurs. Most of jQuery Mobile's official widgets auto-initialize themselves based on this event, and you can set up your code to do the same.</p>
  42 <pre><code>
  43 $( document ).delegate("#aboutPage", "pagecreate", function() {
  44   alert('A page with an ID of "aboutPage" was just created by jQuery Mobile!');
  45 });
  46 </code></pre>
  47
  48         <p>If you'd like to manipulate a page's contents <em>before</em> the pagecreate event fires and widgets are auto-initialized, you can instead bind to the <code>pagebeforecreate</code> event:</p>
  49
  50 <pre><code>
  51 $( document ).delegate("#aboutPage", "pagebeforecreate", function() {
  52   alert('A page with an ID of "aboutPage" is about to be created by jQuery Mobile!');
  53 });
  54 </code></pre>
  55
  56                         <h2>Changing pages</h2>
  57                         <p>If you want to change the current active page with JavaScript, you can use the <a href="../api/methods.html"><code>changePage</code></a> method. There are a lot of methods and properties that you can set when changing pages, but here are two simple examples:</p>
  58                         <pre><code>
  59 <strong>//transition to the "about us" page with a slideup transition</strong>
  60 $.mobile.changePage( "about/us.html", { transition: "slideup"} );
  61
  62 <strong>//transition to the "search results" page, using data from a form with an ID of "search""       </strong>
  63 $.mobile.changePage( "searchresults.php", {
  64         type: "post",
  65         data: $("form#search").serialize()
  66 });
  67 </code></pre>
  68
  69                         <h2>Loading pages</h2>
  70                         <p>To load an external page, enhance its content, and insert it into the DOM, use the <a href="../api/methods.html"><code>loadPage</code> method</a>. There are a lot of methods and properties that you can set when loading pages, but here is a simple example:</p>
  71                         <pre><code>
  72 //load the "about us" page into the DOM
  73 $.mobile.loadPage( "about/us.html" );
  74 </code></pre>
  75
  76                         <h2>Enhancing new markup</h2>
  77                         <p>The page plugin dispatches a <code>pagecreate</code> event, which most widgets use to auto-initialize themselves. As long as a widget plugin script is referenced, it will automatically enhance any instances of the widgets it finds on the page.</p>
  78                         <p>However, if you generate new markup client-side or load in content via Ajax and inject it into a page, you can trigger the <code>create</code> event to handle the auto-initialization for all the plugins contained within the new markup. This can be triggered on any element (even the page <code>div</code> itself), saving you the task of manually initializing each plugin (listview button, select, etc.).</p>
  79                         <p>For example, if a block of HTML markup (say a login form) was loaded in through Ajax, trigger the <code>create</code> event to automatically transform all the widgets it contains (<a href="http://jquerymobile.com/test/docs/forms/textinputs/index.html">inputs</a> and <a href="http://jquerymobile.com/test/docs/buttons/index.html">buttons</a> in this case) into the enhanced versions. The code for this scenario would be:</p>
  80 <pre style="margin: 25px 0;"><code style="font-size: 12px;">$( ...new markup that contains widgets... ).appendTo( ".ui-page" ).trigger( "create" );
  81 </code></pre>
  82
  83                         <h2>Create vs. refresh: An important distinction</h2>
  84                         <p>Note that there is an important difference between the <code>create</code> event and <code>refresh</code> method that some widgets have. The <code>create</code> event is suited for enhancing <em>raw markup</em> that contains one or more widgets. The <code>refresh</code> method should be used on existing (already enhanced) widgets that have been manipulated programmatically and need the UI be updated to match.</p>
  85
  86                         <p>For example, if you had a page where you dynamically appended a new unordered list with <code>data-role=listview</code> attribute after page creation, triggering <code>create</code> on a parent element of that list would transform it into a <a href="http://jquerymobile.com/test/docs/lists/index.html">listview</a> styled widget. If more list items were then programmatically added, calling the listview&#8217;s <code>refresh</code> method would update just those new list items to the enhanced state and leave the existing list items untouched.</p>
  87
  88
  89                         <h2>Scrolling to a position within a page</h2>
  90                         <p>Since we use the URL hash to preserve Back button behavior, using page anchors to jump down to a position on the page isn't supported by using the traditional anchor link (#foo). Use the <a href="../api/methods.html"><code>silentScroll</code></a> method to scroll to a particular Y position without triggering scroll event listeners. You can pass in a <code>yPos</code> arguments to scroll to that Y location. For example:</p>
  91 <pre><code>
  92 //scroll to Y 300px
  93 $.mobile.silentScroll(300);
  94 </code></pre>
  95
  96                         <h2>Binding to mouse and touch events</h2>
  97                         <p>One inportant consideration in mobile is handling mouse and touch events. These events differ significantly across mobile platforms, but the common denominator is that click events will work everywhere, but usually after a significant delay of 500-700ms. This delay is necessary for the browser to wait for double tap, scroll and extended hold tap events to potentially occur. To avoid this delay, it's possible to bind to touch events (ex. touchstart) but the issue with this approach is that some mobile platforms (WP7, Blackberry) don't support touch. To compound this issue, some platforms will emit <em>both</em> touch and mouse events so if you bind to both types, duplicate events will be fired for a single interaction.</p>
  98                         <p>Our solution is to create a set of <a href="../api/events.html">virtual events</a> 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. The virtual mouse system exposes the following virtual events to jQuery bind methods: <code>vmouseover</code>, <code>vmousedown</code>, <code>vmousemove</code>, <code>vmouseup</code>, <code>vclick</code>, and <code>vmousecancel</code></p>
  99
 100
 101                         <h2>Passing parameters between pages</h2>
 102                         <p>jQuery Mobile does not support query parameter passing to internal/embedded pages. For example, if the framework sees a link to "#somePage?someId=1" it  interpret that as "#somePage" and navigate to the internal page div with an ID of <code>somePage</code> and apply a data-url of <code>#somePage?someId=1</code> to that page container. Subsequent calls to other params such as "#somePage?someId=2" will find the same div because jQuery Mobile refers to the data-url on the div which is only set once and will remain at <code>#somePage?someId=1</code>.</p>
 103
 104                         <p>There are two plugins that you can add to your project if query parameters are needed between pages. There is a lightweight <a href="https://github.com/jblas/jquery-mobile-plugins/tree/master/page-params" rel="external">page params plugin</a> and a more fully featured <a href="https://github.com/azicchetti/jquerymobile-router" rel="external">jQuery Mobile router plugin</a> for use with backbone.js or spine.js.</p>
 105
 106
 107
 108                                 </div><!--/content-primary -->
 109
 110                                 <div class="content-secondary">
 111
 112                                         <div data-role="collapsible" data-collapsed="true" data-theme="b" data-content-theme="d">
 113
 114                                                         <h3>More in this section</h3>
 115
 116                                                         <ul data-role="listview" data-theme="c" data-dividertheme="d">
 117
 118                                                                 <li data-role="list-divider">Pages &amp; Dialogs</li>
 119                                                                 <li><a href="page-anatomy.html">Anatomy of a page</a></li>
 120                                                                 <li><a href="page-template.html" data-ajax="false">Single page template</a></li>
 121                                                                 <li><a href="multipage-template.html" data-ajax="false">Multi-page template</a></li>
 122                                                                 <li><a href="page-titles.html">Page titles</a></li>
 123                                                                 <li><a href="page-links.html">Linking pages</a></li>
 124                                                                 <li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
 125                                                                 <li><a href="page-dialogs.html">Dialogs</a></li>
 126                                                                 <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
 127                                                                 <li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
 128                                                                 <li><a href="page-dynamic.html">Dynamically injecting pages</a></li>
 129                                                                 <li data-theme="a"><a href="page-scripting.html">Scripting pages</a></li>
 130                                                                 <li><a href="phonegap.html">PhoneGap apps</a></li>
 131                                                                 <li><a href="touchoverflow.html">touchOverflow feature</a></li>
 132                                                                 <li><a href="pages-themes.html">Theming pages</a></li>
 133                                                         </ul>
 134                                         </div>
 135                                 </div>
 136
 137                         </div><!-- /content -->
 138
 139                         <div data-role="footer" class="footer-docs" data-theme="c">
 140                                         <p>&copy; 2011 The jQuery Project</p>
 141                         </div>
 142
 143                         </div><!-- /page -->
 144
 145                         </body>
 146                         </html>