Feature: routeConfig.props - Passing props to a component

Author: bfanger

docs/en/SUMMARY.md

@@ -13,6 +13,7 @@
   - [Named Routes](essentials/named-routes.md)
   - [Named Views](essentials/named-views.md)
   - [Redirect and Alias](essentials/redirect-and-alias.md)
+  - [Passing props](essentials/passing-props.md)
   - [HTML5 History Mode](essentials/history-mode.md)
 - Advanced
   - [Navigation Guards](advanced/navigation-guards.md)

docs/en/api/options.md

@@ -13,6 +13,7 @@
     name?: string; // for named routes
     components?: { [name: string]: Component }; // for named views
     redirect?: string | Location | Function;
+    props?: boolean | string | Function;
     alias?: string | Array<string>;
     children?: Array<RouteConfig>; // for nested routes
     beforeEnter?: (to: Route, from: Route, next: Function) => void;

docs/en/essentials/passing-props.md

@@ -0,0 +1,72 @@
+# Passing props
+
+Using `$route` in your component creates a tight coupling with the route which limits the flexibility of the component as it can only be used on certain urls.
+
+To decouple this component from the router use props:
+
+**❌ Coupled to $route**
+
+``` js
+const User = {
+  template: '<div>User {{ $route.params.id }}</div>'
+}
+const router = new VueRouter({
+  routes: [
+    { path: '/user/:id', component: User }
+  ]
+})
+```
+
+**👍 Decoupled with props**
+
+``` js
+const User = {
+  props: ['id'],
+  template: '<div>User {{ id }}</div>'
+}
+const router = new VueRouter({
+  routes: [
+    { path: '/user/:id', component: User, props: true }
+  ]
+})
+```
+
+This allows you to use the component anywhere, which makes the component easier to reuse and test.
+
+### Boolean mode
+
+When props is set to true, the router looks at the component and searches for props with the same name as the route.params.
+When a prop is found and its type is Number, String or not set, the param is passed as prop.
+
+### Object mode
+
+When props is an object, this will be set as the component props as-is.
+
+``` js
+const router = new VueRouter({
+  routes: [
+    { path: '/user/first-one', component: User, props: {id: '1' } }
+  ]
+})
+```
+
+### Function mode
+
+You can create a function that returns props.
+This allows you to mix static values and values based on the route.
+
+``` js
+const router = new VueRouter({
+  routes: [
+    { path: '/search', component: SearchUser, props: (route) => ({ query: route.query.q }) }
+  ]
+})
+```
+
+The url: `/search?q=vue` would pass `{query: "vue"}` as props to the SearchUser component.
+
+Try to keep the props function stateless, as it's only evaluated on route changes.
+Tip: If you need to set props based on route and state create a wrapper component.
+
+
+For advanced usage, checkout the [example](https://github.com/vuejs/vue-router/blob/dev/examples/route-props/app.js).

examples/index.html

@@ -15,6 +15,7 @@ <h1>Vue Router Examples</h1>
     <li><a href="route-matching">Route Matching</a></li>
     <li><a href="active-links">Active Links</a></li>
     <li><a href="redirect">Redirect</a></li>
+    <li><a href="route-props">Route Props</a></li>
     <li><a href="route-alias">Route Alias</a></li>
     <li><a href="transitions">Transitions</a></li>
     <li><a href="data-fetching">Data Fetching</a></li>

examples/route-props/Calculator.vue

@@ -0,0 +1,22 @@
+<template>
+  <div>
+    <h2 class="calculator_add">{{a}} + {{b}} = {{ a + b }}</h2>
+    <h2 class="calculator_multiply">{{a}} * {{b}} = {{ a * b }}</h2>
+  </div>
+</template>
+
+<script>
+
+export default {
+  props: {
+    a: {
+      type: Number,
+      required: true
+    },
+    b: {
+      type: Number,
+      required: true
+    }
+  }
+}
+</script>

examples/route-props/Hello.vue

@@ -0,0 +1,17 @@
+<template>
+  <div>
+    <h2 class="hello">Hello {{name}}</h2>
+  </div>
+</template>
+
+<script>
+
+export default {
+  props: {
+    name: {
+      type: String,
+      default: 'Vue!'
+    }
+  }
+}
+</script>

examples/route-props/app.js

@@ -0,0 +1,42 @@
+import Vue from 'vue'
+import VueRouter from 'vue-router'
+import Hello from './Hello.vue'
+import Calculator from './Calculator.vue'
+
+Vue.use(VueRouter)
+
+function dynamicPropsFn (route) {
+  const now = new Date()
+  return {
+    name: (now.getFullYear() + parseInt(route.params.years)) + '!'
+  }
+}
+
+const router = new VueRouter({
+  mode: 'history',
+  base: __dirname,
+  routes: [
+    { path: '/', component: Hello }, // No props, no nothing
+    { path: '/hello/:name', component: Hello, props: true }, // Match params to props (Only matches props with type: String, Number or untyped)
+    { path: '/static', component: Hello, props: { name: 'world' }}, // static values
+    { path: '/dynamic/:years', component: Hello, props: dynamicPropsFn }, // custom logic for mapping between route and props
+    { path: '/calculator/:a/:b', component: Calculator, props: true } // Props with type Number are passed as number
+  ]
+})
+
+new Vue({
+  router,
+  template: `
+    <div id="app">
+      <h1>Route props</h1>
+      <ul>
+        <li><router-link to="/">/</router-link></li>
+        <li><router-link to="/hello/you">/hello/you</router-link></li>
+        <li><router-link to="/static">/static</router-link></li>
+        <li><router-link to="/dynamic/1">/dynamic/1</router-link></li>
+        <li><router-link to="/calculator/2/3">/calculator/2/3</router-link></li>
+      </ul>
+      <router-view class="view"></router-view>
+    </div>
+  `
+}).$mount('#app')

examples/route-props/index.html

@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<link rel="stylesheet" href="/global.css">
+<a href="/">&larr; Examples index</a>
+<div id="app"></div>
+<script src="/__build__/shared.js"></script>
+<script src="/__build__/route-props.js"></script>

src/components/view.js

@@ -1,3 +1,5 @@
+import { resolveProps } from '../util/props'
+
 export default {
   name: 'router-view',
   functional: true,
@@ -49,6 +51,7 @@ export default {
           matched.instances[name] = undefined
         }
       }
+      data.props = resolveProps(route, component, matched.props && matched.props[name])
     }
 
     return h(component, data, children)

src/create-route-map.js

@@ -44,6 +44,7 @@ function addRouteRecord (
     name,
     parent,
     matchAs,
+    props: typeof route.props === 'undefined' ? {} : (route.components ? route.props : { default: route.props }),
     redirect: route.redirect,
     beforeEnter: route.beforeEnter,
     meta: route.meta || {}

src/util/props.js

@@ -0,0 +1,46 @@
+
+import { warn } from './warn'
+
+export function resolveProps (route, component, config) {
+  switch (typeof config) {
+
+    case 'undefined':
+      return
+
+    case 'object':
+      return config
+
+    case 'function':
+      return config(route)
+
+    case 'boolean':
+      if (!config) {
+        return
+      }
+      if (!component.props) {
+        return
+      }
+      const props = {}
+      for (const prop in route.params) {
+        const value = route.params[prop]
+        if (hasProp(component, prop)) {
+          const propType = component.props[prop].type
+          if (propType === null || propType === String) {
+            props[prop] = value
+          } else if (propType === Number && value.match(/^-?([0-9]+|[0-9]*\.[0-9]+)$/)) {
+            props[prop] = parseFloat(value)
+          }
+        }
+      }
+      return props
+    default:
+      warn(false, `props in "${route.path}" is a ${typeof config}, expecting an object, function or boolean.`)
+  }
+}
+
+function hasProp (component, prop) {
+  if (!component.props) {
+    return false
+  }
+  return typeof component.props[prop] !== 'undefined'
+}

test/e2e/specs/route-props.js

@@ -0,0 +1,29 @@
+module.exports = {
+  'route-props': function (browser) {
+    browser
+    .url('http://localhost:8080/route-props/')
+      .waitForElementVisible('#app', 1000)
+      .assert.count('li a', 5)
+
+      .assert.urlEquals('http://localhost:8080/route-props/')
+      .assert.containsText('.hello', 'Hello Vue!')
+
+      .click('li:nth-child(2) a')
+      .assert.urlEquals('http://localhost:8080/route-props/hello/you')
+      .assert.containsText('.hello', 'Hello you')
+
+      .click('li:nth-child(3) a')
+      .assert.urlEquals('http://localhost:8080/route-props/static')
+      .assert.containsText('.hello', 'Hello world')
+
+      .click('li:nth-child(4) a')
+      .assert.urlEquals('http://localhost:8080/route-props/dynamic/1')
+      .assert.containsText('.hello', 'Hello ' + ((new Date()).getFullYear() + 1)+ '!')
+
+      .click('li:nth-child(5) a')
+      .assert.urlEquals('http://localhost:8080/route-props/calculator/2/3')
+      .assert.containsText('.calculator_add', '2 + 3 = 5')
+      .assert.containsText('.calculator_multiply', '2 * 3 = 6')
+      .end()
+  }
+}