{"id":28025471,"url":"https://github.com/roundingwellos/backbone.eventrouter","last_synced_at":"2025-08-03T10:13:42.344Z","repository":{"id":33921423,"uuid":"37641626","full_name":"RoundingWellOS/backbone.eventrouter","owner":"RoundingWellOS","description":"A highly opinionated, simplistic Backbone.Router coupled with a Backbone.Radio.Channel","archived":false,"fork":false,"pushed_at":"2024-09-26T21:12:47.000Z","size":264,"stargazers_count":13,"open_issues_count":2,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-13T10:18:21.355Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/RoundingWellOS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-18T06:25:01.000Z","updated_at":"2024-12-13T14:20:17.000Z","dependencies_parsed_at":"2024-08-13T19:21:44.187Z","dependency_job_id":"8897fccb-6860-458b-a19e-4e9d31d3bbee","html_url":"https://github.com/RoundingWellOS/backbone.eventrouter","commit_stats":{"total_commits":24,"total_committers":4,"mean_commits":6.0,"dds":"0.16666666666666663","last_synced_commit":"1a898353a7368d6390a7d25a48345689a1289fc7"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoundingWellOS%2Fbackbone.eventrouter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoundingWellOS%2Fbackbone.eventrouter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoundingWellOS%2Fbackbone.eventrouter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RoundingWellOS%2Fbackbone.eventrouter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RoundingWellOS","download_url":"https://codeload.github.com/RoundingWellOS/backbone.eventrouter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253516688,"owners_count":21920719,"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":"2025-05-11T04:23:21.461Z","updated_at":"2025-05-11T04:23:22.096Z","avatar_url":"https://github.com/RoundingWellOS.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Backbone.EventRouter\n====================\n\n[![Travis Status](http://img.shields.io/travis/RoundingWellOS/backbone.eventrouter/master.svg?style=flat\u0026amp;label=travis)](https://travis-ci.org/RoundingWellOS/backbone.eventrouter) [![Code Climate Score](http://img.shields.io/codeclimate/github/RoundingWellOS/backbone.eventrouter.svg?style=flat)](https://codeclimate.com/github/RoundingWellOS/backbone.eventrouter) [![Coverage](http://img.shields.io/codeclimate/coverage/github/RoundingWellOS/backbone.eventrouter.svg?style=flat)](https://codeclimate.com/github/RoundingWellOS/backbone.eventrouter) [![Dependency Status](http://img.shields.io/david/RoundingWellOS/backbone.eventrouter.svg?style=flat)](https://david-dm.org/RoundingWellOS/backbone.eventrouter)\n\n\n## About Backbone.EventRouter\n\nBackbone.EventRouter extends the [Backbone.Router](http://backbonejs.org/#Router).  It is coupled with a [Backbone.Radio](https://github.com/marionettejs/backbone.radio) Channel such that when an event is triggered on the channel, it will set the route URL, or when a URL matches a route it will throw an event on the channel.\n\nThis router was built from scripts open sourced from [RoundingWell.com](http://www.roundingwell.com).\n\n## Why yet another Backbone router?\nEarly on we attempted to adopt [event based routing](https://lostechies.com/derickbailey/2011/08/28/dont-execute-a-backbone-js-route-handler-from-your-code/) but found that the patterns led to a lot of repetition.  Not only did you need to define your routes in the router, you also had to do it in corresponding events.  This router helps prevent the repetition and makes the concept maintainable. This extension allows you to use Backbone's router how it was intended (`{trigger: false}`), as well as allowing you to change the state of your app fully through events, using the router to merely kick-off the initial state.\n\n##### But Ember does it differently...\nQuite a good argument against Backbone's router is that it isn't Ember's router, and you'll find many Backbone.Router extensions modeling functionality from that router.  While that is a very valid use case, we find Ember's router to be very heavy.  That router often has the concern of handling the routes, fetching the data and kicking off an app (aka: sub-app, module, component, widget, etc).\n\n##### Backbone.EventRouter is simplistic\nThis router is much simpler in that it listens for routes and triggers events, and listens for events and replace the URL with the applicable route.  That's essentially it.  You're on your own as far as how to handle those events.  But we'd recommend something like [marionette.toolkit.routerapp](https://github.com/RoundingWellOS/marionette.toolkit.routerapp).\n\n\n## Documentation Index\n* [EventRouter's `channelName`](#eventrouters-channelname)\n* [EventRouter's `routeTriggers`](#eventrouters-routetriggers)\n* [EventRouter Events](#eventrouter-events)\n  * [\"before:route\" event](#beforeroute-event)\n  * [\"before:route:[name]\" event](#beforeroutename-event)\n  * [\"noMatch\" event](#nomatch-event)\n* [EventRouter API](#eventrouter-api)\n  * [`getChannel`](#getchannel)\n  * [`addRouteTrigger`](#addroutetrigger)\n  * [`getDefaultRoute`](#getdefaultroute)\n  * [`navigateFromEvent`](#navigatefromevent)\n  * [`translateRoute`](#translateroute)\n\n## EventRouter's `channelName`\n*Default Value:* `'event-router'`\n\nSpecify a `channelName` in your router class definition. This should be a\nstring or a function returning a string that indicates the Backbone.Radio\n[Channel](https://github.com/marionettejs/backbone.radio#channels) name\nthat EventRouter will use.\n\n```js\nBackbone.EventRouter.extend({\n  channelName: 'my-event-channel'\n});\n```\n\nAlternatively, you can specify a `channelName` in the options for\nthe `constructor`:\n\n```js\nvar MyEventRouter = Backbone.EventRouter.extend({...});\n\nnew MyEventRouter({\n  channelName: 'my-event-channel'\n});\n```\n\n## EventRouter's `routeTriggers`\n`routeTriggers` can be a hash or function on the definition\nor passed as an option when instantiating an EventRouter.\n\nThis hash is used to add multiple trigger routes at instantiation.\nEssentially [`addRouteTrigger`](#addroutetrigger) is called for each route trigger.\nMore information about route triggers can be found [here](#addroutetrigger).\n\n```js\nnew MyEventRouter({\n  routeTriggers: {\n    'some:event': 'some/url',\n    'thing:list': 'other/:param',\n    'thing:item': ['some/thing/:id', 'some/thing']\n  }\n});\n\n```\n\n## EventRouter Events\nThese are events triggered on the EventRouter itself.  They are not triggered on the Radio channel.  The Radio channel should be used strictly for routing events.\n\n### \"before:route\" event\nThe \"before:route\" event is functionally equivalent to Backbone's \"route\" [event](http://backbonejs.org/#Events-catalog) but triggered immediately before the route handler instead of after.  [See Backbone.Router.route](http://backbonejs.org/#Router-route) for more information.\n### \"before:route:[name]\" event\nThe \"before:route:[name]\" event is functionally equivalent to Backbone's \"route:[name]\" [event](http://backbonejs.org/#Events-catalog) but triggered immediately before the route handler instead of after.  [See Backbone.Router.route](http://backbonejs.org/#Router-route) for more information.\n### \"noMatch\" event\nIf any event triggered on the Radio Channel is not handled by this EventRouter, this event will be triggered and receive the event string and any data sent to the event.\n\n```js\nvar myEventRouter = new MyEventRouter({\n  routeTriggers: {\n    'some:event': 'some/url',\n    'thing:list': 'other/:param'\n  }\n});\n\nmyEventRouter.on('noMatch', function(event, data){\n  console.log('The event ' + event + ' with data ' + data + ' was not handled by this router!');\n});\n\nvar routeChannel = myEventRouter.getChannel();\n\n// \"The event event:not:handled with data foo was not handled by this router!\" will be logged\nrouteChannel.trigger('event:not:handled', 'foo');\n```\n\n\n## EventRouter API\n### `getChannel`\nGets the EventRouter's Backbone.Radio Channel instance.\n\n```js\nvar router = new Backbone.EventRouter({\n  channelName: 'my-event-channel'\n});\n\nvar routerChannel = router.getChannel();\n\nrouterChannel.on('foo', function(){\n  console.log('Same channel!');\n});\n\n// Triggering here will log: \"Same channel!\"\nBackbone.Radio.trigger('my-event-channel', 'foo');\n```\n\n\n### `addRouteTrigger`\nAdds a routerTrigger, and route(s) to Backbone.Router\nwhich, on route, triggers the appropriate event.\n\nConversely when the event is triggered, the URL will update\nto match the route paired with the event.\n\n```js\nmyEventRouter.addRouteTrigger('some/url/:param', 'some:event');\n\nvar myRouterChannel = myEventRouter.getChannel();\n\nmyRouterChannel.on('some:event', function(param){\n  console.log('Triggered: ' + param);\n});\n\n// Will console log \"Triggered foo\"\nmyEventRouter.navigate('some/url/foo', { trigger: true });\n\n```\n\nThis function also takes an array of routes.  Any route in the array will\ntrigger the given event.  In this case the first route in the array is\nconsidered the default route and will be matched if the event is triggered.\n\n```js\nmyEventRouter.addRouteTrigger(['some/url/:param', 'some/url', 'other/:section/:id'], 'some:event');\n\nvar myRouterChannel = myEventRouter.getChannel();\n\n// Will route URL to \"some/url/bar\"\nmyRouterChannel.trigger('some:event', 'bar');\n```\n\n*Note:* Splat routes and Optional params are not currently supported. ( ie: \"some/url(/:param)\" )\nSimilar handling of multiple routes can be done by setting an array of possible permutations.\nYou can additionally handle these routes as your normally would on a [Backbone.Router](http://backbonejs.org/#Router-routes).\n\n### `getDefaultRoute`\nGet the default route string.\nIt will be either the first of the array or the passed-in event if singular.\n\n```js\nvar myEventRouter =new MyEventRouter({\n  routeTriggers: {\n    'some:event': ['some/url/:param', 'some/url', 'other/:section/:id'],\n    'thing:list': 'other/:param'\n  }\n});\n\n// will return 'some/url/:param'\nmyEventRouter.getDefaultRoute('some:event');\n\n// will return 'other/:param'\nmyEventRouter.getDefaultRoute('thing:list');\n```\n\n### `navigateFromEvent`\nTakes an event string and any arguments passed to that event and translates\nthe event into a URL and navigates to it without re-triggering the route.\n\n```js\nvar myEventRouter =new MyEventRouter({\n  routeTriggers: {\n    'some:event': ['some/url/:param', 'some/url', 'other/:section/:id'],\n    'thing:list': 'other/:param'\n  }\n});\n\n// Will change the route to  \"some/url/foo\" but will not trigger the route or event\nmyEventRouter.navigateFromEvent('some:event', 'foo');\n```\n\n### `translateRoute`\nTakes a route string and an array of arguments\nand returns a url with the named params replaced with the argument values.\n\n```js\n// will return 'some/url/foo/22'\nmyEventRouter.translateRoute('some/url/:param/:id', ['foo', 22]);\n```\n\n## Getting Help\n\nIf you have questions or concerns please feel free to [open an issue](#github-issues).\nAdditionally join us on the [Marionette Gitter](https://gitter.im/marionettejs/backbone.marionette) to have a chat.\nEveryone there is happy to discuss design patterns.\n\n\n## Project Details\n\n#### Library Downloads\n\nYou can download the latest builds directly from the [dist](https://github.com/RoundingWellOS/backbone.eventrouter/tree/master/dist) folder above.\n\n#### Available Packages\n\n**Via [npm](https://www.npmjs.com/package/backbone.eventrouter)**\n```\n$ npm install backbone.eventrouter\n```\n\n**Via [bower](http://bower.io/search/?q=backbone.eventrouter)**\n```\n$ bower install backbone.eventrouter\n```\n\n\nCurrently Backbone.EventRouter is available via npm and bower. If you would like add it to another channel, please\n[open an issue](#github-issues).\n\n#### Changelog\n\nFor change logs and release notes, see the [changelog](CHANGELOG.md) file.\n\n#### Compatibility and Requirements\n\nBackbone.EventRouter currently requires [Backbone](http://backbonejs.com) `1.1.1+`.\n\nBackbone.EventRouter supports IE8+ and modern browsers.\n\n\n## How to Contribute\n\nIf you would like to contribute to Backbone.EventRouter's source code, please read\nthe [guidelines for pull requests and contributions](CONTRIBUTING.md).\nFollowing these guidelines will help make your contributions easier to\nbring into the next release.\n\n\n### Github Issues\n\n[Report issues](https://gitter.im/RoundingWellOS/backbone.eventrouter/issues) with Backbone.EventRouter, and [submit pull requests](https://github.com/RoundingWellOS/backbone.eventrouter/pulls) to fix problems or to\ncreate summarized and documented feature requests (preferably with the feature implemented in the pull request).\n\n\n===\n\nThis library is © 2015 RoundingWell. Distributed under MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froundingwellos%2Fbackbone.eventrouter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froundingwellos%2Fbackbone.eventrouter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froundingwellos%2Fbackbone.eventrouter/lists"}