Update examples of extend and createChildContext to use a callback fu…

…nctions. Add reference to $rawData.

documentation/custom-bindings-controlling-descendant-bindings.md

@@ -40,16 +40,15 @@ Normally, bindings that use `controlsDescendantBindings` will also call `ko.appl
     ko.bindingHandlers.withProperties = {
         init: function(element, valueAccessor, allBindings, viewModel, bindingContext) {
             // Make a modified binding context, with a extra properties, and apply it to descendant elements
-            var newProperties = valueAccessor(),
-                innerBindingContext = bindingContext.extend(newProperties);
+            var innerBindingContext = bindingContext.extend(valueAccessor);
             ko.applyBindingsToDescendants(innerBindingContext, element);
 
             // Also tell KO *not* to bind the descendants itself, otherwise they will be bound twice
             return { controlsDescendantBindings: true };
         }
     };
 
-As you can see, binding contexts have an `extend` function that produces a clone with extra properties. This doesn't affect the original binding context, so there is no danger of affecting sibling-level elements - it will only affect descendants.
+As you can see, binding contexts have an `extend` function that produces a clone with extra properties. The `extend` function accepts either an object with the properties to copy or a function that returns such an object. The function syntax is preferred so that future changes in the binding value are always updated in the binding context. This process doesn't affect the original binding context, so there is no danger of affecting sibling-level elements - it will only affect descendants.
 
 Here's an example of using the above custom binding:
 
@@ -69,9 +68,12 @@ If you want to do this in custom bindings, then instead of using `bindingContext
     ko.bindingHandlers.withProperties = {
         init: function(element, valueAccessor, allBindings, viewModel, bindingContext) {
             // Make a modified binding context, with a extra properties, and apply it to descendant elements
-            var newProperties = valueAccessor(),
-                childBindingContext = bindingContext.createChildContext(bindingContext.$data);
-            ko.utils.extend(childBindingContext, newProperties);
+            var childBindingContext = bindingContext.createChildContext(
+                bindingContext.$rawData, 
+                null, 
+                function(context) {
+                    ko.utils.extend(context, valueAccessor());
+                });
             ko.applyBindingsToDescendants(childBindingContext, element);
 
             // Also tell KO *not* to bind the descendants itself, otherwise they will be bound twice

documentation/custom-bindings.md

@@ -36,7 +36,7 @@ Whenever the associated observable changes, KO will call your `update` callback,
  * `element` --- The DOM element involved in this binding
  * `valueAccessor` --- A JavaScript function that you can call to get the current model property that is involved in this binding. Call this without passing any parameters (i.e., call `valueAccessor()`) to get the current model property value. To easily accept both observable and plain values, call `ko.unwrap` on the returned value.
  * `allBindings` --- A JavaScript object that you can use to access all the model values bound to this DOM element. Call `allBindings.get('name')` to retrieve the value of the `name` binding (returns `undefined` if the binding doesn't exist); or `allBindings.has('name')` to determine if the `name` binding is present for the current element.
- * `viewModel` --- This parameter is deprecated in Knockout 3.x. Use `bindingContext.$data` to access the view model object instead.
+ * `viewModel` --- This parameter is deprecated in Knockout 3.x. Use `bindingContext.$data` or `bindingContext.$rawData` to access the view model instead.
  * `bindingContext` --- An object that holds the [binding context](http://knockoutjs.com/documentation/binding-context.html) available to this element's bindings. This object includes special properties including `$parent`, `$parents`, and `$root` that can be used to access data that is bound against ancestors of this context.
 
 For example, you might have been controlling an element's visibility using the `visible` binding, but now you want to go a step further and animate the transition. You want elements to slide into and out of existence according to the value of an observable. You can do this by writing a custom binding that calls jQuery's `slideUp`/`slideDown` functions: