docs wip

Author: yyx990803

docs/SUMMARY.md

@@ -1,4 +1,4 @@
-# Table of Contents
+# vue-router documentation
 
 - [Installation](installation.md)
 - [Basic Usage](basic.md)
@@ -8,7 +8,7 @@
 - [router-view](view.md)
 - [v-link](link.md)
 - [Transition Pipeline](pipeline/README.md)
-  - [Transition Object](pipeline/transition.md)
+  - [Transition Hooks](pipeline/hooks.md)
   - [data](pipeline/data.md)
   - [activate](pipeline/activate.md)
   - [deactivate](pipeline/deactivate.md)

docs/basic.md

@@ -20,7 +20,7 @@ Creating a Single-page Application with Vue.js + vue-router is dead simple. With
 ### JavaScript
 
 ``` js
-// define some components
+// Define some components
 var Foo = Vue.extend({
     template: '<p>This is foo!</p>'
 })
@@ -29,19 +29,21 @@ var Bar = Vue.extend({
     template: '<p>This is bar!</p>'
 })
 
-// the router needs a root component to render.
-// for demo purposes, we will just use an empty one
+// The router needs a root component to render.
+// For demo purposes, we will just use an empty one
 // because we are using the HTML as the app template.
 var App = Vue.extend({})
 
-// create a router instance.
-// you can pass in additional options here, but let's
+// Create a router instance.
+// You can pass in additional options here, but let's
 // keep it simple for now.
 var router = new VueRouter()
 
-// define some routes.
-// each route should map to a component.
-// we'll talk about nested routes later.
+// 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.
 router.map({
     '/foo': {
         component: Foo
@@ -51,8 +53,8 @@ router.map({
     }
 })
 
-// now we can start the app!
-// router will create an instance of App and mount to
+// Now we can start the app!
+// The router will create an instance of App and mount to
 // the element matching the selector #app.
 router.start(App, '#app')
 ```

docs/pipeline/01.png

@@ -1,28 +1,49 @@
 # Transition Pipeline
 
-Route components can configure its transition and data-loading behavior by implementing appropriate transition pipeline hooks. These hooks include:
+To better understand the pipeline of a route transition, let's imagine we have a router-enabled app, already rendered with three nested `<router-view>` with the path `/a/b/c`:
 
-- `data`
-- `activate`
-- `deactivate`
-- `canActivate`
-- `canDeactivate`
-- `canReuse`
+![](01.png)
 
-When a route transition is triggered, these hooks will be called in a specific order on affected view components.
+And then, the user navigates to a new path, `/a/d/e`, which requires us to update our rendered component tree to a new one:
 
-A route transition can be divided into three phases:
+![](02.png)
+
+How would we go about that? There are a few things we need to do here:
+
+1. We can potentially reuse component A, because it remains the same in the post-transition component tree.
+
+2. We need to deactivate and remove component B and C.
+
+3. We need to create and activate component D and E.
+
+4. Before we actually perform step 2 & 3, we also want to make sure this transition is valid - that is, to make sure that all components involved in this transition **can** be deactivated/activated as desired.
+
+### Transition Phases
+
+With these in mind, we can divide a route transition pipeline into three phases:
 
 1. **Reusability phase:**
 
-  Check if any component in the current view hierarchy can be reused in the new one.
+  Check if any component in the current view hierarchy can be reused in the new one. This is done by comparing the two component trees, find out common components, and then check their reusability. By default, every component is reusable unless configured otherwise.
+
+  ![reusability phase](03.png)
 
 2. **Validation phase:**
 
-  Check if all current components can be deactivated, and if all new components can be activated.
+  Check if all current components can be deactivated, and if all new components can be activated. This is by checking and calling their `canDeactivate` and `canActivate` route config hooks.
+
+  ![validation phase](04.png)
+
+  Note the `canDeactivate` check bubbles bottom-up, while the `canActivate` check is top-down.
+
+  Any of these hooks can potentially abort the transition. If a transition is aborted during the validation phase, the router preserve current app state and restore the previous path.
 
 3. **Activation phase:**
 
-  Deactivate current components and activate new components.
+  Once all validation hooks have been called and none of them aborts the transition, the transition is now said to be valid. The router will now deactivate current components and activate new components.
+
+  ![activation phase](05.png)
+
+  These hooks are called in the same order of the validation hooks, but their purpose is to give you the chance to do cleanup / preparation work before the visible component switching is executed. The interface will not update until all of the affected components' `deactivate` and `activate` hooks have resolved.
 
-The diagram below demonstrates the full pipeline of a route transition:
+We will talk about transition hooks in detail next.

docs/pipeline/02.png

@@ -0,0 +1,93 @@
+# Transition Hooks
+
+A `<router-view>` component involved in a transition can control / react to the transition by implementing appropriate transition pipeline hooks. These hooks include:
+
+- `data`
+- `activate`
+- `deactivate`
+- `canActivate`
+- `canDeactivate`
+- `canReuse`
+
+You can implement these hooks under your component's `route` option:
+
+``` js
+Vue.component('hook-example', {
+  // ... other options
+  route: {
+    activate: function (transition) {
+      console.log('hook-example activated!')
+      transition.next()
+    },
+    deactivate: function (transition) {
+      console.log('hook-example deactivated!')
+      transition.next()
+    }
+  }
+})
+```
+
+### The Transition Object
+
+Each transition hook will receive a `transition` object as the only argument. The transition object exposes the following properties & methods:
+
+- **transition.from**
+
+  A [route object](../route.html) representing the route we are transitioning from.
+
+- **transition.to**
+
+  A route object representing the target path.
+
+- **transition.next()**
+
+  Call this method to progress to the next step of the transition.
+
+- **transition.abort([reason])**
+
+  Call this method to cancel / reject the transition.
+
+- **transition.redirect(path)**
+
+  Cancel current transition and redirect to a different target route instead.
+
+All transition hooks are considered asynchronous by default. In order to signal the transition to progress, you have three options:
+
+1. Explicitly call one of `next`, `abort` or `redirect`.
+
+2. Return a Promise. Details below.
+
+3. For validation hooks (`canActivate` and `canDeactivate`), you can synchronously return a Boolean value.
+
+### Returning Promise in Hooks
+
+When you return a Promise in a transition hook, `transition.next` will be called for you when the Primise resolves. If the Promise is rejected during validation phase, it will call `transition.abort`; if it is rejected during activation phase, it will call `transition.next`.
+
+For validation hooks (`canActivate` and `canDeactivate`), if the Promise's resolved value is falsy, it will also abort the transition.
+
+If a rejected promise has an uncaught error, it will be thrown unless you suppress it with the `suppressTransitionError` option when creating the router.
+
+**Example:**
+
+``` js
+// inside component definition
+route: {
+  canActivate: function () {
+    // assuming the service returns a Promise that
+    // resolve to either `true` or `false`.
+    return authenticationService.isLoggedIn()
+  },
+  activate: function (transition) {
+    return messageService
+      .fetch(transition.to.params.messageId)
+      .then((message) => {
+        // set the data once it arrives.
+        // the component will not display until this
+        // is done.
+        this.message = message
+      })
+  }
+}
+```
+
+We are asynchronously fetching data in the `activate` hook here just for the sake of an example; Note that we also have the [`data` hook](data.html) which is in general more appropriate for this purpose.