{"id":16822203,"url":"https://github.com/strml/backbone.queryrouter","last_synced_at":"2025-06-18T06:36:04.869Z","repository":{"id":15100776,"uuid":"17827517","full_name":"STRML/backbone.queryRouter","owner":"STRML","description":"Drop-in Backbone.Router replacement with support for listening to query parameters.","archived":false,"fork":false,"pushed_at":"2014-08-14T14:40:24.000Z","size":680,"stargazers_count":9,"open_issues_count":0,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-04T08:07:46.695Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/STRML.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-17T12:41:28.000Z","updated_at":"2017-07-31T07:39:13.000Z","dependencies_parsed_at":"2022-09-08T15:11:34.874Z","dependency_job_id":null,"html_url":"https://github.com/STRML/backbone.queryRouter","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STRML%2Fbackbone.queryRouter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STRML%2Fbackbone.queryRouter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STRML%2Fbackbone.queryRouter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/STRML%2Fbackbone.queryRouter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/STRML","download_url":"https://codeload.github.com/STRML/backbone.queryRouter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219852879,"owners_count":16556205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T11:02:13.889Z","updated_at":"2024-10-13T11:03:16.147Z","avatar_url":"https://github.com/STRML.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*\n\n- [Backbone.queryRouter](#backbonequeryrouter)\n\t- [Requirements](#requirements)\n\t- [Download](#download)\n\t- [Description](#description)\n\t- [Usage](#usage)\n\t\t- [Backbone.history.navigateBase(String route, Object options)](#backbonehistorynavigatebasestring-route-object-options)\n\t\t- [Backbone.history.getBaseRoute() -\u003e String](#backbonehistorygetbaseroute--\u003e-string)\n\t\t- [Backbone.history.query -\u003e Backbone.Model](#backbonehistoryquery--\u003e-backbonemodel)\n\t\t- [Backbone.history.resetQuery(Object|String query)](#backbonehistoryresetqueryobject|string-query)\n\t- [Documentation](#documentation)\n\t- [Helper Functions](#helper-functions)\n\t- [Nested Attributes](#nested-attributes)\n\t- [Querystring Formatting](#querystring-formatting)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\nBackbone.queryRouter\n====================\n\nExecute multiple routes per URL change using watches on querystring keys. Drop-in plugin for Backbone;\nexisting routers may remain unchanged, but you gain querystring-based routing via the new \n`queryRoutes` property.\n\nRequirements\n------------\n\n`Backbone \u003e= 1.1.1`\n\nDownload\n--------\n\nFor browsers:\n\n[Development Version](dist/backbone.queryRouter.browser.js) (~20KB)\n\n[Production Version](dist/backbone.queryRouter.browser.min.js) (~5.5KB, ~2.5KB gzipped)\n\nFor Node:\n\n```bash\nnpm install backbone.queryrouter\n```\n\nFor eyeballs:\n\n[Readable Source](src/backbone.queryRouter.js)\n\n[Docs](http://strml.github.io/backbone.queryRouter/src/backbone.queryRouter.js.html)\n\nNested model/querystring support:\n\n[Development Version](dist/backbone.queryRouter.nested.browser.js) (~32KB)\n\n[Production Version](dist/backbone.queryRouter.nested.browser.min.js) (~10KB, ~4.0KB gzipped)\n\nDescription\n-----------\n\nModern web applications have many moving parts, and traditional webapp routing is far too restrictive\nto deal with real-world apps.\n\nA modern webapp may have many independent bits of serializable state that must be correctly transmitted\nwhen a URL is sent to another user. For example, a music app may want to send the current song, position within\nthe song, and location within a browsing window. A search app may want to transmit the current query,\nselected results, expansion of those results, and user preferences.\n\nIt is not always possible to store complex state in localStorage or cookies, if you want to transmit that\ncomplex state to other users via a URL. It can very quickly become unwieldy to create massive 'multi-routes',\nwhere sections of the URL delegate to subrouters. Every time a new widget with state is added, a new \nsection must be added to the route, and all links updated. `There has to be a better way!`\n\nQuerystrings are a perfect solution to this problem, and with HTML5 pushState, they can easily be used\non the client and the server.\n\nUsage\n-----\n\nTo create a router supporting query changes, use the following format:\n\n```javascript\nvar QueryAwareRouter = Backbone.Router.extend({\n\n  // Normal routes definition - this is unchanged.\n  // Normal routes are fired before queryRoutes.\n  routes: {\n    'books/:bookID': 'viewBook',\n    'albums/:songNumber': 'viewSong'\n  },\n\n  // QueryRoutes are defined here. They are fired after normal routes.\n  // They are defined in the format:\n  // {String} keys : {String} handlerName\n  queryRoutes: {\n    // Here you can specify which keys you want to listen to.\n    // The attached handler will be fired each time any of the keys are \n    // added, removed, or changed.\n    'volume': 'setVolume',\n    // To listen to multiple keys, separate them with commas. Whitespace is ignored.\n    'playState, songID' : 'playSong',\n    // To use nested properties, see the `Nested Attributes` section below.\n    'object.nestedProperty': 'nestedHandler'\n  },\n\n  // Each queryHandler is called with two parameters:\n  // @param {Object} queryObj   Current query object.\n  // @param {Array} changedKeys Array of changed keys that caused this handler to fire.\n  setVolume: function(queryObj, changedKeys) {\n    // e.g. if the query is changed to '?songID=foo\u0026volume=100', \n    // `changedKeys = ['volume']` and `queryObj = {songID: 'foo', volume: '100'}`\n    // If you need to get just the changed pairs, use _.pick(queryObj, changedKeys)\n  },\n\n  playSong: function(queryObj, changedKeys) {\n    // e.g. if the query is changed to '?songID=foo\u0026volume=100', \n    // `changedKeys = ['songID']` and `queryObj = {songID: 'foo', volume: '100'}`\n  },\n\n  // ... more handlers ...\n});\n\n```\n\nDocumentation\n-------------\n\nGenerated documentation is [available here](http://strml.github.io/backbone.queryRouter/src/backbone.queryRouter.js.html).\n\nHelper Functions\n----------------\n\nBackbone.queryRouter comes with a few helper functions that help you modify the current URL.\n\n### Backbone.history.navigateBase(String route, Object options)\n\nUsage: `Backbone.history.navigateBase('/newRoute', {trigger: true});`\n\nUseful when you want to change the base route and fire a route handler, but you don't want\nto change the current query. No query handlers will be fired and the query in the URL bar\nwill remain unchanged.\n\n### Backbone.history.getBaseRoute() -\u003e String\n\nReturns current base route (fragment without querystring).\n\n### Backbone.history.query -\u003e Backbone.Model\n\nUsage:\n\n```javascript\nBackbone.history.query.set(attributes, [options])\nBackbone.history.query.unset(attributes, [options])\nBackbone.history.query.clear()\nBackbone.history.query.toString()\n```\n\nThe current query is attached to Backbone.history as a simple Backbone.Model. It supports\nall of the usual Backbone.Model methods and events. Changing attributes on the query\nwill automatically fire the associated query handlers, much like calling \n`Backbone.history.navigate(route, {trigger:true})`.\n\nCall `Backbone.history.query.toString()` to get the current query string.\n\n### Backbone.history.resetQuery(Object|String query, Object options)\n\nUsage: \n\n```javascript\nBackbone.history.resetQuery({key: 'value', nested: {key2: 'value2'}})\nBackbone.history.query.reset(\"?key=value\u0026key2=value2\") // alias\n// see `Nested Attributes` below\nBackbone.history.resetQuery(\"ignored/fragment?key=value\u0026nested[key2]=value2\")\n// Don't trigger handlers\nBackbone.history.resetQuery({key: 'value'}, {trigger: false})\n// Don't trigger anything, including URL changes\nBackbone.history.resetQuery({key: 'value'}, {silent: true})\n// Only set/unset certain keys\nBackbone.history.resetQuery({key: 'value'}, {keys: ['key', 'key2']})\n// Set, but don't unset\nBackbone.history.resetQuery({key: 'value'}, {unset: false})\n\n```\n\nResets the current query value to an entirely new value. Optionally accepts a query string with or\nwithout a leading `?`, and will automatically extract the querystring if you pass it a full\nroute fragment. If you pass this method a querystring containing a `?` in a key or value, \nyou must include the leading `?` or the querystring will be misparsed.\n\nThis method is similar to `Backbone.Collection.reset`; it fires the appropriate `set` and\n`unset` methods, including the associated change events. Only a single `change` event will be thrown, so there is no need to \ndebounce your handlers.\n\nIn the normal (not nested) version of this library, `reset({key: 'param'})` has the same result\nas `reset({key: ['param']})` when stringified and thus will not emit a change event if one is done\nafter the other.\n\nNested Attributes\n-----------------\n\nNested attribute support is available in \n[backbone.queryRouter.nested.browser.js](dist/backbone.queryRouter.nested.browser.js) \n([Production Build](dist/backbone.queryRouter.nested.browser.min.js)). \nWhile this build supports binding to nested attributes, the embedded query model\ndoes not support firing change events on nested attributes. If you require this, simply\ninclude [Backbone.NestedModel](https://github.com/afeld/backbone-nested) before this\nscript and the proper events will automatically be thrown.\n\nQuerystring Formatting\n----------------------\n\nThe smaller, non-nested build of `backbone.queryRouter` uses a nodeJS-compatible querystring library that does\nnot support nested attributes. For example, the query object `{key: ['val1', 'val2']}` would be translated\nto `key=val1\u0026key=val2` and vice-versa.\n\nIn the nested build, querystring support is changed to \n[visionmedia/node-querystring](https://github.com/visionmedia/node-querystring), which supports nested attributes.\nIt also includes keys in arrays, so be sure that your server can parse them correctly. For example,\n`{key: ['val1', 'val2']}` would be translated to `key[0]=val1\u0026key[1]=val2`.\n\nLicense\n-------\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrml%2Fbackbone.queryrouter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrml%2Fbackbone.queryrouter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrml%2Fbackbone.queryrouter/lists"}