|
| 1 | +vue-route |
| 2 | +======= |
| 3 | + |
| 4 | +Routing directive for Vue.js **(v0.11)**, inspired by ng-view. |
| 5 | +Based on `v-component` thus benefits from `v-transition`, `keep-alive`, `wait-for`, `transition-mode`. |
| 6 | + |
| 7 | +Allows you to declare your routes on the `$root` Vue object: |
| 8 | + |
| 9 | +```js |
| 10 | +var root = new Vue({ |
| 11 | + el: 'body', |
| 12 | + |
| 13 | + routes: { |
| 14 | + '/home': { |
| 15 | + componentId: 'fg-home', |
| 16 | + isDefault: true |
| 17 | + }, |
| 18 | + '/work/:work': { |
| 19 | + componentId: 'fg-work', |
| 20 | + afterUpdate: 'updateHeader', |
| 21 | + data: { |
| 22 | + defaultColor: '#3453DD' |
| 23 | + } |
| 24 | + }, |
| 25 | + options: { |
| 26 | + hashbang: true |
| 27 | + } |
| 28 | + } |
| 29 | +}); |
| 30 | + |
| 31 | +``` |
| 32 | + |
| 33 | +With minimal markup: |
| 34 | + |
| 35 | +```html |
| 36 | +<body> |
| 37 | + <div v-route></div> |
| 38 | +</body> |
| 39 | + |
| 40 | +``` |
| 41 | + |
| 42 | +`vue-route` extends the `v-component` directive by @yyx990803 (on the [vuejs repo](https://github.com/yyx990803/vue/tree/master/src/directives/component.js)). Buy him a coffee if you can. |
| 43 | + |
| 44 | +## Get started |
| 45 | + |
| 46 | +**1.** Install with npm/component(1): `npm i vue-route --save` or `component install ayamflow/vue-route`. |
| 47 | + |
| 48 | +**2.** Require and install the plugin: |
| 49 | + |
| 50 | +```js |
| 51 | +var Vue = require('vue'), |
| 52 | + route = require('vue-route'); |
| 53 | + |
| 54 | +Vue.use(route); // BOOM |
| 55 | +``` |
| 56 | + |
| 57 | +**3.** Put the `<div v-route></div>` in your main template. |
| 58 | + |
| 59 | +**4.** Pass your routes to the `$root` VM of you app (see example above). |
| 60 | + |
| 61 | +**5.** Profit ! |
| 62 | + |
| 63 | +## Additional infos |
| 64 | + |
| 65 | +* Routes definition: when you pass your routes to the `$root`, you can pass several properties: |
| 66 | + * `componentId`: the Vue.component id for the associated template/VM. |
| 67 | + * `beforeUpdate`: a callback (method or name of method on the vm) to call before effectively changing to this routehtml. |
| 68 | + * `afterUpdate`: a callback (method or name of method on the vm) to call after effectively having changed to this route. |
| 69 | + * `data`: an object that will be **merged** with the view's `$data`. This is useful when we need to use the same component for different urls but using different data. |
| 70 | + * `isDefault`: boolean indicating wether this page should be the default, in case of non-existing URL. Think of it as the `otherwise` from Angular, so basically a 404 or the home page. |
| 71 | + |
| 72 | +`beforeUpdate` is a middleware, this means you need to call the `next` function provided as the third argument, to continue routing. This allows to prevent a route based on some condition. |
| 73 | + |
| 74 | +Vue is augmented with an additional method, `Vue.navigate(path, [trigger])`. [trigger] is a boolean (defaults to true) that will `pushState` if true, `replaceState` otherwise. |
| 75 | + |
| 76 | +* The router will emit events on your `$root` VM: `router:started`, `router:beforeUpdate`, `router:afterUpdate`. |
| 77 | + |
| 78 | +* You can pass a `options` hash to pass configuration to the router: |
| 79 | +<<<<<<< HEAD |
| 80 | + * `hashbang`: boolean (defaults to false) to use `#!` urls. Note that your links shouldn't include hashbangs, the router handles this. |
| 81 | + * `click`: boolean (defaults to true) to automatically bind all click to the router. Not that if `false`, you will need to explicitly call `Vue.navigate` method). |
| 82 | + * `base`: string (defaults to '/') to specify the base path. |
| 83 | + * `broadcast`: boolean (defaults to false) if true the events will be emitted using the $root `$broadcast` method, so all child VMs will receive the event until a handler `return false;`. If false, it uses `$emit`. |
| 84 | + * `debug`: boolean (defaults to false) to activate logging from the directive. |
| 85 | +======= |
| 86 | + * `hashbang` boolean (defaults to false) to use `#!` urls. Note that your links shouldn't include hashbangs, the router handles this. |
| 87 | + * `click` boolean (defaults to true) to automatically bind all click to the router. Not that if `false`, you will need to explicitly call `Vue.navigate` method) |
| 88 | + * `base` string (defaults to '/') to specify the base path |
| 89 | + * `broadcast` boolean (defaults to false) if true the events will be emitted using the $root `$broadcast` method, so all child VMs will receive the event until a handler `return false;`. If false, it uses `$emit`. |
| 90 | + * `debug` boolean (defaults to false) to activate logging from the directive. |
| 91 | +>>>>>>> Add notice regarding URL and hashbangs as seen in #15. |
| 92 | + |
| 93 | +## Location context |
| 94 | + |
| 95 | +When the router emits an event, 2 parameters are passed: `location` and `oldLocation`. Like in Angular, it is an object containing some useful properties: |
| 96 | +* `regexp`: the route regexp, such as `/items/:itemId`. |
| 97 | +* `path`: the current path, such as `/items/razor/`. |
| 98 | +* `params`: a hash of the params from the route, here `{item: 'razor'}`. |
| 99 | +* `componentId`: the componentId associated to the current route. |
| 100 | + |
| 101 | +## Contributing |
| 102 | + |
| 103 | +* Fork & PR on **[dev](https://github.com/ayamflow/vue-route/tree/dev)** branch. |
| 104 | +* If possible, add tests to cover the changes. |
| 105 | +* Code style: 4 tabs, semicolons. Check the code if in doubt. |
0 commit comments