docs: data fetching

Author: yyx990803

docs/en/advanced/data-fetching.md

@@ -1,19 +1,37 @@
 # Data Fetching
 
-Sometimes you need to fetch data from the server before rendering a route. For
-example, before visiting a user profile, you have to fetch his data from the
-server. We can achieve this in two different ways. Each way provide a different
-UX approach and both of them are valid designs.
+Sometimes you need to fetch data from the server when a route is activated. For example, before rendering a user profile, you need to fetch the user's data from the server. We can achieve this in two different ways:
 
+- **Fetching After Navigation**: perform the navigation first, and fetch data in the incoming component's lifecycle hook. Display a loading state while data is being fetched.
 
-## Fetching before navigation
+- **Fetching Before Navigation**: Fetch data before navigation in the route enter guard, and perform the navigation after data has been fetched.
 
-This method consists on fetching the data before actually navigating to the new
-route. For those using vue-router 1, this works as the `activate` hook. In
-vue-router 2 you use the `beforeRouteEnter` hook to control the navigation flow.
-You get access to the `route`, a `redirect` function and a `next` callback to
-let the navigation end. Not calling the `next` callback will simply cancel the
-navigation. Note that this hook is
+Technically, both are valid choices - it ultimately depends on the user experience you are aiming for.
+
+## Fetching After Navigation
+
+When using this approach, we navigate and render the incoming component immediately, and fetch data in the component's `created` hook. It gives us the opportunity to display a loading state while the data is being fetched over the network, and we can also handle loading differently for each view.
+
+Let's assume we have a `Post` component that needs to fetch the data for a post based on `$route.params.id`:
+
+``` html
+<template>
+  <div class="post">
+    <div class="loading" v-if="loading">
+      Loading...
+    </div>
+
+    <div v-if="error" class="error">
+      {{ error }}
+    </div>
+
+    <div v-if="post" class="content">
+      <h2>{{ post.title }}</h2>
+      <p>{{ post.body }}</p>
+    </div>
+  </div>
+</template>
+```
 
 ``` js
 export default {
@@ -24,75 +42,63 @@ export default {
       error: null
     }
   },
-  beforeRouteEnter (route, redirect, next) {
+  created () {
     // fetch the data when the view is created and the data is
     // already being observed
-    this.fetchData(route.params.id, next)
+    this.fetchData()
   },
   watch: {
     // call again the method if the route changes
-    $route () {
-      this.fetchData(this.$route.params.id)
-    }
+    '$route': 'fetchData'
   },
   methods: {
-    fetchData (id, cb) {
+    fetchData () {
       this.error = this.post = null
       this.loading = true
-      getPost(id, (err, post) => {
+      // replace getPost with your data fetching util / API wrapper
+      getPost(this.$route.params.id, (err, post) => {
         this.loading = false
         if (err) {
           this.error = err.toString()
         } else {
           this.post = post
         }
-        cb && cb()
       })
     }
   }
 }
 ```
 
-The user still can use the application while the resource is being fetched. It
-is therefore recommended to show him with a progress bar or any other indicator
-that the web site is waiting for data. If, during this time, the user navigates
-somewhere else by clicking on a link, the navigation waiting for data will never
-take place.
-
-## Fetching inside the view
+## Fetching Before Navigation
 
-This method consists on fetching data during the component lifecycle. It allows
-you to define how the content of your view is presented while the resources are
-loading. Using this approach let you handle how loading in handled differently
-for each view.
-
-Replacing `beforeRouteEnter` with `created` is almost all you need to do to
-switch to the other fetching method.
+With this approach we fetch the data before actually navigating to the new
+route. We can perform the data fetching in the `beforeRouteEnter` guard in the incoming component, and only call `next` when the fetch is complete:
 
 ``` js
 export default {
   data () {
     return {
-      loading: false,
       post: null,
       error: null
     }
   },
-  created () {
-    // fetch the data when the view is created and the data is
-    // already being observed
-    this.fetchData()
+  beforeRouteEnter (route, redirect, next) {
+    getPost(route.params.id, (err, post) => {
+      if (err) {
+        // display some global error message
+      } else {
+        next(vm => {
+          vm.post = post
+        })
+      }
+    })
   },
+  // when route changes when this component is already rendered,
+  // the logic will be slightly different.
   watch: {
-    // call again the method if the route changes
-    '$route': 'fetchData'
-  },
-  methods: {
-    fetchData () {
-      this.error = this.post = null
-      this.loading = true
+    $route () {
+      this.post = null
       getPost(this.$route.params.id, (err, post) => {
-        this.loading = false
         if (err) {
           this.error = err.toString()
         } else {
@@ -104,25 +110,4 @@ export default {
 }
 ```
 
-The component lifecycle will go on and once the data is fetched, the view will update acordingly. This way you can choose what to show while the data is being fetched. Here we're just displaying _Loading..._:
-
-``` html
-<template>
-  <div class="post">
-    <div class="loading" v-if="loading">Loading...</div>
-    <div v-if="error" class="error">
-      {{ error }}
-    </div>
-    <transition name="slide">
-      <!--
-        giving the post container a unique key triggers transitions
-        when the post id changes.
-      -->
-      <div v-if="post" class="content" :key="post.id">
-        <h2>{{ post.title }}</h2>
-        <p>{{ post.body }}</p>
-      </div>
-    </transition>
-  </div>
-</template>
-```
+The user will stay on the current view while the resource is being fetched for the incoming view. It is therefore recommended to display a progress bar or some kind of indicator while the data is being fetched. If the data fetch fails, it's also necessary to display some kind of global warning message.