From 3bb62b6651a8b91bec5a87ea04382e7f9d868fdc Mon Sep 17 00:00:00 2001
From: Ben Ogle <ogle.ben@gmail.com>
Date: Fri, 12 Dec 2014 17:37:39 -0800
Subject: [PATCH] Update converting view section

---
 docs/upgrading/upgrading-your-package.md | 66 ++++++++++++++++++++----
 1 file changed, 57 insertions(+), 9 deletions(-)

diff --git a/docs/upgrading/upgrading-your-package.md b/docs/upgrading/upgrading-your-package.md
index 5d44780a7..155c35fd9 100644
--- a/docs/upgrading/upgrading-your-package.md
+++ b/docs/upgrading/upgrading-your-package.md
@@ -159,24 +159,71 @@ To use the new views, you need to specify the `atom-space-pen-views` module in y
 
 ### Converting your views
 
-Sometimes it is as simple as converting the requires at the top of each view page. In the case of our above example, you can just convert them to the following:
+Sometimes it is as simple as converting the requires at the top of each view page. I assume you read the 'TL;DR' section and have updated all of your requires.
+
+### Upgrading classes extending any space-pen View
+
+The `afterAttach` and `beforeRemove` hooks have been replaced with
+`attached` and `detached` and their semantics have been altered. `attached` will only be called when all parents of the View are attached to the DOM.
 
 ```coffee
-{$, View} = require 'space-pen'
-{TextEditorView} = require 'atom-space-pen-views'
+# Old way
+{View} = require 'atom'
+class MyView extends View
+  afterAttach: (onDom) ->
+    #...
+
+  beforeRemove: ->
+    #...
 ```
 
-If you are using the lifecycle hooks, you will need to update code as well.
+```coffee
+# New way
+{View} = require 'atom-space-pen-views'
+class MyView extends View
+  attached: ->
+    # Always called with the equivalent of @afterAttach(true)!
+    #...
 
-### Upgrading to space-pen's TextEditorView
+  removed: ->
+    #...
+```
+
+### Upgrading to the new TextEditorView
 
 You should not need to change anything to use the new `TextEditorView`! See the [docs][TextEditorView] for more info.
 
-### Upgrading to space-pen's ScrollView
+### Upgrading to classes extending ScrollView
 
-See the [docs][ScrollView] for all the options.
+The `ScrollView` has very minor changes.
 
-### Upgrading to space-pen's SelectListView
+You can no longer use `@off` to remove default behavior for `core:move-up`, `core:move-down`, etc.
+
+```coffee
+# Old way to turn off default behavior
+class ResultsView extends ScrollView
+  initialize: (@model) ->
+    super
+    # turn off default scrolling behavior from ScrollView
+    @off 'core:move-up'
+    @off 'core:move-down'
+    @off 'core:move-left'
+    @off 'core:move-right'
+```
+
+```coffee
+# New way to turn off default behavior
+class ResultsView extends ScrollView
+  initialize: (@model) ->
+    disposable = super()
+    # turn off default scrolling behavior from ScrollView
+    disposable.dispose()
+```
+
+* Check out [an example](https://github.com/atom/find-and-replace/pull/311/files#diff-9) from find-and-replace.
+* See the [docs][ScrollView] for all the options.
+
+### Upgrading to classes extending SelectListView
 
 Your SelectListView might look something like this:
 
@@ -254,7 +301,8 @@ class CommandPaletteView extends SelectListView
     @panel?.hide()
 ```
 
-See the [SelectListView docs][SelectListView] for all the options. And check out the [conversion of CommandPaletteView][selectlistview-example] as a real-world example.
+* And check out the [conversion of CommandPaletteView][selectlistview-example] as a real-world example.
+* See the [SelectListView docs][SelectListView] for all options.
 
 ## Specs