Merge pull request #21 from vuejs/2.0

2.0

Author: dingyiming

src/api/index.md

@@ -440,7 +440,6 @@ type: api
 
 - **See also:**
   - [Computed Properties](/guide/computed.html)
-  - [Reactivity in Depth: Inside Computed Properties](/guide/reactivity.html#Inside-Computed-Properties)
 
 ### methods
 

src/examples/hackernews.md

@@ -4,10 +4,32 @@ type: examples
 order: 10
 ---
 
-> This is a HackerNews clone built upon HN's official Firebase API, and using Webpack + vue-loader for the build setup.
+> This is a HackerNews clone built upon HN's official Firebase API, Vue 2.0 + vue-router + vuex, with server-side rendering.
 
+{% raw %}
 <div style="max-width:600px">
-  <a href="http://vuejs.github.io/vue-hackernews" target="_blank"><img style="width:100%" src="/images/hn.png"></a>
+  <a href="https://github.com/vuejs/vue-hackernews-2.0" target="_blank">
+    <img style="width:100%" src="/images/hn.png">
+  </a>
 </div>
+{% endraw %}
 
-> [[Source](https://github.com/vuejs/vue-hackernews)]
+> [Live Demo](https://vue-hn.now.sh/)
+> Note: the demo may need some spin up time if nobody has accessed it for a certain period.
+>
+> [[Source](https://github.com/vuejs/vue-hackernews-2.0)]
+
+## Features
+
+- Server Side Rendering
+  - Vue + vue-router + vuex working together
+  - Server-side data pre-fetching
+  - Client-side state & DOM hydration
+- Single-file Vue Components
+  - Hot-reload in development
+  - CSS extraction for production
+- Real-time List Updates with FLIP Animation
+
+## Architecture Overview
+
+<img width="973" alt="Hackernew clone architecture overview" src="/images/hn-architecture.png">

src/guide/computed.md

@@ -77,6 +77,39 @@ You can open the console and play with the example vm yourself. The value of `vm
 
 You can data-bind to computed properties in templates just like a normal property. Vue is aware that `vm.reversedMessage` depends on `vm.message`, so it will update any bindings that depend on `vm.reversedMessage` when `vm.message` changes. And the best part is that we've created this dependency relationship declaratively: the computed getter function is pure and has no side effects, which makes it easy to test and reason about.
 
+### Computed Caching vs Methods
+
+You may have noticed we can achieve the same result by invoking a method in the expression:
+
+``` html
+<p>Reversed message: "{{ reverseMessage() }}"</p>
+```
+
+``` js
+// in component
+methods: {
+  reverseMessage: function () {
+    return this.message.split('').reverse().join('')
+  }
+}
+```
+
+Instead of a computed property, we can define the same function as a method instead. For the end result, the two approaches are indeed exactly the same. However, the difference is that **computed properties are cached based on its dependencies.** A computed property will only re-evaluate when some of its dependencies have changed. This means as long as `message` has not changed, multiple access to the `reversedMessage` computed property will immediately return the previously computed result without having to run the function again.
+
+This also means the following computed property will never update, because `Date.now()` is not a reactive dependency:
+
+``` js
+computed: {
+  now: function () {
+    return Date.now()
+  }
+}
+```
+
+In comparison, a method invocation will **always** run the function whenever a re-render happens.
+
+Why do we need caching? Imagine we have an expensive computed property **A**, which requires looping through a huge Array and doing a lot of computations. Then we may have other computed properties that in turn depend on **A**. Without caching, we would be executing **A**’s getter many more times than necessary! In cases where you do not want caching, use a method instead.
+
 ### Computed vs Watched Property
 
 Vue does provide a more generic way to observe and react to data changes on a Vue instance: **watch properties**. When you have some data that needs to change based on some other data, it is tempting to overuse `watch` - especially if you are coming from an AngularJS background. However, it is often a better idea to use a computed property rather than an imperative `watch` callback. Consider this example:
@@ -148,8 +181,6 @@ computed: {
 
 Now when you run `vm.fullName = 'John Doe'`, the setter will be invoked and `vm.firstName` and `vm.lastName` will be updated accordingly.
 
-The technical details behind how computed properties are updated are discussed in [another section](reactivity.html#Inside-Computed-Properties) dedicated to the reactivity system.
-
 ## Watchers
 
 While computed properties are more appropriate in most cases, there are times when a custom watcher is necessary. That's why Vue provides a more generic way to react to data changes through the `watch` option. This is most useful when you want to perform asynchronous or expensive operations in response to changing data.
@@ -270,3 +301,5 @@ var watchExampleVM = new Vue({
 {% endraw %}
 
 In this case, using the `watch` option allows us to perform an asynchronous operation (accessing an API), limit how often we perform that operation, and set intermediary states until we get a final answer. None of that would be possible with a computed property.
+
+In addition to the `watch` option, you can also use the imperative [vm.$watch API](/api/#vm-watch).

src/guide/index.md

@@ -113,7 +113,7 @@ var app3 = new Vue({
 </script>
 {% endraw %}
 
-Go ahead and enter `app2.seen = false` in the console. You should see the message disappear.
+Go ahead and enter `app3.seen = false` in the console. You should see the message disappear.
 
 This second example demonstrates that we can bind data to not only text and attributes, but also the **structure** of the DOM. Moreover, Vue also provides a powerful transition effect system that can automatically apply [transition effects](transitions.html) when elements are inserted/updated/removed by Vue.
 

src/guide/installation.md

@@ -18,7 +18,9 @@ Detailed release notes for each version are available on [GitHub](https://github
 
 ## Standalone
 
-Simply download and include with a script tag. `Vue` will be registered as a global variable. **Pro tip: Don't use the minified version during development. You will miss out all the nice warnings for common mistakes.**
+Simply download and include with a script tag. `Vue` will be registered as a global variable.
+
+<p class="tip">Don't use the minified version during development. You will miss out all the nice warnings for common mistakes!</p>
 
 <div id="downloads">
 <a class="button" href="/js/vue.js" download>Development Version</a><span class="light info">With full warnings and debug mode</span>
@@ -47,6 +49,24 @@ NPM is the recommended installation method when building large scale application
 $ npm install vue@next
 ```
 
+### Note on NPM Builds
+
+Because Single File Components pre-compile the templates into render functions at build time, the default export of the `vue` NPM package is the **runtime-only build**, which does not support the `template` option. If you still wish to use the `template` option, you will need to configure your bundler to alias `vue` to the standalone build.
+
+With webpack, add the following alias to your webpack config:
+
+``` js
+resolve: {
+  alias: {
+    vue: 'vue/dist/vue.js'
+  }
+}
+```
+
+For Browserify, you can use [aliasify](https://github.com/benbria/aliasify) for the same effect.
+
+<p class="tip">Do NOT do `import Vue from 'vue/dist/vue'` - since some tools or 3rd party libraries may import vue as well, this may cause the app to load both the runtime and standalone builds at the same time and lead to errors.</p>
+
 ## CLI
 
 Vue.js provides an [official CLI](https://github.com/vuejs/vue-cli) for quickly scaffolding ambitious Single Page Applications. It provides batteries-included build setups for a modern frontend workflow. It takes only a few minutes to get up and running with hot-reload, lint-on-save, and production-ready builds:

src/guide/reactivity.md

@@ -135,41 +135,3 @@ Vue.component('example', {
   }
 })
 ```
-
-## Inside Computed Properties
-
-It should be noted that Vue's computed properties are **not** simple getters. Each computed property keeps track of its own reactive dependencies. When a computed property is evaluated, Vue updates its dependency list and caches the returned value. The cached value is only invalidated when one of the tracked dependencies have changed. Therefore, as long as the dependencies did not change, accessing the computed property will directly return the cached value instead of calling the getter.
-
-Why do we need caching? Imagine we have an expensive computed property **A**, which requires looping through a huge Array and doing a lot of computations. Then we may have other computed properties that in turn depend on **A**. Without caching, we would be executing **A**’s getter many more times than necessary!
-
-Because of computed property caching, the getter function is not always called when you access a computed property. Consider the following example:
-
-``` js
-var vm = new Vue({
-  data: {
-    message: 'hi'
-  },
-  computed: {
-    example: function () {
-      return Date.now() + this.message
-    }
-  }
-})
-```
-
-The computed property `example` has only one dependency: `vm.message`. `Date.now()` is **not** a reactive dependency, because it has nothing to do with Vue's data observation system. Therefore, when you programmatically access `vm.example`, you will find the timestamp remains the same unless `vm.message` triggers a re-evaluation.
-
-In some use cases, you may want to preserve the simple getter-like behavior, where every time you access `vm.example` it simply calls the getter again. You can do that by turning off caching for a specific computed property:
-
-``` js
-computed: {
-  example: {
-    cache: false,
-    get: function () {
-      return Date.now() + this.message
-    }
-  }
-}
-```
-
-Now, every time you access `vm.example`, the timestamp will be up-to-date. **However, note this only affects programmatic access inside JavaScript; data-bindings are still dependency-driven.** When you bind to a computed property in the template as `{% raw %}{{ example }}{% endraw %}`, the DOM will only be updated when a reactive dependency has changed.