docs: matching & nested

Author: yyx990803

docs/en/SUMMARY.md

@@ -6,9 +6,11 @@
 - [Installation](installation.md)
 - Essentials
   - [Getting Started](essentials/getting-started.md)
+  - [Dynamic Route Matching](essentials/matching.md)
   - [Nested Routes](essentials/nested-routes.md)
   - [Redirect and Alias](essentials/redirect-and-alias.md)
   - [Programmatic Navigation](essentials/navigation.md)
+  - [Server Config for History Mode](essentials/server.md)
 - Advanced
   - [Named Routes](advanced/named-routes.md)
   - [Named Views](advanced/named-views.md)
@@ -25,4 +27,3 @@
   - [Router Instance](api/router-instance.md)
   - [The $route Object](api/route-object.md)
   - [Component Route Hooks](api/component-hooks.md)
-  - [Route Matching Rules](api/matching.md)

docs/en/api/matching.md

@@ -1,6 +1,8 @@
 # Getting Started
 
-Creating a Single-page Application with Vue.js + vue-router is dead simple. With Vue.js, we are already dividing our application into components. When adding vue-router to the mix, all we need to do is map our components to the routes and let vue-router know where to render them. Here's a basic example:
+> We will be using [ES2015](https://github.com/lukehoban/es6features) in the code samples in the guide.
+
+Creating a Single-page Application with Vue.js + vue-router is dead simple. With Vue.js, we are already composing our application with components. When adding vue-router to the mix, all we need to do is map our components to the routes and let vue-router know where to render them. Here's a basic example:
 
 ### HTML
 
@@ -23,49 +25,40 @@ Creating a Single-page Application with Vue.js + vue-router is dead simple. With
 ### JavaScript
 
 ``` js
-// 1. Use plugin.
-// This installs <router-view> and <router-link>,
-// and injects $router and $route to all router-enabled child components
-Vue.use(VueRouter)
+// 0. If using a module system, call Vue.use(VueRouter)
 
-// 2. Define route components.
+// 1. Define route components.
 // These can be imported from other files
-var Foo = { template: '<div>foo</div>' }
-var Bar = { template: '<div>bar</div>' }
+const Foo = { template: '<div>foo</div>' }
+const Bar = { template: '<div>bar</div>' }
 
-// 3. Define some routes
+// 2. Define some routes
 // Each route should map to a component. The "component" can
 // either be an actual component constructor created via
 // Vue.extend(), or just a component options object.
 // We'll talk about nested routes later.
-var routes = [
+const routes = [
   { path: '/foo', component: Foo },
   { path: '/bar', component: Bar }
 ]
 
-// 4. Create the router instance and pass the `routes` option
+// 3. Create the router instance and pass the `routes` option
 // You can pass in additional options here, but let's
 // keep it simple for now.
-var router = new VueRouter({
-  routes: routes
+const router = new VueRouter({
+  routes // short for routes: routes
 })
 
-// 5. Create and mount the root instance.
+// 4. Create and mount the root instance.
 // Make sure to inject the router with the router option to make the
 // whole app router-aware.
-new Vue({
-  router: router
+const app = new Vue({
+  router
 }).$mount('#app')
 
 // Now the app has started!
 ```
 
 You can also checkout this example [live](http://jsfiddle.net/yyx990803/xgrjzsup/).
 
-In addition:
-
-- Notice that a `<router-link>` automatically gets the `.router-link-active` class when its target route is matched. You can learn more about it in its [API reference](../api/router-link.md).
-
-- The root Vue instance will be available as `router.app` once the initial render is complete. You can learn more about the properties and methods available on the router instance [here](../api/router-instance.md).
-
-- The router instance will be available in all descendants of the root instance as `this.$router`. An object representing the current route state will also be available as [this.$route](../api/route-object.md).
+Notice that a `<router-link>` automatically gets the `.router-link-active` class when its target route is matched. You can learn more about it in its [API reference](../api/router-link.md).

docs/en/essentials/getting-started.md

@@ -0,0 +1,45 @@
+# Dynamic Route Matching
+
+Very often we will need to map routes with the given pattern to the same component. For example we may have a `User` component which should be rendered for all users but with different user IDs. In `vue-router` we can use a dynamic segment in the path to achieve that:
+
+``` js
+const User = {
+  template: '<div>User</div>'
+}
+
+const router = new VueRouter({
+  routes: [
+    // dynamic segments start with a colon
+    { path: '/user/:id', component: User }
+  ]
+})
+```
+
+Now URLs like `/user/foo` and `/user/bar` will both map to the same route.
+
+A dynamic segment is denoted by a colon `:`. When a route is matched, the value of the dynamic segments will be exposed as `this.$route.params` in every component. Therefore, we can render the current user ID by updating `User`'s template to this:
+
+``` js
+const User = {
+  template: '<div>User {{ $route.params.id }}</div>'
+}
+```
+
+You can checkout a live example [here](http://jsfiddle.net/yyx990803/4xfa2f19/).
+
+You can have multiple dynamic segments in the same route, and they will map to corresponding fields on `$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 }` |
+
+In addition to `$route.params`, the `$route` object also exposes other useful information such as `$route.query` (if there is a query in the URL), `$route.hash`, etc. You can check out the full details in the [API Reference](../api/route-object.md).
+
+### Advanced Matching Patterns
+
+`vue-router` uses [path-to-regexp](https://github.com/pillarjs/path-to-regexp) as its path matching engine, so it supports many advanced matching patterns such as optional dynamic segments, zero or more / one or more requirements, and even custom regex patterns. Check out its [documentation](https://github.com/pillarjs/path-to-regexp#parameters) for these advanced patterns, and [this example](https://github.com/vuejs/vue-router/blob/next/examples/route-matching/app.js) of using them in `vue-router`.
+
+### Matching Priority
+
+Sometimes the same URL may be matched by multiple routes. In such a case the matching priority is determined by the order of route definition: the earlier a route is defined, the higher priority it gets.

docs/en/essentials/matching.md

@@ -1,41 +1,47 @@
 # Nested Routes
 
-Mapping nested routes to nested components is a common need, and it is also very
-simple with vue-router.
+Real app UIs are usually composed of components that are nested multiple levels deep. It is also very common that the segments of a URL corresponds to a certain structure of nested components, for example:
 
-Suppose we have the following app:
+```
+/user/foo/profile                     /user/foo/posts
++------------------+                  +-----------------+
+| User             |                  | User            |
+| +--------------+ |                  | +-------------+ |
+| | Profile      | |  +------------>  | | Posts       | |
+| |              | |                  | |             | |
+| +--------------+ |                  | +-------------+ |
++------------------+                  +-----------------+
+```
+
+With `vue-router`, it is very simple to express this relationship using nested route configurations.
+
+Given the app we created in the last chapter:
 
 ``` 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
-var Foo = { template: '<div>Foo</div>' }
+const User = {
+  template: '<div>User {{ $route.params.id }}</div>'
+}
+
 const router = new VueRouter({
   routes: [
-    // Foo is rendered when /foo is matched
-    {
-      path: '/foo',
-      component: Foo
-    }
+    { path: '/user/:id', component: User }
   ]
 })
 ```
 
-Similarly, a rendered component can also contain its own, nested
-`<router-view>`. For example, if we add one inside the `Foo` component's
-template:
+The `<router-view>` here is a top-level outlet. It renders the component matched by a top level route. Similarly, a rendered component can also contain its own, nested `<router-view>`. For example, if we add one inside the `User` component's template:
 
 ``` js
-var Foo = {
+const User = {
   template: `
-    <div class="foo">
-      <h2>This is Foo!</h2>
+    <div class="user">
+      <h2>User {{ $route.params.id }}</h2>
       <router-view></router-view>
     </div>
   `
@@ -48,50 +54,45 @@ option in `VueRouter` constructor config:
 ``` js
 const router = new VueRouter({
   routes: [
-    {
-      path: '/foo',
-      component: Foo
+    { path: '/user/:id', component: User,
       children: [
         {
-          // Bar will be rendered inside Foo's <router-view>
-          // when /foo/bar is matched
-          path: '/bar',
-          component: Bar
+          // UserProfile will be rendered inside User's <router-view>
+          // when /user/:id/profile is matched
+          path: 'profile',
+          component: UserProfile
         },
         {
-          // Bar will be rendered inside Foo's <router-view>
-          // when /foo/bar is matched
-          path: '/bar',
-          component: Bar
+          // UserPosts will be rendered inside User's <router-view>
+          // when /user/:id/posts is matched
+          path: 'posts',
+          component: UserPosts
         }
       ]
     }
   ]
 })
 ```
 
-As you can see the `children` option has pretty much the same format as the
-`routes` option. Therefore, you can keep nesting views as much as you need.
+As you can see the `children` option is just another Array of route configuration objects like `routes` itself. Therefore, you can keep nesting views as much as you need.
 
-At this point, 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 an empty subroute path:
+At this point, with the above configuration, when you visit `/user/foo`, nothing will be rendered inside `User`'s outlet, because no sub route is matched. Maybe you do want to render something there. In such case you can provide an empty subroute path:
 
 ``` js
 const router = new VueRouter({
   routes: [
     {
-      path: '/foo',
-      component: Foo
+      path: '/user/:id', component: User,
       children: [
-        // Default will be rendered inside Foo's <router-view>
-        // when /foo is matched
-        { path: '', component: Default },
-        // other sub routes
+        // UserHome will be rendered inside User's <router-view>
+        // when /user/:id is matched
+        { path: '', component: UserHome },
+
+        // ...other sub routes
       ]
     }
   ]
 })
 ```
 
-A working demo of this example can be found [here](https://jsfiddle.net/posva/wuczg0av/).
+A working demo of this example can be found [here](http://jsfiddle.net/yyx990803/L7hscd8h/).

docs/en/essentials/nested-routes.md

@@ -2,7 +2,16 @@
 
 ### Direct Download / CDN
 
-Unpkg.com provides NPM-based CDN links. The latest release is available at [https://unpkg.com/vue-router@latest/dist/vue-router.js](https://unpkg.com/vue-router@latest/dist/vue-router.js) - you can also specify any other versions/tags available on NPM!
+[https://unpkg.com/vue-router](https://unpkg.com/vue-router)
+
+[Unpkg.com](https://unpkg.com) provides NPM-based CDN links. The above link will always point to the latest release on NPM. You can also use a specific version/tag via URLs like `https://unpkg.com/[email protected]`.
+
+Include `vue-router` after Vue and it will install itself automatically:
+
+``` html
+<script src="/path/to/vue.js"></script>
+<script src="/path/to/vue-router.js"></script>
+```
 
 ### NPM
 
@@ -19,8 +28,7 @@ import VueRouter from 'vue-router'
 Vue.use(VueRouter)
 ```
 
-You don't need to do this when using the standalone build because it installs
-itself automatically.
+You don't need to do this when using global script tags.
 
 ### Dev Build