docs: nested routes & route object

Author: yyx990803

docs/SUMMARY.md

@@ -3,7 +3,7 @@
 - [Installation](installation.md)
 - [Basic Usage](basic.md)
 - [Nested Routes](nested.md)
-- [Route Context](route.md)
+- [Route Object](route.md)
 - [router-view](view.md)
 - [v-link](link.md)
 - [Router Options](options.md)

docs/nested.md

@@ -1 +1,79 @@
 # Nested Routes
+
+Mapping nested routes to nested components is a common need, and it is also very simple with vue-router.
+
+Suppose we have the following app:
+
+``` html
+<div id="app">
+  <router-view></router-view>
+</div>
+```
+
+The `<router-view>` here is a top-level outlet. It renders the component matched by a top level route:
+
+``` js
+router.map({
+  '/foo': {
+    // Foo is rendered when /foo is matched
+    component: Foo
+  }
+})
+```
+
+Similarly, a rendered component can also contain its own, nested `<router-view>`. For example, if we add one inside the `Foo` component's template:
+
+``` js
+var Foo = Vue.extend({
+  template:
+    '<div class="foo">' +
+      '<h2>This is Foo!</h2>' +
+      '<router-view></router-view>' + // <- nested outlet
+    '</div>'
+})
+```
+
+To render components into this nested outlet, we need to update our route config:
+
+``` js
+router.map({
+  '/foo': {
+    component: Foo,
+    // add a subRoutes map under /foo
+    subRoutes: {
+      '/bar': {
+        // Bar will be rendered inside Foo's <router-view>
+        // when /foo/bar is matched
+        component: Bar
+      },
+      '/baz': {
+        // Same for Baz, but only when /foo/baz is matched
+        component: Baz
+      }
+    }
+  }
+})
+```
+
+Now, with the above configuration, when you visit `/foo`, nothing will be rendered inside `Foo`'s outlet, because no sub route is matched. Maybe you do want to render something there. In such case you can provide a `/` subroute in this case:
+
+``` js
+router.map({
+  '/foo': {
+    component: Foo,
+    subRoutes: {
+      '/': {
+        // This component will be rendered into Foo's <router-view>
+        // when /foo is matched. Using an inline component definition
+        // here for convenience.
+        component: {
+          template: '<p>Default sub view for Foo</p>'
+        }
+      },
+      // other sub routes...
+    }
+  }
+})
+```
+
+A working demo of this example can be found [here](http://jsfiddle.net/yyx990803/naeg67da/).

docs/route.md

@@ -1 +1,64 @@
-# Route Context
+# Route Object
+
+Vue-router supports matching paths that contain dynamic segments, star segments and query strings. All these information of a parsed route will be accessible on the exposed **Route Context Objects** (we will just call them "route" objects from now on). The route object will be injected into every component in a vue-router-enabled app as `this.$route`, and will be updated whenever a route transition is performed.
+
+A route object exposes the following properties:
+
+- **$route.path**
+
+  A string that equals the path of the current route, always resolved as an absolute path. e.g. `"/foo/bar"`.
+
+- **$route.params**
+
+  An object that contains key/value pairs of dynamic segments and star segments. More details below.
+
+- **$route.query**
+
+  An object that contains key/value pairs of the query string. For example, for a path `/foo?user=1`, we get `$route.query.user == 1`.
+
+### Using in Templates
+
+You can directly bind to the `$route` object inside your component templates. For example:
+
+``` html
+<div>
+  <p>Current route path: {{$route.path}}</p>
+  <p>Current route params: {{$route.params | json}}</p>
+</div>
+```
+
+### Dynamic Segments
+
+Dynamic segments can be defined in the form of path segments with a leading colon, e.g. in `user/:username`, `:username` is the dynamic segment. It will match paths like `/user/foo` or `/user/bar`. When a path containing a dynamic segment is matched, the dynamic segments will be available inside `$route.params`.
+
+Example Usage:
+
+``` js
+router.map({
+  '/user/:username': {
+    component: {
+      template: '<p>username is {{$route.params.username}}</p>'
+    }
+  }
+})
+```
+
+A path can contain multiple dynamic segments, and each of them will be stored as a key/value pair in `$route.params`.
+
+Examples:
+
+| pattern | matched path | $route.params |
+|---------|------|--------|
+| /user/:username | /user/evan | `{ username: 'evan' }` |
+| /user/:username/post/:post_id | /user/evan/post/123 | `{ username: 'evan', post_id: 123 }` |
+
+### Star Segments
+
+While dynamic segments can correspond to only a single segment in a path, star segments is basically the "greedy" version of it. For example `/foo/*bar` will match anything that starts with `/foo/`. The part matched by the star segment will also be available in `$route.params`.
+
+Examples:
+
+| pattern | matched path | $route.params |
+|---------|------|--------|
+| /user/*any | /user/a/b/c | `{ any: 'a/b/c' }` |
+| /foo/*any/bar | /foo/a/b/bar | `{ any: 'a/b' }` |