From d7aadf01b37dd6d04dc5cfd3a08a4e96601346b8 Mon Sep 17 00:00:00 2001 From: Robert Hurst Date: Wed, 8 Feb 2012 11:02:59 -0800 Subject: [PATCH] - Removed the examples from the readme and better fleshed out the documentation + Added a basic routing example app. --- examples/basic routes/app.js | 43 +++++++++ examples/basic routes/index.html | 21 +++++ examples/basic routes/style.css | 16 ++++ origin.js | 4 +- readme.md | 147 ++++++++++--------------------- 5 files changed, 128 insertions(+), 103 deletions(-) create mode 100644 examples/basic routes/app.js create mode 100644 examples/basic routes/index.html create mode 100644 examples/basic routes/style.css diff --git a/examples/basic routes/app.js b/examples/basic routes/app.js new file mode 100644 index 0000000..06bff90 --- /dev/null +++ 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 = '

Home

This is an example of OriginJS routing. You may use it to learn how to effectivley use the library.

OriginJS is avalible on GitHub

'; + }); + + //about route + OriginJS.bind('/about', function() { + + //load the about content + page.innerHTML = '

About

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.

'; + }); + + //contact route + OriginJS.bind('/contact', function() { + + //load the contact content + page.innerHTML = '

Contact

If you find any issues or you have a request regarding OriginJS please post an issue on the issue tracker.

'; + }); + + //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 new file mode 100644 index 0000000..9fd46f6 --- /dev/null +++ b/examples/basic routes/index.html @@ -0,0 +1,21 @@ + + + + + Basic Routes Example App + + + + + + + +

Basic Routes Example App

+ +
+ +
+ + \ No newline at end of file diff --git a/examples/basic routes/style.css b/examples/basic routes/style.css new file mode 100644 index 0000000..b5af335 --- /dev/null +++ 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; +} \ No newline at end of file diff --git a/origin.js b/origin.js index cfab5ba..9ce8f70 100644 --- 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 index 94e9ca9..b9fa888 100644 --- a/readme.md +++ b/readme.md @@ -4,94 +4,14 @@ 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. - - - -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 ============= @@ -99,32 +19,47 @@ 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 =======