vue-route
v1.5.1
Published
Routing directive for Vue.js, inspired by ng-view.
Downloads
2,871
Maintainers
ayamflowReadme
vue-route
Routing directive for Vue.js, inspired by ng-view.
Based on v-component thus benefits from v-transition, keep-alive, wait-for, transition-mode.
Versions 1.5.0+ are made for Vue.js v0.12+. Use older versions for Vue.js v0.11.
Allows you to declare your routes on the $root Vue object:
var root = new Vue({
el: 'body',
routes: {
'/home': {
componentId: 'fg-home',
isDefault: true
},
'/items/:item': {
componentId: 'fg-item',
afterUpdate: 'updateHeader',
data: {
defaultColor: '#3453DD'
}
},
options: {
hashbang: true
}
}
});
With minimal markup:
<body>
<div v-route></div>
</body>
vue-route extends the v-component directive by @yyx990803 (on the vuejs repo). Buy him a coffee if you can.
Get started
1. Install with npm/component(1): npm i vue-route --save or component install ayamflow/vue-route.
2. Require and install the plugin:
var Vue = require('vue'),
route = require('vue-route');
Vue.use(route); // BOOM3. Put the <div v-route></div> in your main template.
4. Pass your routes to the $root VM of you app (see example above).
5. Profit !
Transition, keep-alive and other directives
If you want to add custom transitions between your pages, it's recommended to put them on each page's component template. Putting anything on the v-route element itself will only be active if you change this element (for instance with a v-if directive).
Following the example, that would be:
<div class="Home" v-transition="homeTransition">...</div> // fg-home componentAdditional infos
- Routes definition: when you pass your routes to the
$root, you can pass several properties:componentId: the Vue.component id for the associated template/VM.beforeUpdate: a callback (method or name of method on the vm) to call before effectively changing to this routehtml.afterUpdate: a callback (method or name of method on the vm) to call after effectively having changed to this route.data: an object (or function returning 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.isDefault: boolean indicating wether this page should be the default, in case of non-existing URL. Think of it as theotherwisefrom Angular, so basically a 404 or the home page.
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.
For instance, you can return before next is called to cancel the route; usefull for an authentication page for instance.
Another instance is to pause the app during loading and calling next when everything is loaded, thus resuming the flow.
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.
The router will emit events on your
$rootVM:router:started,router:beforeUpdate,router:afterUpdate.You can pass a
optionshash to pass configuration to the router:hashbang: boolean (defaults to false) to use#!urls. Note that your links shouldn't include hashbangs, the router handles this.click: boolean (defaults to true) to automatically bind all click to the router. Not that iffalse, you will need to explicitly callVue.navigatemethod).base: string (defaults to '/') to specify the base path.broadcast: boolean (defaults to false) if true the events will be emitted using the $root$broadcastmethod, so all child VMs will receive the event until a handlerreturn false;. If false, it uses$emit.debug: boolean (defaults to false) to activate logging from the directive.
Location context
When the router emits an event, 2 parameters are passed: location and oldLocation. Like in Angular, it is an object containing some useful properties:
regexp: the route regexp, such as/items/:item.path: the current path, such as/items/razor/.params: a hash of the params from the route, here{item: 'razor'}.componentId: the componentId associated to the current route.
Route parameters
Each component used by v-route will have its $data extended with the location.params array (see above). That means that on the route /items/razor, this.$data.$routeParams.item == 'razor'.
Subroutes
Managing subviews with subroutes like /route/:firstParam/:secondParam is userland responsability; you should handle this with a v-component or programmatically.
Compatibility note
vue-route supports the same browsers as Vue; however to make it properly work on IE9 you need to add the HTML5-history-API polyfill.
Contributing
- Fork & PR on dev branch.
- If possible, add tests to cover the changes.
- Code style: 4 tabs, semicolons. Check the code if in doubt.