- Removed the examples from the readme and better fleshed out the doc…

…umentation + Added a basic routing example app.
RobertWHurst · Feb 8, 2012 · d7aadf0 · d7aadf0
1 parent 291c607
commit d7aadf0
Show file tree

Hide file tree

Showing 5 changed files with 128 additions and 103 deletions.
diff --git a/examples/basic routes/app.js b/examples/basic routes/app.js
@@ -0,0 +1,43 @@
+/*
+BASIC ROUTES EXAMPLE
+
+This file should give you an idea of how to get started
+ */
+
+bind('load', window, function() {
+
+	//get the page div
+	var page = document.getElementById('page');
+
+	//setup the routes
+
+	//home route
+	OriginJS.bind('/', function() {
+
+		//load the home content
+		page.innerHTML = '<h2>Home</h2><p>This is an example of OriginJS routing. You may use it to learn how to effectivley use the library.</p><p>OriginJS is avalible on <a href="http://github.com/RobertWHurst/OriginJS" target="_blank">GitHub</a></p>';
+	});
+
+	//about route
+	OriginJS.bind('/about', function() {
+
+		//load the about content
+		page.innerHTML = '<h2>About</h2><p>OriginJS is am awesome clent slide router. It\'s lightweight, easy to use, and has a lot of very powerful features. If your building a single page application, and javascript game, or anything else heavy in javascript, OriginJS will make your application more accessable and might even help you code in a more organized way.</p>';
+	});
+
+	//contact route
+	OriginJS.bind('/contact', function() {
+
+		//load the contact content
+		page.innerHTML = '<h2>Contact</h2><p>If you find any issues or you have a request regarding OriginJS please post an issue on the <a href="http://github.com/RobertWHurst/OriginJS/issues" target="_blank">issue tracker</a>.</p>';
+	});
+
+	//load the current route
+	OriginJS.update();
+
+});
+
+
+//DO NOT USE IN YOUR PROJECT!
+//This is pollyfill for binding to the load event in ms's old browsers (not needed for oigin)
+function bind(eventName, element, callback) {if(element.addEventListener){element.addEventListener(eventName,callback,false);}else{element.attachEvent("on"+eventName,function(event){return callback.call(element,event);});}}
diff --git a/examples/basic routes/index.html b/examples/basic routes/index.html
@@ -0,0 +1,21 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+<head>
+	<meta charset="UTF-8">
+	<title>Basic Routes Example App</title>
+
+	<link rel="stylesheet" href="style.css">
+
+	<script src="../../origin.js"></script>
+	<script src="app.js"></script>
+</head>
+<body>
+	<h1>Basic Routes Example App</h1>
+	<nav>
+		<a href="#/">Home</a><a href="#/about">About</a><a href="#/contact">Contact</a>
+	</nav>
+	<div id="page">
+
+	</div>
+</body>
+</html>
diff --git a/examples/basic routes/style.css b/examples/basic routes/style.css
@@ -0,0 +1,16 @@
+body {
+	font-family: Helvetica, Arial, sans-serif;
+	font-size: 16px;
+	padding: 40px;
+}
+h1 {
+	text-align: center;
+}
+#page,
+nav {
+	width: 720px;
+	margin: 0 auto;
+}
+nav a {
+	margin-right: 10px;
+}
diff --git a/origin.js b/origin.js
@@ -20,9 +20,7 @@
 	var routes = [],
 		lastRouteData = false,
 		inReset = false,
-		pointers;
-
-	pointers = [];
+		pointers = [];
 
 	//bind to the has change event
 	bind('hashchange', window, handleCurrentRoute);

diff --git a/readme.md b/readme.md
@@ -4,127 +4,62 @@ Every route begins with an origin.
 
 Introduction
 ============
-OriginJS is a very flexible and powerful router that's easy to use but still offers advanced features if and when
-needed. Features like dynamic redirect and alias pointers, group binding, and scored route matching.
+OriginJS is am awesome clent slide router. It's lightweight, easy to use, and has a lot of very powerful features.
+If your building a single page application, and javascript game, or anything else heavy in javascript, OriginJS will
+make your application more accessable and might even help you code in a more organized way.
 
-Getting Started
-===============
-
-First include origin.js in your page. You can do this with a script tag in the head of your page, or you can 
-load it with [require.js](http://requirejs.org/).
-
-Using Origin is very easy. Here's a very basic example.
-
-	OriginJS.bind('/', function() {
-
-		//home page logic goes here
-		//loaded on /#/ or /
-
-	});
-
-	OriginJS.bind('/about', function() {
-
-		//about page logic goes here
-		//loaded on /#/about
-
-	});
-
-	//instruct the router to try and find then follow a route now that routes above have been added
-	OriginJS.update()
-
-Your links would look like this.
-
-	<nav>
-		<a href="#/">Home</a>
-		<a href="#/about">About</a>
-	</nav>
-
-This is far to simple an example for serious applications though so here is an example with a bit more complexity.
-
-	OriginJS.bind(['/:user/:profilePage', '/:user/:profilePage/+'], function(uris, data) {
-
-		//will match hash urls such as
-		// /#/RobertWHurst/Wall/
-		// or even
-		// /#/John_01/About/Data/1/0/1
-
-		//get the dynamic data
-		var user = data.user,
-			profilePage = data.profilePage,
-			profilePageSubUris = uris.splice(2);
-
-		// load profile code here
-
-	}, function(uris, data) {
-
-		//cleanup code for profile here
-
-	});
-
-As you can see there is an optional callback for cleaning up when a different route is loaded. Also both callbacks get two
-arguments. The first is an array with each uri from the current url in the location hash. Even more interesting is the
-`:user` and `:profilePage` uris in the bind rules. These are id uris and capture any uri in the corresponding position
-in the hash url. The uri value gets added to the data object passed to the callback under a key by the same name as the
-rule uri. Here's an example of what I mean.
-
-    Rule Uri = :user
-                                     so                 data.user === 'RobertWHurst'
-    Hash Uri = RobertWHurst
-
-There there are two other operators you can use in your routes. The catchall, `+`, and the wild card uri, `*`. Catchalls
-are self explanatory they will match any uri and all that follow it. Good for things like 404 or black hole pages.
-Wildcards match like id Uris except the do not save the hash uri value to the data array.
-
-Don't use location.hash to change routes!
-=========================================
-You don't always want to use anchor tags to navigate your app. Sometimes you want to do this programatically. You can use
-location.hash if you really want to, it will work but you shouldn't. Origin has a method for redirecting to other places.
-Its called `OriginJS.go` and can be uses as follows.
-
-	//If a route has been set for /home this will redirect to /#/home/. if no route exists it will redirect /home/
-    OriginJS.go('/home');
-
-    //Opens a new tab (or window) containing http://google.com/
-    OriginJS.go('http://google.com/');
-
-    //holding control while ether of these fire will yield a new tab (or window) regardless of the passed url.
-
-As you can see above `OriginJS.go(url)` Allows to to load any page you like, not just hash routes. You don't even have to think
-about it. Its predictable and yet feels magical. The choice is yours but I would highly recommend `OriginJS.go(url)` over
-`location.hash`.
+Examples
+========
+If your looking for examples and a bit more detail you should checkout the [OriginJS homepage (incomplete)](robertwhurst.github.com/OriginJS).
+You some also have a look at the example applications in the examples directory.
 
 Documentation
 =============
 
 Bind
 ----
 
-    OriginJS.bind(route, setupCallback[, tearDownCallback]);
-
-This method is the corner stone of this library. It binds your route logic to the routes of your application.
+    OriginJS.bind(route, setupCallback(urisArray, previousUrisArray)[, tearDownCallback(urisArray, previousUrisArray)]);
 
+This method is the corner stone of this library. It binds your route logic to the routes of your application. To bind a
+route you simply call `OriginJS.bind()` passing it a route (like /home, /about, etc...), and a setup callback that will
+load the content of your route. You can optionally pass a teardown callback aswell if you wish to cleanup your loaded
+content when a different route is followed. You can think of `setupCallback()` and `tearDownCallback()` as parellels to the
+DOM's `onload` and `onunload` events.
 
 ### Arguments
 
-`route`: The route you wish to bind. The route can contain dynamic uris such as `*`, `+`, or `:someIdHere`. see `dynamic
-uris` for more details.
-`setupCallback`: Should be a function containing logic for constructing the content for the route.
-`tearDownCallback`: Should be a function containing logic for removing the content for the route. This is optional.
+- `route`: A route string or an array of route strings. The route can contain dynamic uris such as `*`, `+`, or `:someIdHere`.
+- `setupCallback`: A function or array of functions that will be called when the route is followed.
+- `tearDownCallback`: Optional. A function or array of functions that will be called when the navigating way from the route.
+
+Both the `setupCallback()` and the `tearDownCallback()` are passed two arguments; A uris array for the current route,
+and a uris array from the route followed prior to the current.
+
+### Uris Arrays
+Uris arrays contain each uri from the triggering hash url. So if your route is binded to `/home/*` and someone navigated
+to `/home/cake` the uri array would be `['home', 'cake']`.
+
+### Special Route Uris
 
-Both the `setupCallback` and the `tearDownCallback` are passed two arguments; A uris array object for the current route,
-and a uris array from the route prior to the current. See uris array for details.
+- `*`: Wildcard uris will match any uri.
+- `:[name]`: Dynamic uris are a colon followed by a key name. Examples `:key`, `:user`, `:cake`. Dynaimc uris will capture
+the value of the uri they match and attach it the the uris array as a keyed value. `:key` becomes `urisArray.key`,
+`:user` becomes `urisArray.user`, `:cake` becomes `urisArray.cake`.
+- `+`: Catchall uris will match any uri and anything that follows it. It can be used to setup things like 404 pages and
+other types of catchall pages.
 
 Go
 --
 
 	OriginJS.go(url);
 
-At some point you may want to trigger routes or open other pages programatically. This is what `OriginJS.go(url)` is for.
-If `OriginJS.bind` is ying, `OriginJS.go` is yang.
+At some point you may want to trigger routes or open other pages programatically. This is what `OriginJS.go()` is for.
+If `OriginJS.bind()` is ying, `OriginJS.go()` is yang.
 
 ### Arguments
 
-`url`: Any url you wish to follow. If the url is pointing to a binded route the router will load that route. No need to
+- `url`: Any url you wish to follow. If the url is pointing to a binded route the router will load that route. No need to
 prefix with `/#`. If the url is not pointing to a binded route it will redirect to the url. If the url contains a domain
 it will open the url in a new tab (or window).
 
@@ -133,9 +68,21 @@ Update
 
 	OriginJS.update();
 
-The `OriginJS.update` method is used to trigger force Origin to match the current hash url routes are defined. You should
+The `OriginJS.update()` method is used to trigger force Origin to match the current hash url routes are defined. You should
 call this after your routes are binded in your appication. You should only need to to call this function once.
 
+Point
+-----
+
+	OriginJS.point(route[, ...]).to(route)
+	OriginJS.point(route[, ...]).at(route)
+
+At some point you may want to setup aliases or redirects. `OriginJS.point()` creates aliases and redrects with ease. It
+takes any number route strings. and returns an object with two functions. These functions are `at()` and `to()`.
+
+- `at(route)`: Creates an alias from the routes passed to `point()` and points them to a `route` passed.
+- `to(route)`: Creates a redirect from the routes passed to `point()` and forwards them to a `route` passed.
+
 Credits
 =======