Merge pull request #19 from robertbosse/master

agcolom · agcolom · commit c5f7f8e2a62c · 2012-10-15T10:36:00.000-07:00
Api docs: hashchange event documentation
diff --git a/entries/hashtag.xml b/entries/hashtag.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0"?>
+<entry name="hashtag" 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"/>
+	</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>
+	<example>
+		<desc>Click, and watch as the magic happens!</desc>
+		<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>
+		<html><![CDATA[
+			<style>
+				#nav {
+				  font-size: 200%;
+				}
+
+				#nav a {
+				  color: #777;
+				  border: 2px solid #777;
+				  background-color: #ccc;
+				  padding: 0.2em 0.6em;
+				  text-decoration: none;
+				  float: left;
+				  margin-right: 0.3em;
+				}
+
+				#nav a:hover {
+				  color: #999;
+				  border-color: #999;
+				  background: #eee; 
+				}
+
+				#nav a.selected,
+				#nav a.selected:hover {
+				  color: #0a0;
+				  border-color: #0a0;
+				  background: #afa; 
+				}		
+			</style>
+
+			<p id="nav">
+				<a href="#test1">test 1</a>
+				<a href="#test2">test 2</a>
+				<a href="#test3">test 3</a>
+				<a href="#test4">test 4</a>
+			</p>
+    	]]></html>
+	</example>
+	<category slug="events"/>
+</entry>
