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

clarified some of the points on scripting pages

Browse source
This commit is contained in:
scottjehl 2011-10-07 10:58:34 -04:00
parent da2352a7ad
commit dc90ef39f6
1 changed files with 22 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
docs/pages/page-scripting.html
View file

@ -22,27 +22,39 @@
<div data-role="content">
<div class="content-primary">
<p>Since jQuery Mobile uses an Ajax-powered navigation system, there are a few helpful things to know when writing scripts that interact with the page and navigation model. 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>
<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>
<h2>Scripts & styles in the head</h2>
<h2>Scripts &amp; styles in the head</h2>
<p>When you click a link in jQuery Mobile, the Ajax navigation system uses the link's href to formulate an Ajax request. Although the full page is loaded with Ajax, the framework only pulls in the <em>contents of the page</em>, and ignores anything in the <code>head</code> except for title tag contents.</p>
<p> This means that any scripts or styles in the <code>head</code> of the page won't have any effect <em>when the page is loaded via Ajax</em>. The same page will work as expected if you were to load a page directly but both scenarios need to be considered. The reason that the <code>head</code> is ignored for Ajax page content: it's just too complex. The framework would need to compare and reconcile the contents of multiple page <code>head</code> elements as they are loaded into the DOM so we leave this task to the developer.</p>
<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 href to formulate an Ajax request (instead of allowing the browser's default link behavior of requesting that href 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>
<p>The simplest approach is to add the same set of stylesheets and scripts into all your pages. If you need to load in specific scripts or styles for a particular page, bind to the <code>pagecreate</code> event (details below) to run the necessary code when a specific page ID is created. Following this approach will ensure that the code executes if the page is loaded directly or is pulled in and shown via Ajax.</p>
<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>
<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>
<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>
<h2>pagecreate = DOM ready</h2>
<p>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 by the Ajax navigation system, you must bind to the <a href="../api/events.html"><code>pagecreate</code></a> event. </p>
<p>The <code>pagecreate</code> event is triggered on the page being initialized, right 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>
<p>One of the first things people learn in jQuery is to use the $(document).ready() 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>
<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>
<pre><code>
$('#aboutPage').live('pagecreate',function(event){
alert('This page was just enhanced by jQuery Mobile!');
$( document ).delegate( "pagecreate", "#aboutPage", function() {
alert('A page with an ID of "aboutPage" was just created by jQuery Mobile!');
});
</code></pre>
<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>
<pre><code>
$( document ).delegate( "pagebeforecreate", "#aboutPage", function() {
alert('A page with an ID of "aboutPage" is about to be created by jQuery Mobile!');
});
</code></pre>
<h2>Changing pages</h2>
<p>If you need to change the current page with JavaScript, 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>
<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>
<pre><code>
<strong>//transition to the "about us" page with a slideup transition</strong>
$.mobile.changePage( "about/us.html", { transition: "slideup"} );