Merge remote-tracking branch 'upstream/master'

Author: patrickash

categories.xml

@@ -3,5 +3,11 @@
 	<category name="Widgets" slug="widgets">
 		<desc></desc>
 	</category>
+	<category name="Events" slug="events">
+	<desc></desc>
+	</category>
+	<category name="Miscellaneous" slug="misc">
+	<desc></desc>
+	</category>
 	<category name="All" slug="all"/>
 </categories>

entries/footer.xml

@@ -0,0 +1,67 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
+<entry name="footer" namespace="fn" type="widget" widgetnamespace="mobile">
+	<title>Footer Widget</title>
+    <desc>The <strong>Footer bar</strong> is usually the last element inside each mobile page, and tends to be more freeform than the header in terms of content and functionality, but typically contains a combination of text and buttons.</desc>
+    <longdesc>
+        <h2>Footer bar structure</h2>
+        <p>The <code>footer</code> bar has the same basic structure as the header except it uses the <code> data-role</code> attribute value of <code>footer</code>.</p> 
+
+        <pre>
+            <span class="nt">&lt;div</span> <strong><span class="na">data-role=</span><span class="s">"footer"</span></strong><span class="nt">&gt;</span> 
+            <span class="nt">&lt;h4&gt;</span>Footer content<span class="nt">&lt;/h4&gt;</span> 
+            <span class="nt">&lt;/div&gt;</span> 
+        </pre> 
+
+        <p>The <code>footer</code> toolbar will be themed with the "a" swatch by default (black in the default theme) but you can easily set the theme swatch color.
+        <iframe src="/resources/footer/example1.html" style="width:100%;height:90px;border:0px"></iframe></p> 
+
+        <p>The page footer is very similar to the header in terms of options and configuration. The primary difference is that the footer is designed to be less structured than the header to allow more flexibility, so the framework doesn't automatically reserve slots for buttons to the left or right as it does in headers.</p>
+        <p>Since footers do not have the same prescriptive markup conventions as headers, we recommend using layout grids or writing custom styles to achieve the design you want.</p> 
+
+        <h2>Adding buttons</h2>
+        <p>Any link or valid button markup added to the footer will automatically be turned into a button. To save space, buttons in toolbars are automatically set to inline styling so the button is only as wide as the text and icons it contains.</p>
+        <p>By default, toolbars don't have any padding to accommodate nav bars and other widgets. To include padding on the bar, add a <code>class="ui-bar"</code> to the footer.</p>
+
+
+        <pre><code>
+            &lt;div data-role=&quot;footer&quot; class=&quot;ui-bar&quot;&gt;
+            &lt;a href=&quot;index.html&quot; data-role=&quot;button&quot; data-icon=&quot;plus&quot;&gt;Add&lt;/a&gt;
+            &lt;a href=&quot;index.html&quot; data-role=&quot;button&quot; data-icon=&quot;arrow-u&quot;&gt;Up&lt;/a&gt;
+            &lt;a href=&quot;index.html&quot; data-role=&quot;button&quot; data-icon=&quot;arrow-d&quot;&gt;Down&lt;/a&gt;
+            &lt;/div&gt;
+        </code></pre>
+
+        <p>This creates this toolbar with buttons sitting in a row
+            <iframe src="/resources/footer/example2.html" style="width:100%;height:90px;border:0px"></iframe></p>
+
+        <p>Note that <code>.ui-bar</code> should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap the toolbar's contents in an element and apply the padding to that element.</p>
+
+        <p>To group buttons together into a button set, wrap the links in a wrapper with <code> data-role=&quot;controlgroup&quot;</code> and <code>data-type=&quot;horizontal&quot;</code> attributes.</p>
+
+        <code>&lt;div data-role=&quot;controlgroup&quot; data-type=&quot;horizontal&quot;&gt;</code>
+
+        <p>This creates a grouped set of buttons:
+            <iframe src="/resources/footer/example3.html" style="width:100%;height:90px;border:0px"></iframe></p>
+
+        <h2>Adding form elements</h2>
+        <p>Form elements and other content can also be added to toolbars. Here is an example of a select menu inside a footer bar. We recommend using mini-sized form elements in toolbars by adding the <code>data-mini="true"</code> attribute:
+        <iframe src="/resources/footer/example4.html" style="width:100%;height:90px;border:0px"></iframe></p>
+
+        
+
+        <h2>Fixed &amp; Persistent footers</h2>
+        <p>In situations where the footer is a global navigation element, you may want it to appear fixed so it doesn't scroll out of view. It's also possible to make a fixed toolbar persistent so it appears to not move between page transitions. This can be accomplished by using the persistent footer feature included in jQuery Mobile.</p> 
+        <p>To make a footer persistent between transitions, add the <code>data-id</code> attribute to the footer of all relevant pages and use the same <code>id</code> value for each. For example, by adding <code>data-id="myfooter"</code> to the current page and the target page, the framework will keep the footer anchors in the same spot during the page animation. <strong>This effect will only work correctly if the header and footer toolbars are set to <code>data-position="fixed"</code> so they are in view during the transition.</strong></p>
+    </longdesc>
+	<added>1.0</added>
+	<example>
+		<desc>A basic example of a footer</desc>
+		<code><![CDATA[]]></code>
+		<html><![CDATA[
+		    <div data-role="footer">
+			    <h4>Footer content</h4>
+		    </div> ]]></html>
+	</example>
+	<category slug="widgets"/>
+</entry>

entries/grid-layout.xml

@@ -0,0 +1,120 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
+<entry name="grid-layout" namespace="fn" type="misc" widgetnamespace="mobile">
+	<title>Grid Layout</title>
+    <desc>Multi-column layout grids</desc>
+		<longdesc>
+			<p>Using multiple column layouts isn't generally recommended on a mobile device because of the narrow screen width, but there are times where you may need to place small elements side-by-side (like buttons or navigation tabs, for example).</p>
+			<p>The jQuery Mobile framework provides a simple way to build CSS-based columns through a  block style class convention called <code>ui-grid</code>. </p>
+			<p>There are four preset layouts that can be used in any situation that requires columns:</p>
+			<ul>
+				<li><strong>two</strong>-column (using the <code>ui-grid-a</code> class)</li>
+				<li><strong>three</strong>-column (using the <code>ui-grid-b</code> class)</li>
+				<li><strong>four</strong>-column (using the <code>ui-grid-c</code> class)</li>
+				<li><strong>five</strong>-column (using the <code>ui-grid-d</code> class)</li>
+			</ul>
+			<p>Grids are 100% width, completely invisible (no borders or backgrounds) and don't have padding or margins, so they shouldn't interfere with the styles of elements placed inside them. </p>
+			<p>Within the grid container, child elements are assigned <code>ui-block-a/b/c/d/e</code> in a sequential manner which makes each "block" element float side-by-side, forming the grid. The <code>ui-block-a</code> class essentially clears the floats which will start a new line (see multiple row grids, below).</p>
+
+			<h2>Two column grids</h2>
+
+			<p>To build a two-column (50/50%) layout, start with a container with a <code>class</code> of <code>ui-grid-a</code>, and add two child containers inside it classed with <code>ui-block-a</code> for the first column and <code>ui-block-b</code> for the second:</p>
+
+<pre><code>
+&lt;div class="ui-grid-a"&gt;
+	&lt;div class="ui-block-a"&gt;&lt;strong&gt;I'm Block A&lt;/strong&gt; and text inside will wrap&lt;/div&gt;
+	&lt;div class="ui-block-b"&gt;&lt;strong&gt;I'm Block B&lt;/strong&gt; and text inside will wrap&lt;/div&gt;
+&lt;/div&gt;&lt;!-- /grid-a --&gt;
+</code></pre>
+
+			<p>The above markup produces the following content layout:</p>
+			<iframe src="/resources/grid-layout/example1.html" style="width:100%;height:90px;border:0"></iframe>
+
+			<p>As you see above, by default grid blocks have no visual styling; they simply present content side-by-side.</p>
+			<p>Grid classes can be applied to any container. In this next example, we add <code>ui-grid-a</code> to a <code>fieldset</code>, and apply the <code>ui-block</code> classes to the container of each of the two buttons inside to stretch them each to 50% of the screen width:</p>
+			
+<pre><code>
+&lt;fieldset class="ui-grid-a"&gt;
+	&lt;div class="ui-block-a"&gt;&lt;button type="submit" data-theme="c"&gt;Cancel&lt;/button&gt;&lt;/div&gt;
+	&lt;div class="ui-block-b"&gt;&lt;button type="submit" data-theme="b"&gt;Submit&lt;/button&gt;&lt;/div&gt;	   
+&lt;/fieldset&gt;
+</code></pre>
+
+			<iframe src="/resources/grid-layout/example2.html" style="width:100%;height:90px;border:0"></iframe>
+			<p>Please note that the framework adds left and right margin to buttons in a grid. For a single button you can use a container with class <code>ui-grid-solo</code> and wrap the button in a div with class <code>ui-block-a</code> like the example below. This way the button will get the same margin.</p>
+			
+<pre><code>
+&lt;div class="ui-grid-a"&gt;
+	&lt;div class="ui-block-a"&gt;&lt;button type="button" data-theme="c"&gt;Previous&lt;/button&gt;&lt;/div&gt;
+	&lt;div class="ui-block-b"&gt;&lt;button type="button" data-theme="c"&gt;Next&lt;/button&gt;&lt;/div&gt;	   
+&lt;/div&gt;
+&lt;div class="ui-grid-solo"&gt;
+	&lt;div class="ui-block-a"&gt;&lt;button type="v" data-theme="b"&gt;More&lt;/button&gt;&lt;/div&gt;
+&lt;/div&gt;
+</code></pre>
+
+			<iframe src="/resources/grid-layout/example3.html" style="width:100%;height:130px;border:0"></iframe>
+			
+			<p>Theme classes (not data-theme attributes) from the <a href="../api/themes.html" class="ui-link">theming system</a> can be added to an element, including grids. On the blocks below, we're adding two classes: <code>ui-bar</code> to add the default bar padding and <code>ui-bar-e</code> to apply the background gradient and font styling for the "e" toolbar theme swatch. For illustration purposes, an inline <code>style="height:120px"</code> attribute is also added to each grid to set each to a standard height. </p>
+
+			<iframe src="/resources/grid-layout/example4.html" style="width:100%;height:150px;border:0"></iframe>
+
+			<h3>Three-column grids</h3>
+
+			<p>The other grid layout configuration uses <code>class=ui-grid-b</code> on the parent, and 3 child container elements, each with its respective <code>ui-block-a/b/c</code> class, to create a three-column layout (33/33/33%). Note: These blocks are also styled with theme classes so the grid layout is clearly visible.</p>
+
+<pre><code>
+&lt;div class="ui-grid-b"&gt;
+	&lt;div class="ui-block-a"&gt;Block A&lt;/div&gt;
+	&lt;div class="ui-block-b"&gt;Block B&lt;/div&gt;
+	&lt;div class="ui-block-c"&gt;Block C&lt;/div&gt;
+&lt;/div&gt;&lt;!-- /grid-b --&gt;
+</code></pre>
+
+			<p>This will produce a 33/33/33% grid for our content.</p>
+			<iframe src="/resources/grid-layout/example5.html" style="width:100%;height:150px;border:0"></iframe>
+			
+			<p>And an example of a 3 column grid with buttons inside:</p>
+			<iframe src="/resources/grid-layout/example6.html" style="width:100%;height:90px;border:0"></iframe>
+			
+			<h3>Four-column grids</h3>
+
+			<p>A four-column, 25/25/25/25% grid is created by specifying <code>class=ui-grid-c</code> on the parent and adding a fourth block. Note: These blocks are also styled with theme classes so the grid layout is clearly visible.</p>
+			
+			<iframe src="/resources/grid-layout/example7.html" style="width:100%;height:150px;border:0"></iframe>
+
+			<h2>Five-column grids</h2>
+
+			<p>A five-column, 20/20/20/20/20% grid is created by specifying <code>class=ui-grid-d</code> on the parent and adding a fifth block. Note: These blocks are also styled with theme classes so the grid layout is clearly visible.</p>
+			
+			<iframe src="/resources/grid-layout/example8.html" style="width:100%;height:150px;border:0"></iframe>
+			
+			<h3>Multiple row grids</h3>
+
+			<p>Grids are designed to wrap to multiple rows of items. For example, if you specify a 3-column grid (ui-grid-b) on a container that has nine child blocks, it will wrap to 3 rows of 3 items each. There is a CSS rule to clear the floats and start a new line when the <code>class=ui-block-a</code> is seen so make sure to assign block classes in a repeating sequence (a, b, c, a, b, c, etc.) that maps to the grid type:</p>
+			<iframe src="/resources/grid-layout/example9.html" style="width:100%;height:450px;border:0"></iframe>
+
+			<h3>Grids in toolbars</h3>
+			
+			<p>Grids are helpful for creating layouts within a toolbar. Here's a footer with a 4 column grid.</p>
+			<iframe src="/resources/grid-layout/example10.html" style="width:100%;height:90px;border:0"></iframe>
+			
+		</longdesc>
+	<added>1.0</added>
+	<options>
+	</options>
+	<events>
+	</events>
+	<methods>
+	</methods>
+	<example>
+		<desc>A basic example of grid layout</desc>
+		<code><![CDATA[]]></code>
+		<html><![CDATA[<fieldset class="ui-grid-a">
+		<div class="ui-grid-a">
+			<div class="ui-block-a"><strong>I'm Block A</strong> and text inside will wrap.</div>
+			<div class="ui-block-b"><strong>I'm Block B</strong> and text inside will wrap.</div>
+		</div><!-- /grid-a -->]]></html>
+	</example>
+	<category slug="misc"/>
+</entry>

entries/hashtag.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0"?>
+<entry name="hashchange" type="event" return="jQuery">
+	<title>.hashchange()</title>
+	<desc>Enables bookmarkable #hash history.</desc>
+	<longdesc>
+		<p>The jQuery Mobile <code>.hashchange()</code> event handler enables very basic bookmarkable #hash history by providing a callback function bound to the window.onhashchange event. The onhashchange event fires when a window's hash changes.</p>
+		<p>In browsers that support it, the native HTML5 window.onhashchange event is used. In IE6/7 (and IE8 operating in "IE7 compatibility" mode), a hidden Iframe is created to allow the back button and hash-based history to work.</p>
+		<xi:include href="../includes/core-extension-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
+		<pre>
+		<code><![CDATA[
+			$(function(){
+				// Bind an event to window.onhashchange that, when the hash changes, gets the
+				// hash and adds the class "selected" to any matching nav link.
+				$(window).hashchange( function(){
+				var hash = location.hash;
+
+				// Set the page title based on the hash.
+				document.title = 'The hash is ' + ( hash.replace( /^#/, '' ) || 'blank' ) + '.';
+
+				// Iterate over all nav links, setting the "selected" class as-appropriate.
+				$('#nav a').each(function(){
+					var that = $(this);
+					that[ that.attr( 'href' ) === hash ? 'addClass' : 'removeClass' ]( 'selected' );
+					});
+				})
+				// Since the event is only triggered when the hash changes, we need to trigger
+				// the event now, to handle the hash the page may have loaded with.
+				$(window).hashchange();
+			}); 
+		]]></code>
+	</pre>
+	<p>iFrame source: <span id="hashtagIframeLink">example1.html</span>
+		<iframe id="hashtagIframe" src="/resources/hashchange/example1.html" style="width:100%;height:90px;border:0px"></iframe>
+	</p>
+	</longdesc>
+	<added>1.0</added>
+	<signature>
+		<argument name="callback" type="Function" optional="true">
+			<desc>A function to invoke after the onhashchange event is fired.</desc>
+		</argument>
+	</signature>
+	<category slug="events"/>
+</entry>