Reorganize sidebar and some content; cannibalize reactivity page (#1086)

* reorganize sidebar and some content; cannibalize reactivity page

* Fix typo in instance.md

* Fix typo in instance.md

* Change errorMessage: null to error: null in instance.md

* Fix typo in reactivity.md.hidden

* remove redundant note about filters

Author: chrisvfritz

src/images/logged-proxied-data.png

@@ -436,8 +436,8 @@ if (version === 2) {
   var vm = new Vue({
     data: data
   })
-  vm.a // -> 1
-  vm.$data === data // -> true
+  vm.a // => 1
+  vm.$data === data // => true
 
   // must use function when in Vue.extend()
   var Component = Vue.extend({
@@ -545,10 +545,10 @@ if (version === 2) {
       }
     }
   })
-  vm.aPlus   // -> 2
+  vm.aPlus   // => 2
   vm.aPlus = 3
-  vm.a       // -> 2
-  vm.aDouble // -> 4
+  vm.a       // => 2
+  vm.aDouble // => 4
   ```
 
 - **See also:** [Computed Properties](../guide/computed.html)
@@ -610,7 +610,7 @@ if (version === 2) {
       }
     }
   })
-  vm.a = 2 // -> new: 2, old: 1
+  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>
@@ -744,6 +744,17 @@ if (version === 2) {
 
   Called after the instance has just been mounted where `el` is replaced by the newly created `vm.$el`. If the root instance is mounted to an in-document element, `vm.$el` will also be in-document when `mounted` is called.
 
+  Note that `mounted` does **not** guarantee that all child components have also been mounted. If you want to wait until the entire view has been rendered, you can use [vm.$nextTick](#vm-nextTick) inside of `mounted`:
+
+  ``` js
+  mounted: function () {
+    this.$nextTick(function () {
+      // Code that will run only after the
+      // entire view has been rendered
+    })
+  }
+  ```
+
   **This hook is not called during server-side rendering.**
 
 - **See also:** [Lifecycle Diagram](../guide/instance.html#Lifecycle-Diagram)
@@ -772,6 +783,17 @@ if (version === 2) {
 
   The component's DOM will have been updated when this hook is called, so you can perform DOM-dependent operations here. However, in most cases you should avoid changing state inside the hook. To react to state changes, it's usually better to use a [computed property](#computed) or [watcher](#watch) instead.
 
+  Note that `updated` does **not** guarantee that all child components have also been re-rendered. If you want to wait until the entire view has been re-rendered, you can use [vm.$nextTick](#vm-nextTick) inside of `updated`:
+
+  ``` js
+  updated: function () {
+    this.$nextTick(function () {
+      // Code that will run only after the
+      // entire view has been re-rendered
+    })
+  }
+  ```
+
   **This hook is not called during server-side rendering.**
 
 - **See also:** [Lifecycle Diagram](../guide/instance.html#Lifecycle-Diagram)
@@ -892,8 +914,8 @@ if (version === 2) {
     created: function () { console.log(2) },
     mixins: [mixin]
   })
-  // -> 1
-  // -> 2
+  // => 1
+  // => 2
   ```
 
 - **See also:** [Mixins](../guide/mixins.html)
@@ -953,7 +975,7 @@ if (version === 2) {
   var Child = {
     inject: ['foo'],
     created () {
-      console.log(this.foo) // -> "bar"
+      console.log(this.foo) // => "bar"
     }
     // ...
   }
@@ -1170,7 +1192,7 @@ if (version === 2) {
   new Vue({
     customOption: 'foo',
     created: function () {
-      console.log(this.$options.customOption) // -> 'foo'
+      console.log(this.$options.customOption) // => 'foo'
     }
   })
   ```
@@ -1435,7 +1457,7 @@ if (version === 2) {
     console.log(msg)
   })
   vm.$emit('test', 'hi')
-  // -> "hi"
+  // => "hi"
   ```
 
 <h3 id="vm-once">vm.$once( event, callback )</h3>

src/v2/api/index.md

@@ -1,7 +1,7 @@
 ---
 title: Comparison with Other Frameworks
 type: guide
-order: 29
+order: 701
 ---
 
 This is definitely the most difficult page in the guide to write, but we do feel it's important. Odds are, you've had problems you tried to solve and you've used another library to solve them. You're here because you want to know if Vue can solve your specific problems better. That's what we hope to answer for you.

src/v2/guide/comparison.md

@@ -68,9 +68,9 @@ var vm = new Vue({
 Here we have declared a computed property `reversedMessage`. The function we provided will be used as the getter function for the property `vm.reversedMessage`:
 
 ``` js
-console.log(vm.reversedMessage) // -> 'olleH'
+console.log(vm.reversedMessage) // => 'olleH'
 vm.message = 'Goodbye'
-console.log(vm.reversedMessage) // -> 'eybdooG'
+console.log(vm.reversedMessage) // => 'eybdooG'
 ```
 
 You can open the console and play with the example vm yourself. The value of `vm.reversedMessage` is always dependent on the value of `vm.message`.

src/v2/guide/computed.md

@@ -1,7 +1,7 @@
 ---
 title: Custom Directives
 type: guide
-order: 16
+order: 302
 ---
 
 ## Intro

src/v2/guide/custom-directive.md

@@ -1,7 +1,7 @@
 ---
-title: Production Deployment Tips
+title: Production Deployment
 type: guide
-order: 20
+order: 401
 ---
 
 ## Turn on Production Mode

src/v2/guide/deployment.md

@@ -75,7 +75,7 @@ var example2 = new Vue({
 })
 
 // you can invoke methods in JavaScript too
-example2.greet() // -> 'Hello Vue.js!'
+example2.greet() // => 'Hello Vue.js!'
 ```
 
 Result:

src/v2/guide/events.md

@@ -0,0 +1,46 @@
+---
+title: Filters
+type: guide
+order: 305
+---
+
+Vue.js allows you to define filters that can be used to apply common text formatting. Filters are usable in two places: **mustache interpolations and `v-bind` expressions** (the latter supported in 2.1.0+). Filters should be appended to the end of the JavaScript expression, denoted by the "pipe" symbol:
+
+``` html
+<!-- in mustaches -->
+{{ message | capitalize }}
+
+<!-- in v-bind -->
+<div v-bind:id="rawId | formatId"></div>
+```
+
+The filter function always receives the expression's value (the result of the former chain) as its first argument. In this example, the `capitalize` filter function will receive the value of `message` as its argument.
+
+``` js
+new Vue({
+  // ...
+  filters: {
+    capitalize: function (value) {
+      if (!value) return ''
+      value = value.toString()
+      return value.charAt(0).toUpperCase() + value.slice(1)
+    }
+  }
+})
+```
+
+Filters can be chained:
+
+``` html
+{{ message | filterA | filterB }}
+```
+
+In this case, `filterA`, defined with a single argument, will receive the value of `message`, and then the `filterB` function will be called with the result of `filterA` passed into `filterB`'s single argument.
+
+Filters are JavaScript functions, therefore they can take arguments:
+
+``` html
+{{ message | filterA('arg1', arg2) }}
+```
+
+Here `filterA` is defined as a function taking three arguments. The value of `message` will be passed into the first argument. The plain string `'arg1'` will be passed into the `filterA` as its second argument, and the value of expression `arg2` will be evaluated and passed in as the third argument.

src/v2/guide/filters.md

@@ -343,8 +343,8 @@ vm.pick === vm.a
 
 ``` js
 // when selected:
-typeof vm.selected // -> 'object'
-vm.selected.number // -> 123
+typeof vm.selected // => 'object'
+vm.selected.number // => 123
 ```
 
 ## Modifiers

src/v2/guide/forms.md

@@ -17,6 +17,10 @@ Vue does **not** support IE8 and below, because it uses ECMAScript 5 features th
 
 Detailed release notes for each version are available on [GitHub](https://github.com/vuejs/vue/releases).
 
+## Vue Devtools
+
+When using Vue, we recommend also installing the [Vue Devtools](https://github.com/vuejs/vue-devtools#vue-devtools) in your browser, allowing you to inspect and debug your Vue applications in a more user-friendly interface.
+
 ## Direct `<script>` Include
 
 Simply download and include with a script tag. `Vue` will be registered as a global variable.

src/v2/guide/installation.md

@@ -4,9 +4,9 @@ type: guide
 order: 3
 ---
 
-## Constructor
+## Creating a Vue Instance
 
-Every Vue application is bootstrapped by creating a **root Vue instance** with the `Vue` constructor function:
+Every Vue application starts by creating a new **Vue instance** with the `Vue` function:
 
 ``` js
 var vm = new Vue({
@@ -16,46 +16,68 @@ var vm = new Vue({
 
 Although not strictly associated with the [MVVM pattern](https://en.wikipedia.org/wiki/Model_View_ViewModel), Vue's design was partly inspired by it. As a convention, we often use the variable `vm` (short for ViewModel) to refer to our Vue instance.
 
-When you instantiate a Vue instance, you need to pass in an **options object** which can contain options for data, template, element to mount on, methods, lifecycle callbacks, and more. The full list of options can be found in the [API reference](../api/#Options-Data).
+When you create a Vue instance, you pass in an **options object**. The majority of this guide describes how you can use these options to create your desired behavior. For reference, you can also browse the full list of options in the [API reference](../api/#Options-Data).
 
-The `Vue` constructor can be extended to create reusable **component constructors** with pre-defined options:
+A Vue application consists of a **root Vue instance** created with `new Vue`, optionally organized into a tree of nested, reusable components. For example, a todo app's component tree might look like this:
 
-``` js
-var MyComponent = Vue.extend({
-  // extension options
-})
-
-// all instances of `MyComponent` are created with
-// the pre-defined extension options
-var myComponentInstance = new MyComponent()
+```
+Root Instance
+|- TodoList
+   |- TodoItem
+      |- DeleteTodoButton
+      |- EditTodoButton
+   |- TodoListFooter
+      |- ClearTodosButton
+      |- TodoListStatistics
 ```
 
-Although it is possible to create extended instances imperatively, most of the time it is recommended to compose them declaratively in templates as custom elements. We will talk about [the component system](components.html) in detail later. For now, you just need to know that all Vue components are essentially extended Vue instances.
+We'll talk about [the component system](components.html) in detail later. For now, just know that all Vue components are also Vue instances, and so accept the same options object (except for a few root-specific options).
 
-## Properties and Methods
+## Data and Methods
 
-Each Vue instance **proxies** all the properties found in its `data` object:
+When a Vue instance is created, it adds all the properties found in its `data` object to Vue's **reactivity system**. When the values of those properties change, the view will "react", updating to match the new values.
 
 ``` js
+// Our data object
 var data = { a: 1 }
+
+// The object is added to a Vue instance
 var vm = new Vue({
   data: data
 })
 
-vm.a === data.a // -> true
+// These reference the same object!
+vm.a === data.a // => true
 
-// setting the property also affects original data
+// Setting the property on the instance
+// also affects the original data
 vm.a = 2
-data.a // -> 2
+data.a // => 2
 
 // ... and vice-versa
 data.a = 3
-vm.a // -> 3
+vm.a // => 3
+```
+
+When this data changes, the view will re-render. It should be noted that properties in `data` are only **reactive** if they existed when the instance was created. That means if you add a new property, like:
+
+``` js
+vm.b = 'hi'
 ```
 
-It should be noted that only these proxied properties are **reactive**, meaning any changes to their values will trigger the view to re-render. If you attach a new property to the instance after it has been created, it will not trigger any view updates. We will discuss the reactivity system in detail later.
+Then changes to `b` will not trigger any view updates. If you know you'll need a property later, but it starts out empty or non-existent, you'll just need to set some initial value. For example:
+
+``` js
+data: {
+  newTodoText: '',
+  visitCount: 0,
+  hideCompletedTodos: false,
+  todos: [],
+  error: null
+}
+```
 
-In addition to data properties, Vue instances expose a number of useful instance properties and methods. These properties and methods are prefixed with `$` to differentiate them from proxied data properties. For example:
+In addition to data properties, Vue instances expose a number of useful instance properties and methods. These are prefixed with `$` to differentiate them from user-defined properties. For example:
 
 ``` js
 var data = { a: 1 }
@@ -64,25 +86,25 @@ var vm = new Vue({
   data: data
 })
 
-vm.$data === data // -> true
-vm.$el === document.getElementById('example') // -> true
+vm.$data === data // => true
+vm.$el === document.getElementById('example') // => true
 
 // $watch is an instance method
-vm.$watch('a', function (newVal, oldVal) {
-  // this callback will be called when `vm.a` changes
+vm.$watch('a', function (newValue, oldValue) {
+  // This callback will be called when `vm.a` changes
 })
 ```
 
-<p class="tip">Don't use [arrow functions](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions) on an instance property or callback (e.g. `vm.$watch('a', newVal => this.myMethod())`). As arrow functions are bound to the parent context, `this` will not be the Vue instance as you'd expect and `this.myMethod` will be undefined.</p>
-
-Consult the [API reference](../api/#Instance-Properties) for the full list of instance properties and methods.
+In the future, you can consult the [API reference](../api/#Instance-Properties) for a full list of instance properties and methods.
 
 ## Instance Lifecycle Hooks
 
-Each Vue instance goes through a series of initialization steps when it is created - for example, it needs to set up data observation, compile the template, mount the instance to the DOM, and update the DOM when data changes. Along the way, it will also invoke some **lifecycle hooks**, which give us the opportunity to execute custom logic. For example, the [`created`](../api/#created) hook is called after the instance is created:
+Each Vue instance goes through a series of initialization steps when it's created - for example, it needs to set up data observation, compile the template, mount the instance to the DOM, and update the DOM when data changes. Along the way, it also runs functions called **lifecycle hooks**, giving users the opportunity to add their own code at specific stages.
+
+For example, the [`created`](../api/#created) hook can be used to run code after an instance is created:
 
 ``` js
-var vm = new Vue({
+new Vue({
   data: {
     a: 1
   },
@@ -91,13 +113,15 @@ var vm = new Vue({
     console.log('a is: ' + this.a)
   }
 })
-// -> "a is: 1"
+// => "a is: 1"
 ```
 
-There are also other hooks which will be called at different stages of the instance's lifecycle, for example [`mounted`](../api/#mounted), [`updated`](../api/#updated), and [`destroyed`](../api/#destroyed). All lifecycle hooks are called with their `this` context pointing to the Vue instance invoking it. You may have been wondering where the concept of "controllers" lives in the Vue world and the answer is: there are no controllers. Your custom logic for a component would be split among these lifecycle hooks.
+There are also other hooks which will be called at different stages of the instance's lifecycle, such as [`mounted`](../api/#mounted), [`updated`](../api/#updated), and [`destroyed`](../api/#destroyed). All lifecycle hooks are called with their `this` context pointing to the Vue instance invoking it.
+
+<p class="tip">Don't use [arrow functions](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions) on an options property or callback, such as `created: () => console.log(this.a)` or `vm.$watch('a', newValue => this.myMethod())`. Since arrow functions are bound to the parent context, `this` will not be the Vue instance as you'd expect and `this.a` or `this.myMethod` will be undefined.</p>
 
 ## Lifecycle Diagram
 
-Below is a diagram for the instance lifecycle. You don't need to fully understand everything going on right now, but this diagram will be helpful in the future.
+Below is a diagram for the instance lifecycle. You don't need to fully understand everything going on right now, but as you learn and build more, it will be a useful reference.
 
-![Lifecycle](/images/lifecycle.png)
+![The Vue Instance Lifecycle](/images/lifecycle.png)

src/v2/guide/instance.md

@@ -1,7 +1,7 @@
 ---
 title: Join the Vue.js Community!
 type: guide
-order: 30
+order: 702
 ---
 
 Vue's community is growing incredibly fast and if you're reading this, there's a good chance you're ready to join it. So... welcome!