Copy backbone.queryparams.js to your environment and include after backbone.js.
Any route except those ending with a wildcard will automatically accept additional content using the '?' separator. This content is a set of key value pairs using '&' as the pair separator and '=' as the key/value separator - just like the URL query string syntax.
If a query string exists in the route hash, the routing function (defined in the routes hash) will be given an additional parameter (in last ordinal position) containing hash of the key/value data.
routes: {
'foo/:bar': 'myRoute'
}
...
myRoute: function(bar, params) {
// the params attribute will be undefined unless there is a route containing a query string
}
- #foo/abc -> myRoute( 'abc', undefined )
- #foo/abc?foo=bar -> myRoute( 'abc', {'foo': 'bar'} )
All query parameters can be passed in a single hash using the key referenced from the route definition by setting Backbone.Router.namedParameters = true.
Using the previous example route patterns, the controller function would be
myRoute( {bar: 'abc', foo: 'bar'} );
Although this is not compatible with backbone, it is very useful to prevent router function parameter overloading where you have to always consider whether the route query parameters were passed.
-
Any keys containing '.' will represent a nested structure.
-
Any keys containing '[]' will assume an array structure.
-
Any values containing '|' will assume an array structure.
-
Non-array values can still contain '|' but it must be URI encoded (%7C).
-
A prefix of '|' will ensure an array in case there is only a single value.
#foo/abc?me.fname=Joe&me.lname=Hudson -> myRoute('abc', {'me': {'fname': 'Joe', 'lname': 'Hudson'}} ) #foo/abc?animals=cat|dog -> myRoute( 'abc', ['cat', 'dog'] ) #foo/abc?animals=|cat -> myRoute( 'abc', ['cat'] )
You can create a route string from a route + parameter hash using the router.toFragment(route, parameters) method. It can contain a nested hash structure or arrays. ex:
var route = router.toFragment('myroute', {
a:'l', b:{c: 'n', d:'m', e:{f: 'o'}}, array1:['p'], array2:['q', 'r'], array3:['s','t','|']
});
If you want to use this plugin with regex routes you'll need to append the query capture component (([\?]{1}.*)?) manually.
router.route(/foo\/([^\/]+)\//, 'foo:event', callback)
should be written
router.route(/foo\/([^\/]+)\/([\?]{1}.*)?/, 'foo:event', callback)
This library supports Backbone 1.0.0 and 1.1.0. Backbone 1.1.0 users need to either include the backbone.queryparams-1.1-shim.js file or modify their backbone libray to remove this line from Backbone.History.prototype.navigate.
// Strip the fragment of the query and hash for matching.
fragment = fragment.replace(pathStripper, '');