Deprecation Guide for Ember.View

source/deprecations/v1.x.html.md

@@ -457,3 +457,197 @@ syntax introduced in 1.12:
 ```
 
 For further reading, review the [RFC](https://github.com/emberjs/rfcs/blob/master/active/0001-improved-cp-syntax.md) describing this feature and the [pull request of the initial implementation](https://github.com/emberjs/ember.js/pull/9527).
+
+### Deprecations Added in 1.13
+
+Ember.js 1.13 is the last minor release of Ember 1.x before 2.0. Consequently,
+it has a rather large number of notable deprecations.
+
+#### Ember.View
+
+Ember 1.x encouraged a Model-View-Controller-Route architecture. Since then,
+the web has consolidated around a Model-Component-Route pattern for web
+development that Ember 2.0 also embraces.
+
+Views are removed from the Ember 2.0 API. However a single release is likely
+insufficient for large apps to upgrade their entire codebase away from routeable
+views, and consequently Ember is providing extended support for views via the
+[ember-legacy-views](https://github.com/emberjs/ember-legacy-views) addon.
+This addon will remain compatible with Ember until v2.4 of the framework
+is released.
+
+##### Migrating away from the view helper
+
+In most cases Ember views can be replaced with a component. For example
+this view and usage:
+
+```handlebars
+{{! app/templates/show-menu.hbs }}
+{{view.title}}
+```
+
+```js
+// app/views/show-menu.js
+import Ember from "ember";
+
+// Usage: {{view "show-menu"}}
+export default Ember.View.extend({
+  templateName: 'some-menu',
+  title: 'My Menu'
+});
+```
+
+Can be replaced with this component:
+
+```handlebars
+{{! app/templates/components/show-menu.hbs }}
+{{title}}
+```
+
+```js
+// app/components/show-menu.js
+import Ember from "ember";
+
+// Usage: {{show-menu}}
+export default Ember.Component.extend({
+  title: 'My Menu'
+});
+```
+
+Note that a component is always its own context in a template. A view's template
+may have had access to other variables that were present where it was called,
+such as a `controller`. A component template will always be isolated, and
+if data is needed it should be passed upon invocation. For example:
+
+```handlebars
+{{show-menu options=controller.menuOptions}}
+```
+
+##### Differences in yielded blocks
+
+Some notable differences exist between yielded view blocks and yielded component
+blocks. A view could be used this way:
+
+```js
+// app/views/reverse-name.js
+import Ember from "ember";
+
+export default Ember.View.extend({
+  reversedName: Ember.computed('name', function() {
+    return this.get('name').split("").reverse().join("");
+  })
+});
+```
+
+```handlebars
+{{#view "reverse-name" name=controller.name}}
+  {{view.reversedName}}
+{{/view}}
+```
+
+Components introduced block params. This concept achieves data passing
+without the confusion over what `{{view}}` refers to. For example:
+
+```js
+// app/components/reverse-name.js
+import Ember from "ember";
+
+export default Ember.Component.extend({
+  reversedName: Ember.computed('name', function() {
+    return this.get('name').split("").reverse().join("");
+  })
+});
+```
+
+```handlebars
+// app/templates/components/reverse-name.hbs
+{{yield reversedName}}
+```
+
+```handlebars
+{{reverse-name name=controller.name as |reversedName|}}
+  {{reversedName}}
+{{/view}}
+```
+
+Just as passing values to a component allow access to those values in the
+isolated template of that component, yielding block params allow for values
+from the component to be passed to the location the component was called at.
+
+##### Routable Views
+
+When a template for a given route is rendered, if there is a view with the
+same name that view will also be used. For example this view is attached
+to the rendered route template:
+
+```js
+// app/router.js
+import Ember from "ember";
+
+export default Ember.Router.map(function() {
+  this.route('about');
+});
+```
+
+```js
+// app/views/about.js
+import Ember from "ember";
+
+export default Ember.View.extend({
+  classNameBindings: ['controller.isActive:active']
+});
+```
+
+There are only two reasons a view may be used for a route.
+
+  * To set attribute bindings
+  * To attach event handlers
+
+You should migrate away from routed views. For example to attach
+bindings an element in the template is sufficient:
+
+```js
+// app/router.js
+import Ember from "ember";
+
+export default Ember.Router.map(function() {
+  this.route('about');
+});
+```
+
+```handlebars
+{{! app/templates/about.hbs }}
+<div class="{{if isActive 'active'}}">
+  <!-- something something -->
+</div>
+```
+
+If attaching events or sharing DOM is necessary, consider a component:
+
+```js
+// app/router.js
+import Ember from "ember";
+
+export default Ember.Router.map(function() {
+  this.route('about');
+});
+```
+
+```handlebars
+{{! app/templates/about.hbs }}
+{{#active-layout isActive=isActive}}
+  <!-- something something -->
+{{/active-layout}}
+```
+
+```js
+// app/components/active-layout.js
+import Ember from "ember";
+
+export default Ember.Component.extend({
+  classNameBindings: ['isActive:active'],
+  click() {
+    // Handle click
+  }
+});
+```