docs: meta, scroll, lazy loading

Author: yyx990803

docs/en/SUMMARY.md

@@ -12,9 +12,10 @@
   - [Named Routes](essentials/named-routes.md)
   - [Named Views](essentials/named-views.md)
   - [Redirect and Alias](essentials/redirect-and-alias.md)
-  - [Server Config for History Mode](essentials/server.md)
+  - [HTML5 History Mode](essentials/history-mode.md)
 - Advanced
   - [Navigation Hooks](advanced/navigation-guards.md)
+  - [Route Meta Fields](advanced/meta.md)
   - [Transitions](advanced/transitions.md)
   - [Data Fetching](advanced/data-fetching.md)
   - [Scroll Behavior](advanced/scroll-behavior.md)

docs/en/advanced/lazy-loading.md

@@ -1,84 +1,45 @@
 # Lazy Loading Routes
 
-When you are using bundlers like Webpack or Browserify, it's trivially easy to
-lazy-load a route component using Vue.js' built-in
-[async component functionality](http://vuejs.org/guide/components.html#Async-Components).
-Instead of directly defining your route component, you define it as a function
-that will asynchronously resolve the actual component definition:
+When building apps with a bundler, the JavaScript bundle can become quite large and thus affecting page load time. It would be more efficient if we can split each route's components into a separate chunk, and only load them when the route is visited.
 
-``` js
-const router = new VueRouter({
-  routes: [
-    {
-      path: '/async',
-      component: function (resolve) {
-        // somehow retrieve your component definition from server...
-        resolve(MyComponent)
-      }
-    }
-  ]
-})
-```
+Combining Vue's [async component feature](http://vuejs.org/guide/components.html#Async-Components) and Webpack's [code splitting feature](https://webpack.github.io/docs/code-splitting.html), it's trivially easy to
+lazy-load route components.
 
-Now, manually handling component retrieval is less than ideal, but bundlers like
-Webpack & Browserify both provides ways to make it easier.
+All we need to do is defining our route components as async components:
 
-### Webpack
+``` js
+const Foo = resolve => {
+  // require.ensure is Webpack's special syntax for a code-split point.
+  require.ensure(['./Foo.vue'], () => {
+    resolve(require('./Foo.vue'))
+  })
+}
+```
 
-Webpack has built-in support for async code-splitting. You can use the AMD-like
-`require` syntax in your code to indicate an async code-split point:
+There's also an alternative code-split syntax using AMD style require, so this can be simplified to:
 
 ``` js
-require(['./MyComponent.vue'], function (MyComponent) {
-  // code here runs after MyComponent.vue is asynchronously loaded.
-})
+const Foo = resolve => require(['./Foo.vue'], resolve)
 ```
 
-Combined with the router it can simply look like this:
+Nothing needs to change in the route config, just use `Foo` as usual:
 
 ``` js
 const router = new VueRouter({
   routes: [
-    {
-      path: '/async',
-      component: function (resolve) {
-        require(['./MyComponent.vue'], resolve)
-      }
-    }
+    { path: '/foo', component: Foo }
   ]
 })
 ```
 
-Now, `MyComponent.vue`, along with any dependencies that are only used by itself,
-will be loaded asynchronously only when the route `/async` needs to be rendered.
-
-### Browserify
+### Grouping Components in the Same Chunk
 
-TODO make this part as easy as wepack's
-
-It's a bit more tricky to achieve the same with Browserify, but it's possible
-with the
-[`partition-bundle` plugin](https://github.com/substack/browserify-handbook/blob/master/readme.markdown#partition-bundle).
-You will have to manually declare your bundle mappings in a `json` file:
-
-``` json
-{
-  "main.js": ["./main.js"],
-  "my-component.js": ["./MyComponent.vue"]
-}
-```
-
-Then in `main.js` you would do something similar, using the `loadjs` function instead of `require`:
+Sometimes we may want to group all the components nested under the same route into the same async chunk. To achieve that we need to use [named chunks](https://webpack.github.io/docs/code-splitting.html#named-chunks) by providing a chunk name to `require.ensure` as the 3rd argument:
 
 ``` js
-const router = new VueRouter({
-  routes: [
-    {
-      path: '/async',
-      component: function (resolve) {
-        loadjs(['./MyComponent.vue'], resolve)
-      }
-    }
-  ]
-})
+const Foo = r => require.ensure([], () => r(require('./Foo.vue')), 'group-foo')
+const Bar = r => require.ensure([], () => r(require('./Bar.vue')), 'group-foo')
+const Baz = r => require.ensure([], () => r(require('./Baz.vue')), 'group-foo')
 ```
+
+Webpack will group any async module with the same chunk name into the same async chunk - this also means we don't need to explicitly list dependencies for `require.ensure` anymore (thus passing an empty array).

docs/en/advanced/meta.md

@@ -0,0 +1,51 @@
+# Route Meta Fields
+
+You can include a `meta` field when defining a route:
+
+``` js
+const router = new VueRouter({
+  routes: [
+    {
+      path: '/foo',
+      component: Foo,
+      children: [
+        {
+          path: 'bar',
+          component: Bar,
+          // a meta field
+          meta: { requiresAuth: true }
+        }
+      ]
+    }
+  ]
+})
+```
+
+So how do we access this `meta` field?
+
+First, each route object in the `routes` configuration is called a **route record**. Route records may be nested. Therefore when a route is matched, it can potentially match more than one route record.
+
+For example, with the above route config, the URL `/foo/bar` will match both the parent route record and the child route record.
+
+All route records matched by a route are exposed on the `$route` object (and also route objects in navigation guards) as the `$route.matched` Array. Therefore, we will need to iterate over `$route.matched` to check for meta fields in route records.
+
+An example use case is checking for a meta field in the global navigation guard:
+
+``` js
+router.beforeEach((route, redirect, next) => {
+  if (route.matched.some(record => record.meta.requiresAuth)) {
+    // this route requires auth, check if logged in
+    // if not, redirect to login page.
+    if (!auth.loggedIn()) {
+      redirect({
+        path: '/login',
+        query: { redirect: route.fullPath }
+      })
+    } else {
+      next()
+    }
+  } else {
+    next()
+  }
+})
+```

docs/en/advanced/scroll-behavior.md

@@ -0,0 +1,61 @@
+# Scroll Behavior
+
+When using client-side routing, we may want to scroll to top when navigating to a new route, or preserve the scrolling position of history entries just like real page reload does. `vue-router` allows you to achieve these and even better, allows you to completely customize the scroll behavior on route navigation.
+
+**Note: this feature only works in HTML5 history mode.**
+
+When creating the router instance, you can provide the `scrollBehavior` function:
+
+``` js
+const router = new VueRouter({
+  routes: [...],
+  scrollBehavior (to, from, savedPosition) {
+    // return desired position
+  }
+})
+```
+
+The `scrollBehavior` function receives the `to` and `from` route objects. The third argument, `savedPosition`, is only available if this is a `popstate` navigation (triggered by the browser's back/forward buttons).
+
+The function can return a scroll position object. The object could be in the form of:
+
+- `{ x: number, y: number }`
+- `{ selector: string }`
+
+If a falsy value or an empty object is returned, no scrolling will happen.
+
+For example:
+
+``` js
+scrollBehavior (to, from, savedPosition) {
+  return { x: 0, y: 0 }
+}
+```
+
+This will simply make the page scroll to top for all route navigations.
+
+Returning the `savedPosition` will result in a native-like behavior when navigating with back/forward buttons:
+
+``` js
+scrollBehavior (to, from, savedPosition) {
+  if (savedPosition) {
+    return savedPosition
+  } else {
+    return { x: 0, y: 0 }
+  }
+}
+```
+
+If you want to simulate the "scroll to anchor" behavior:
+
+``` js
+scrollBehavior (to, from, savedPosition) {
+  if (to.hash) {
+    return {
+      selector: to.hash
+    }
+  }
+}
+```
+
+We can also use [route meta fields](meta.md) to implement fine-grained scroll behavior control. Check out a full example [here](https://github.com/vuejs/vue-router/blob/next/examples/scroll-behavior/app.js).

docs/en/essentials/server.md renamed to docs/en/essentials/history-mode.md

@@ -1,10 +1,17 @@
-# Server Configuration for History Mode
+# HTML5 History Mode
 
 The default mode for `vue-router` is hash mode - it uses the URL hash to simulate a full URL so that the page won't be reloaded when the URL changes.
 
-To get rid of the ugly hash, we can use the HTML5 `history.pushState` API to achieve URL navigation without page reload. But for this mode to work properly, you need to configure your server properly.
+To get rid of the ugly hash, we can use the router's **history mode**, which leverages the `history.pushState` API to achieve URL navigation without page reload:
 
-Because when using history mode, the URL will look like a normal url, e.g. `http://yoursite.com/user/id`. Since our app is a single page client side app, without proper server configuration the users will get a 404 if they visit that URL directly.
+``` js
+const router = new VueRouter({
+  mode: 'history',
+  routes: [...]
+})
+```
+
+But for this mode to work properly, you need to configure your server properly. When using history mode, the URL will look like a normal url, e.g. `http://yoursite.com/user/id`. Since our app is a single page client side app, without proper server configuration the users will get a 404 if they visit that URL directly.
 
 Therefore you need to add a catch-all fallback route to your server: if the URL doesn't match any static assets, it should serve the same `index.html` page that your app lives in.