Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Backbone plugin which provides query parameter support

branch: master

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…


Cannot retrieve the latest commit at this time

Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 LICENSE
Octocat-spinner-32 backbone.queryparams.js


Copy backbone.queryparams.js to your environment and include after backbone.js.

Query string route syntax

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

Example route patterns

  • #foo/abc -> myRoute( 'abc', undefined )
  • #foo/abc?foo=bar -> myRoute( 'abc', {'foo': 'bar'} )

Nested query strings

  • Any keys containing '.' will represent a nested 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'] )

Generating route with query string

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','|']

Regular Expression Routes

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)
Something went wrong with that request. Please try again.