Read the documentation for a detailed explanation of available methods and features.
crossroads.addRoute('/news/{id}', function(id){
console.log(id);
});
crossroads.parse('/news/123'); //will match '/news/{id}' route passing 123 as param
Optional segments are very useful since they can drastically reduce the amount of routes required to describe the whole application.
//{id} is required, :date: is optional
crossroads.addRoute('/news/{id}/:date:', function(id, date){
console.log(id +' - '+ date);
});
crossroads.parse('/news/123'); //match route and pass "123" as param
crossroads.parse('/news/45/2011-09-31'); //match route passing "45" and "2011-09-31" as param
Rest segments are useful in cases where you might want to match an arbitrary number of segments.
// {section*} will match multiple segments
crossroads.addRoute('/news/{section*}/{id}', function(section, id){
console.log(section +' - '+ id);
});
//match route and pass "lorem" and "123"
crossroads.parse('/news/lorem/123');
//match route passing "lorem/ipsum/dolor" and "45"
crossroads.parse('/news/lorem/ipsum/dolor/45'); Decode Query String (v0.9.0+)
If a capturing group starts with ? it will be decoded into an object.
crossroads.addRoute('foo.php{?query}', function(query){
console.log(query.lorem +' - '+ query.dolor);
});
// match route passing {lorem:"ipsum", dolor:"amet"}
crossroads.parse('foo.php?lorem=ipsum&dolor=amet');
//capturing groups are passed as parameters to listeners
crossroads.addRoute(/^news\/([0-9]+)$/, function(id){
console.log(id);
});
crossroads.parse('/news/123'); //will match route passing "123" as param
crossroads.parse('/news/qwerty'); //won't match route Store route reference and attach mutiple listeners
var articleRoute = crossroads.addRoute('/article/{category}/{name}');
articleRoute.matched.add(function(category, name){
console.log(category);
});
articleRoute.matched.add(function(category, name){
console.log(name);
});
//will match articleRoute passing "lol_catz" and "keyboard_cat" as param
crossroads.parse('/article/lol_catz/keyboard_cat'); Use RegExp to validate params
var specialNews = crossroads.addRoute('/news/{id}');
specialNews.matched.add(function(id){
console.log(id);
});
specialNews.rules = {
id : /^[0-9]+$/ //match only numeric ids
};
crossroads.parse('/news/asd'); //won't match since ID isn't numeric
crossroads.parse('/news/5'); //will match `specialNews` and pass "5" as param to all listeners
crossroads.parse('/news/5asd'); //won't match since ID isn't numeric Use functions to validate params
This feature is very useful and gives a lot of flexibility on the validation.
var specialNews = crossroads.addRoute('/news/{category}/{id}');
specialNews.matched.add(function(id){
console.log(id);
});
specialNews.rules = {
//function should return a boolean value
id : function(val, request, values){
return val !== 'foo' && values.category !== 'bar';
}
};
crossroads.parse('/news/world/asd'); //will match
crossroads.parse('/news/bar/5'); //won't match Use arrays to validate params
var specialNews = crossroads.addRoute('/news/{id}');
specialNews.matched.add(function(id){
console.log(id);
});
specialNews.rules = {
//segments are treated as strings unless `crossroads.shouldTypecast = true` (default = false)
id : ['asd', '5', '123', '23456', 'qwerty']
};
crossroads.parse('/news/asd'); //will match
crossroads.parse('/news/5'); //will match
crossroads.parse('/news/loremipsum'); //won't match
var specialNews = crossroads.addRoute('/news/{id}');
specialNews.matched.add(function(id){
console.log(id);
});
specialNews.rules = {
//request_ will accept any kind of validation rule (function, array, RegExp)
request_ : ['/news/asd', '/news/5']
};
crossroads.parse('/news/asd'); //will match
crossroads.parse('/news/5'); //will match
crossroads.parse('/news/loremipsum'); //won't match Normalize parameters & add default parameters
This feature is very powerful and can simplify a lot the logic of you application, it makes it easy to create multiple alias to the same route (see #21) and to set default parameters to the matched signal.
function onSectionMatch(sectionId, subId){
console.log(sectionId +' - '+ subId);
}
var newsRoute = crossroads.addRoute('/news/{date}/{id}', onSectionMatch);
newsRoute.rules = {
normalize_ : function(request, vals){
//return parameters that should be passed to matched signal listeners
return ['editorial', vals.id];
}
};
crossroads.parse('/news/2011-08-32/123'); //will log "editorial - 123" Default arguments (v0.8.0+)
If you are using crossroads to route nodejs requests you can use the crossroads.parse() second argument to specify the default arguments passed to all handlers. Very useful in case you need to access the request and response objects.
var http = require('http'),
url = require('url'),
crossroads = require('crossroads');
http.createServer(function (req, res) {
//pass request and response as first arguments to all signals
crossroads.parse( url.parse(req.url).pathname, [req, res] );
}).listen(1337, "127.0.0.1");
crossroads.addRoute('/foo/{val}', function(val){
console.log(typeof val);
});
crossroads.shouldTypecast = false; //default = false
crossroads.parse('/foo/false'); //log "string"
crossroads.parse('/foo/true'); //log "string"
crossroads.parse('/foo/123'); //log "string"
crossroads.parse('/foo/abc'); //log "string"
crossroads.shouldTypecast = true; //default = false
crossroads.parse('/foo/false'); //log "boolean"
crossroads.parse('/foo/true'); //log "boolean"
crossroads.parse('/foo/123'); //log "number"
crossroads.parse('/foo/abc'); //log "string" Check if route match a string
var myRoute = crossroads.addRoute('/foo/{id}');
console.log( myRoute.match('/foo/bar') ); //true Create a string that matches the route (v0.9.0+)
var myRoute = crossroads.addRoute('foo/{id}/:slug:');
myRoute.interpolate({id: 123, slug: 'something'}); // "foo/123/something"
myRoute.interpolate({id: 456}); // "foo/456"
var myRoute = crossroads.addRoute('/foo/{id}');
myRoute.dispose(); //remove route from crossroads and also remove all listeners from route.matched Create a new Router instance
You can create multiple Routers if needed. The new instance will work exactly like the crossroads object and it is totally independent.
var sectionRouter = crossroads.create();
sectionRouter.addRoute('/foo');
console.log( sectionRouter.getNumRoutes() ); // 1 Piping multiple routers (v0.11.0+)
It's often a better practice to use multiple routers than greedy routes (more granular control and split responsibility), so after v0.11.0 you can also pipe/chain multiple routers.
var sectionRouter = crossroads.create();
var navRouter = crossroads.create();
sectionRouter.pipe(navRouter);
// will also call `parse()` on `navRouter`
sectionRouter.parse('foo');
// there is also an `unpipe()` method
// sectionRouter.unpipe(navRouter); Validate RegExp route capturing groups
You can also validate each capturing group (the same way you do with the normal segments):
var awesomeRoute = crossroads.addRoute(/^(\w+)\/(\w+)$/, function(a, b){
console.log(a +' - '+ b);
});
awesomeRoute.rules = {
//keys match index of capturing groups
'0' : ['asd', 'qwe', 'zxc'];
'1' : function(val, request, values){
if(values[0] == 'asd' && val == '123'){
return false
} else {
return true;
}
}
};
crossroads.parse('asd/123'); //wont match
crossroads.parse('asd/456'); //match Execute an action every time crossroads matches any route
Useful for tracking, debugging and any other action that may need to happen every time the app changes the current route.
//log all routes crossroads.routed.add(console.log, console);Execute an action every time crossroads can't match any route
Useful for tracking, debugging or handling errors.
//log all requests that were bypassed crossroads.bypassed.add(console.log, console);Execute an action when changing from current route to next one (v0.8.0+)
Useful for cases where you might need to trigger an action in between changes and that should only happen in a few cases.
var route1 = crossroads.addRoute('/foo/{bar}');
// will be triggered when current route is `route1` and crossroads is about to
// match another route
route1.switched.add(console.log, console);
Routes with higher priority will be tested before. Routes are tested by order of creation if priority is omitted. The default priority is 0.
crossroads.addRoute('/lorem');
crossroads.addRoute('/{foo}', null, 5);
crossroads.addRoute('/{bar}');
crossroads.parse('/lorem'); //will match second route since it has higher priority
Some people loves chaining... if that's your thing, crossroads API can be chained till a certain extent, use it with care, code may become harder to read:
crossroads
.addRoute('{section}', loadSection)
.rules = {
section : ['home', 'login', 'contact']
};
crossroads.js can be used with Hasher.js, but also with History.js. You'll need signals.js, crossroads.js, history.js, a history.js adapter (on their site). Example is in Coffeescript.
# ### Routes
# Route for some view that takes params
crossroads
.addRoute('{?query}', (query) ->
console.log(query)
)
# Route for an admin section
crossroads
.addRoute('/admin', ->
console.log("admin section")
)
# Process the landing route
crossroads.parse(document.location.pathname + document.location.search)
# log all requests that were bypassed / not matched
crossroads.bypassed.add(console.log, console);
# ### History management
History = window.History
if History.enabled
State = History.getState()
# set initial state to first page that was loaded
History.pushState
urlPath: window.location.pathname
, $("title").text(), State.urlPath
else
return false
loadAjaxContent = (target, urlBase, selector) ->
$(target).load urlBase + " " + selector
updateContent = (State) ->
selector = "#" + State.data.urlPath.substring(1)
if $(selector).length #content is already in #hidden_content
$("#content").children().appendTo "#hidden_content"
$(selector).appendTo "#content"
else
$("#content").children().clone().appendTo "#hidden_content"
loadAjaxContent "#content", State.url, selector
# Content update and back/forward button handler
History.Adapter.bind window, "statechange", ->
crossroads.parse(document.location.pathname + document.location.search)
# navigation link handler
$("body").on "click", "a", (e) ->
urlPath = $(this).attr("href")
if _(urlPath).startsWith('#') # probably some js function we don't want to mess with
return true
e.preventDefault()
title = $(this).text()
History.pushState
urlPath: urlPath
, title, urlPath
For more examples check the unit tests.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4