PageRenderTime 49ms CodeModel.GetById 20ms RepoModel.GetById 0ms app.codeStats 0ms

/docs/pages/page-scripting.html

https://github.com/inorganik/jquery-mobile
HTML | 127 lines | 117 code | 10 blank | 0 comment | 0 complexity | cd8d21bbc9a5d3e96112212b63c2258e MD5 | raw file
    

  1. <!DOCTYPE html> 
    2. 

  2. <html> 
    3. 

  3. 	<head>
    4. 

  4. 	<meta charset="utf-8">
    5. 

  5. 	<meta name="viewport" content="width=device-width, initial-scale=1"> 
    6. 

  6. 	<title>jQuery Mobile Docs - Scripting pages</title> 
    7. 

  7. 	<link rel="stylesheet"  href="../../themes/default/" />  
    8. 

  8. 	<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
    9. 

  9. 	<script src="../../js/jquery.js"></script>
    10. 

  10. 	<script src="../../experiments/themeswitcher/jquery.mobile.themeswitcher.js"></script>
    11. 

  11. 	<script src="../_assets/js/jqm-docs.js"></script>
    12. 

  12. 	<script src="../../js/"></script>
    13. 

  13. </head> 
    14. 

  14. <body> 
    15. 

  15. 

  16. 	<div data-role="page" class="type-interior">
    17. 

  17. 

  18. 		<div data-role="header" data-theme="f">
    19. 

  19. 		<h1>Scripting pages</h1>
    20. 

  20. 		<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
    21. 

  21. 	</div><!-- /header -->
    22. 

  22. 

  23. 	<div data-role="content">
    24. 

  24. 		<div class="content-primary">		
    25. 

  25. 			<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> 
    26. 

  26. 			
    27. 

  27. 			<h2>Scripts & styles in the head</h2> 
    28. 

  28. 			
    29. 

  29. 			<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>
    30. 

  30. 			<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>
    31. 

  31. 			
    32. 

  32. 			<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>
    33. 

  33. 			
    34. 

  34. 			<h2>pagecreate = DOM ready</h2> 
    35. 

  35. 

  36. 			<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>
    37. 

  37. 			<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>
    38. 

  38. <pre><code>
    39. 

  39. $('#aboutPage').live('pagecreate',function(event){
    40. 

  40.   alert('This page was just enhanced by jQuery Mobile!');
    41. 

  41. });
    42. 

  42. </code></pre>
    43. 

  43. 

  44. 			<h2>Changing pages</h2> 
    45. 

  45. 			<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>
    46. 

  46. 			<pre><code>
    47. 

  47. <strong>//transition to the "about us" page with a slideup transition</strong> 			
    48. 

  48. $.mobile.changePage( "about/us.html", { transition: "slideup"} );	
    49. 

  49. 

  50. <strong>//transition to the "search results" page, using data from a form with an ID of "search"" 	</strong>	
    51. 

  51. $.mobile.changePage( "searchresults.php", {
    52. 

  52. 	type: "post", 
    53. 

  53. 	data: $("form#search").serialize()
    54. 

  54. });		
    55. 

  55. </code></pre>
    56. 

  56. 

  57. 			<h2>Loading pages</h2> 
    58. 

  58. 			<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>
    59. 

  59. 			<pre><code>
    60. 

  60. //load the "about us" page into the DOM			
    61. 

  61. $.mobile.loadPage( "about/us.html" );	
    62. 

  62. </code></pre>
    63. 

  63. 

  64. 			<h2>Enhancing new markup</h2> 
    65. 

  65. 			<p>The page plugin dispatches a &#8220;pagecreate&#8221; 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>		
    66. 

  66. 			<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 div itself), saving you the task of manually initializing each plugin (listview button, select, etc.).</p> 
    67. 

  67. 			<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/texts/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> 
    68. 

  68. <pre style="margin: 25px 0;"><code style="font-size: 12px;">$( ...new markup that contains widgets... ).appendTo( ".ui-page" ).trigger( "create" );
    69. 

  69. </code></pre> 
    70. 

  70. 

  71. 			<h2>Create vs. refresh: An important distinction</h2> 
    72. 

  72. 			<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> 
    73. 

  73. 

  74. 			<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>
    75. 

  75. 

  76. 

  77. 			<h2>Scrolling to a position within a page</h2> 
    78. 

  78. 			<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>
    79. 

  79. <pre><code>
    80. 

  80. //scroll to Y 300px 			
    81. 

  81. $.mobile.silentScroll(300);	
    82. 

  82. </code></pre>	
    83. 

  83. 		
    84. 

  84. 			<h2>Binding to mouse and touch events</h2> 
    85. 

  85. 			<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>
    86. 

  86. 			<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>
    87. 

  87. 			
    88. 

  88. 

  89. 

  90. 				</div><!--/content-primary -->		
    91. 

  91. 

  92. 				<div class="content-secondary">
    93. 

  93. 

  94. 					<div data-role="collapsible" data-collapsed="true" data-theme="b">
    95. 

  95. 

  96. 							<h3>More in this section</h3>
    97. 

  97. 

  98. 							<ul data-role="listview" data-theme="c" data-dividertheme="d">
    99. 

  99. 

  100. 								<li data-role="list-divider">Pages &amp; Dialogs</li>
    101. 

  101. 								<li><a href="page-anatomy.html">Anatomy of a page</a></li>
    102. 

  102. 								<li><a href="page-template.html" data-ajax="false">Single page template</a></li>
    103. 

  103. 								<li><a href="multipage-template.html" data-ajax="false">Multi-page template</a></li>
    104. 

  104. 								<li><a href="page-titles.html">Page titles</a></li>
    105. 

  105. 								<li><a href="page-links.html">Linking pages</a></li>
    106. 

  106. 								<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
    107. 

  107. 								<li><a href="page-dialogs.html">Dialogs</a></li>
    108. 

  108. 								<li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
    109. 

  109. 								<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
    110. 

  110. 								<li><a href="page-dynamic.html">Dynamically Injecting Pages</a></li>
    111. 

  111. 								<li data-theme="a"><a href="page-scripting.html">Scripting pages</a></li>
    112. 

  112. 								<li><a href="pages-themes.html">Theming pages</a></li>
    113. 

  113. 

  114. 							</ul>
    115. 

  115. 					</div>
    116. 

  116. 				</div>		
    117. 

  117. 

  118. 			</div><!-- /content -->
    119. 

  119. 

  120. 			<div data-role="footer" class="footer-docs" data-theme="c">
    121. 

  121. 					<p>&copy; 2011 The jQuery Project</p>
    122. 

  122. 			</div>
    123. 

  123. 

  124. 			</div><!-- /page -->
    125. 

  125. 

  126. 			</body>
    127. 

  127. 			</html>
    128. 

  128.