Merge pull request #37 from vuejs/master

update

Author: dingyiming

src/api/index.md

@@ -347,6 +347,8 @@ type: api
   })
   ```
 
+  <p class="tip">Note that __you should not use an arrow function with the `data` property__ (e.g. `data: () => { return { a: this.myProp }}`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.myProp` will be undefined.</p>
+
 - **See also:** [Reactivity in Depth](/guide/reactivity.html)
 
 ### props
@@ -418,6 +420,8 @@ type: api
 
   Computed properties to be mixed into the Vue instance. All getters and setters have their `this` context automatically bound to the Vue instance.
 
+  <p class="tip">Note that __you should not use an arrow function to define a computed property__ (e.g. `aDouble: () => this.a * 2`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.a` will be undefined.</p>
+
   Computed properties are cached, and only re-computed on reactive dependency changes.
 
 - **Example:**
@@ -458,6 +462,8 @@ type: api
 
   Methods to be mixed into the Vue instance. You can access these methods directly on the VM instance, or use them in directive expressions. All methods will have their `this` context automatically bound to the Vue instance.
 
+  <p class="tip">Note that __you should not use an arrow function to define a method__ (e.g. `plus: () => this.a++`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.a` will be undefined.</p>
+
 - **Example:**
 
   ```js
@@ -488,16 +494,18 @@ type: api
   ``` js
   var vm = new Vue({
     data: {
-      a: 1
+      a: 1,
+      b: 2,
+      c: 3
     },
     watch: {
-      'a': function (val, oldVal) {
+      a: function (val, oldVal) {
         console.log('new: %s, old: %s', val, oldVal)
       },
       // string method name
-      'b': 'someMethod',
+      b: 'someMethod',
       // deep watcher
-      'c': {
+      c: {
         handler: function (val, oldVal) { /* ... */ },
         deep: true
       }
@@ -506,6 +514,8 @@ type: api
   vm.a = 2 // -> new: 2, old: 1
   ```
 
+  <p class="tip">Note that __you should not use an arrow function to define a watcher__ (e.g. `searchQuery: newValue => this.updateAutocomplete(newValue)`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.updateAutocomplete` will be undefined.</p>
+
 - **See also:** [Instance Methods - vm.$watch](#vm-watch)
 
 ## Options / DOM
@@ -559,6 +569,8 @@ type: api
 
 ## Options / Lifecycle Hooks
 
+All lifecycle hooks automatically have their `this` context bound to the instance, so that you can access data, computed properties, and methods. This means __you should not use an arrow function to define a lifecycle method__ (e.g. `created: () => this.fetchTodos()`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.fetchTodos` will be undefined.
+
 ### beforeCreate
 
 - **Type:** `Function`
@@ -829,7 +841,7 @@ type: api
 
 - **Details:**
 
-  The data object that the Vue instance is observing. You can swap it with a new object. The Vue instance proxies access to the properties on its data object.
+  The data object that the Vue instance is observing. The Vue instance proxies access to the properties on its data object.
 
 - **See also:** [Options - data](#data)
 

src/guide/comparison.md

@@ -26,7 +26,7 @@ With that said, we hope you can feel confident in the fairness of the review bel
 
 ### Performance Profiles
 
-In every real-world scenario that we've tested so far, Vue outperforms React by a fair margin (usually at least 20-50% faster, though in some cases much more than that). We could now link to benchmarks - but frankly, all benchmarks are flawed in some way and very few resemble what you'd write in a real application. Instead, let's break it down.
+In every real-world scenario that we've tested so far, Vue outperforms React by a fair margin. If your eyebrows are raising right now, read further. We'll breakdown why (and even include a benchmark developed in collaboration with the React team).
 
 #### Render Performance
 

src/guide/index.md

@@ -6,7 +6,7 @@ order: 2
 
 ## What is Vue.js?
 
-Vue (pronounced /vjuː/, like **view**) is a **progressive framework** for building user interfaces. Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable. The core library is focused on the view layer only, and is very easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with [modern tooling](application.html) and [supporting libraries](https://github.com/vuejs/awesome-vue#libraries--plugins).
+Vue (pronounced /vjuː/, like **view**) is a **progressive framework** for building user interfaces. Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable. The core library is focused on the view layer only, and is very easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with [modern tooling](single-file-components.html) and [supporting libraries](https://github.com/vuejs/awesome-vue#libraries--plugins).
 
 If you are an experienced frontend developer and want to know how Vue compares to other libraries/frameworks, check out the [Comparison with Other Frameworks](comparison.html).
 
@@ -51,34 +51,38 @@ In addition to text interpolation, we can also bind element attributes like this
 
 ``` html
 <div id="app-2">
-  <span v-bind:id="id">Inspect me</span>
+  <span v-bind:title="message">
+    Hover your mouse over me for a few seconds to see my dynamically bound title!
+  </span>
 </div>
 ```
 ``` js
 var app2 = new Vue({
   el: '#app-2',
   data: {
-    id: 'inspect-me'
+    message: 'You loaded this page on ' + new Date()
   }
 })
 ```
 {% raw %}
 <div id="app-2" class="demo">
-  <span v-bind:id="id">Inspect me</span>
+  <span v-bind:title="message">
+    Hover your mouse over me for a few seconds to see my dynamically bound title!
+  </span>
 </div>
 <script>
 var app2 = new Vue({
   el: '#app-2',
   data: {
-    id: 'inspect-me'
+    message: 'You loaded this page on ' + new Date()
   }
 })
 </script>
 {% endraw %}
 
-Here we are encountering something new. The `v-bind` attribute you are seeing is called a **directive**. Directives are prefixed with `v-` to indicate that they are special attributes provided by Vue, and as you may have guessed, they apply special reactive behavior to the rendered DOM. Here it is basically saying "bind this element's `id` attribute to the `id` property on the Vue instance."
+Here we are encountering something new. The `v-bind` attribute you are seeing is called a **directive**. Directives are prefixed with `v-` to indicate that they are special attributes provided by Vue, and as you may have guessed, they apply special reactive behavior to the rendered DOM. Here it is basically saying "keep this element's `title` attribute up-to-date with the `message` property on the Vue instance."
 
-Use the browser devtools to inspect the element above - you should see that it has the id `inspect-me`. And yes, it would update if you modify `app2.id` in the console.
+If you open up your JavaScript console again and enter `app2.message = 'some new message'`, you'll once again see that the bound HTML - in this case the `title` attribute - has been updated.
 
 ## Conditionals and Loops
 

src/guide/installation.md

@@ -36,7 +36,7 @@ Also available on [jsdelivr](//cdn.jsdelivr.net/vue/{{vue_version}}/vue.js) or [
 
 ## NPM
 
-NPM is the recommended installation method when building large scale applications with Vue. It pairs nicely with module bundlers such as [Webpack](http://webpack.github.io/) or [Browserify](http://browserify.org/). Vue also provides accompanying tools for authoring [Single File Components](application.html#Single-File-Components).
+NPM is the recommended installation method when building large scale applications with Vue. It pairs nicely with module bundlers such as [Webpack](http://webpack.github.io/) or [Browserify](http://browserify.org/). Vue also provides accompanying tools for authoring [Single File Components](single-file-components.html).
 
 ``` bash
 # latest stable

src/guide/instance.md

@@ -73,6 +73,8 @@ vm.$watch('a', function (newVal, oldVal) {
 })
 ```
 
+<p class="tip">Note that __you should not use arrow functions on an instance property or callback__ (e.g. `vm.$watch('a', newVal => this.myMethod())`). The reason is arrow functions bind the parent context, so `this` will not be the Vue instance as you expect and `this.myMethod` will be undefined.</p>
+
 Consult the [API reference](/api) for the full list of instance properties and methods.
 
 ## Instance Lifecycle Hooks

src/guide/migration.md

@@ -332,7 +332,7 @@ Most use cases of mutating a prop can be replaced by one of these options:
 
 ### Props on a Root Instance <sup>deprecated</sup>
 
-On root Vue instances (i.e. instances created with `new Vue({ ... })`), you must use `propsData` instead instead of `props`.
+On root Vue instances (i.e. instances created with `new Vue({ ... })`), you must use `propsData` instead of `props`.
 
 {% raw %}
 <div class="upgrade-path">
@@ -653,7 +653,7 @@ Directives have a greatly reduced scope of responsibility: they are now only use
 Some of the most notable differences include:
 
 - Directives no longer have instances. This means there's no more `this` inside directive hooks. Instead, they receive everything they might need as arguments. If you really must persist state across hooks, you can do so on `el`.
-- Options such as `acceptStatement`, `deep`, `priority`, etc are all deprecated.
+- Options such as `acceptStatement`, `deep`, `priority`, etc are all deprecated. To replace `twoWay` directives, see [this example](#Two-Way-Filters-deprecated).
 - Some of the current hooks have different behavior and there are also a couple new hooks.
 
 Fortunately, since the new directives are much simpler, you can master them more easily. Read the new [Custom Directives guide](custom-directive.html) to learn more.
@@ -665,6 +665,29 @@ Fortunately, since the new directives are much simpler, you can master them more
 </div>
 {% endraw %}
 
+### Directive `.literal` Modifier <sup>deprecated</sup>
+
+The `.literal` modifier has been removed, as the same can be easily achieved by just providing a string literal as the value.
+
+For example, you can update:
+
+``` js
+<p v-my-directive.literal="foo bar baz"></p>
+```
+
+to just:
+
+``` html
+<p v-my-directive="'foo bar baz'"></p>
+```
+
+{% raw %}
+<div class="upgrade-path">
+  <h4>Upgrade Path</h4>
+  <p>Run the <a href="https://github.com/vuejs/vue-migration-helper">migration helper</a> on your codebase to find examples of the `.literal` modifier on a directive.</p>
+</div>
+{% endraw %}
+
 ## Transitions
 
 ### `transition` Attribute <sup>deprecated</sup>
@@ -702,6 +725,10 @@ If you need to stagger list transitions, you can control timing by setting and a
 
 ## Events
 
+### `events` option <sup>deprecated</sup>
+
+The `events` option has been deprecated. Event handlers should now be registered in the `created` hook instead. Check out the [`$dispatch` and `$broadcast` migration guide](#dispatch-and-broadcast-deprecated) for a detailed example.
+
 ### `Vue.directive('on').keyCodes` <sup>deprecated</sup>
 
 The new, more concise way to configure `keyCodes` is through`Vue.config.keyCodes`. For example:
@@ -1016,32 +1043,32 @@ In many cases though, you'll still run into strange behavior (e.g. `0.035.toFixe
 
 ### Two-Way Filters <sup>deprecated</sup>
 
-Some users have enjoyed using two-way filters with `v-model` to create interesting inputs with very little code. While seemingly simple however, two-way filters can also hide a great deal of complexity - and even encourage poor UX by delaying state updates. Instead, components are recommended as a more explicit and feature-rich way of creating custom inputs.
+Some users have enjoyed using two-way filters with `v-model` to create interesting inputs with very little code. While _seemingly_ simple however, two-way filters can also hide a great deal of complexity - and even encourage poor UX by delaying state updates. Instead, components wrapping an input are recommended as a more explicit and feature-rich way of creating custom inputs.
 
-We'll now walk through an example of a filter provided by the community and offer tips for how to migrate away from two-way filters. Here's a simple currency filter:
+As an example, we'll now walk the migration of a two-way currency filter:
 
-<iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/6744xnjk/embedded/result,html,js" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/6744xnjk/embedded/js,html,result" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
 
-It mostly works well, but the delayed state updates can cause strange behavior. For example, try entering `99.999` into one of those inputs. When the input loses focus, its value will update to `$100.00`. When looking at the calculated total however, you'll see that `99.999` is what's stored in our data. The version of reality that the user sees is out of sync!
+It mostly works well, but the delayed state updates can cause strange behavior. For example, click on the `Result` tab and try entering `9.999` into one of those inputs. When the input loses focus, its value will update to `$10.00`. When looking at the calculated total however, you'll see that `9.999` is what's stored in our data. The version of reality that the user sees is out of sync!
 
-To start transitioning towards a more robust solution using Vue 2.0, let's first refactor this filter into a component that uses it:
+To start transitioning towards a more robust solution using Vue 2.0, let's first wrap this filter in a new `<currency-input>` component:
 
-<iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/g7osemrx/embedded/result,html,js" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/943zfbsh/embedded/js,html,result" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
 
-This allows us add behavior that wasn't possible with a filter alone, such as selecting the content of an input on focus. Now the next step will be to extract the business logic from the filter:
+This allows us add behavior that a filter alone couldn't encapsulate, such as selecting the content of an input on focus. Now the next step will be to extract the business logic from the filter. Below, we pull everything out into an external [`currencyValidator` object](https://gist.github.com/chrisvfritz/5f0a639590d6e648933416f90ba7ae4e):
 
-<iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/j4xtb20e/embedded/result,html,js" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/9c32kev2/embedded/js,html,result" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
 
 This increased modularity not only makes it easier to migrate to Vue 2, but also allows currency parsing and formatting to be:
 
 - unit tested in isolation from your Vue code
 - used by other parts of your application, such as to validate the payload to an API endpoint
 
-Having this validator extracted out, we can also more comfortably build it up into a more robust solution. We've now eliminated the state quirks and have even made it impossible for users to enter anything wrong, similar to what the browser's native number input tries to do.
+Having this validator extracted out, we've also more comfortably built it up into a more robust solution. The state quirks have been eliminated and it's actually impossible for users to enter anything wrong, similar to what the browser's native number input tries to do.
 
 We're still limited however, by filters and by Vue 1.0 in general, so let's complete the upgrade to Vue 2.0:
 
-<iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/r4e49aLs/embedded/result,html,js" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="300" src="https://jsfiddle.net/chrisvfritz/1oqjojjx/embedded/js,html,result" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
 
 You may notice that:
 
@@ -1127,7 +1154,7 @@ When used together with `<transition>`, make sure to nest it inside:
 Interpolation within attributes is no longer valid. For example:
 
 ``` html
-<button v-bind:class="btn btn-{{ size }}"></button>
+<button class="btn btn-{{ size }}"></button>
 ```
 
 Should either be updated to use an inline expression:

src/guide/render-function.md

@@ -160,6 +160,8 @@ One thing to note: similar to how `v-bind:class` and `v-bind:style` have special
   nativeOn: {
     click: this.nativeClickHandler
   },
+  // The name of a slot if the child of a component
+  slot: 'name-of-slot'
   // Other special top-level properties
   key: 'myKey',
   ref: 'myRef'

src/guide/unit-testing.md

@@ -6,7 +6,7 @@ order: 22
 
 ## Setup and Tooling
 
-Anything compatible with a module-based build system will work, but if you're looking for a specific recommendation, try the [Karma](http://karma-runner.github.io/0.12/index.html) test runner. It has a lot of community plugins, including support for [Webpack](https://github.com/webpack/karma-webpack) and [Browserify](https://github.com/Nikku/karma-browserify). For detailed setup, please refer to each project's respective documentation, though these example Karma configurations for [Webpack](https://github.com/vuejs/vue-loader-example/blob/master/build/karma.conf.js) and [Browserify](https://github.com/vuejs/vueify-example/blob/master/karma.conf.js) may help you get started.
+Anything compatible with a module-based build system will work, but if you're looking for a specific recommendation, try the [Karma](http://karma-runner.github.io) test runner. It has a lot of community plugins, including support for [Webpack](https://github.com/webpack/karma-webpack) and [Browserify](https://github.com/Nikku/karma-browserify). For detailed setup, please refer to each project's respective documentation, though these example Karma configurations for [Webpack](https://github.com/vuejs/vue-loader-example/blob/master/build/karma.conf.js) and [Browserify](https://github.com/vuejs/vueify-example/blob/master/karma.conf.js) may help you get started.
 
 ## Simple Assertions
 

themes/vue/source/css/_common.styl

@@ -7,6 +7,7 @@ body
     -webkit-font-smoothing antialiased
     -moz-osx-font-smoothing grayscale
     color $medium
+    background-color white
     margin 0
 
 a