Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 57 lines (44 sloc) 9.42 kb
e7b06d7 @mbest Update README.md
authored
1 Better Binding for Knockout
a4013ea @SteveSanderson Added Markdown readme
SteveSanderson authored
2
e7b06d7 @mbest Update README.md
authored
3 What’s great about Knockout?
8117236 @SteveSanderson Updated readme
SteveSanderson authored
4
e7b06d7 @mbest Update README.md
authored
5 * Provides a concise way to link data to the UI through declarative bindings.
6 * Automatically updates the UI based on changing data using observables.
dcffc79 @SteveSanderson Update readme
SteveSanderson authored
7
e7b06d7 @mbest Update README.md
authored
8 What’s new and improved in this update?
9
10 1. When an element in the UI has multiple bindings, each binding is processed separately. For example, an element might have bindings for its color and for its text contents. Previously, when Knockout needed to update the color, it would also update the text (even though the data for the text hadn’t changed). With this update, Knockout will only process the binding that needs it.
11 2. Multiple bindings for an element are processed in a more logical order. For example, a `select` element might have the `options` and `selectedOptions` bindings. Previously, the bindings were processed in the order they were given in the element’s `data-bind` attribute. So if `selectedOptions` was listed first, it would fail to initialize the selected options since the options wouldn’t be in the UI yet. With this update, Knockout knows more about what the bindings do, which it uses to determine which bindings to process first.
12 3. Two-level bindings can be specified using one-level syntax. For example, when binding the load event, you could use `event.load: handler` instead of `event { load: handler }`. Both forms can used, with no functional difference between the two.
13 4. Bindings whose only valid value is *true* can be specified without the value. The only built-in binding this applies to is `uniqueValue`. So you could use `uniqueValue` instead of `uniqueValue: true`.
14 5. Event handler functions are called with the correct `this` value when just the function value is given. Previously, all handler functions were called with `this` set to the value of `$data`. With this update, if you specify `click: $parent.handler`, the handler function will be called with `this` set to `$parent`. This is equivalent to `click: function() { $parent.handler() }` or `click: $parent.handler.bind($parent)`
4f123b2 @mbest Make sure all new functionality and all fixed bugs are represented by sp...
authored
15 6. The `with` binding has been split into two bindings: `with` and `withif`. The new `with` binding doesn’t use the template code and thus is much faster and simpler. It doesn’t modify it’s contents but just pushes a new binding context. The `withif` binding provides the same functionality of the previous `with` binding.
16 7. Certain bindings can be set up to run after their descendants’ bindings have run. This is useful if a binding modifies its descendant elements and needs them to be initialized first.
17 8. The minified code is smaller. Even with a lot of new features (and some additional error reporting), the minified version of this update is slightly smaller than the current master *head*.
e7b06d7 @mbest Update README.md
authored
18
19 What compatibility issues are there with this update?
20
21 1. Users may have custom bindings that rely on being updated when other bindings on the same element are updated. Since this will not be the case with this update (see item #1 above), users must change those custom bindings to specifically subscribe to the model data that should trigger an update.
63af654 @mbest Add 'builtIn' binding flag that's not exported. Warning about out-of-ord...
authored
22 2. Users may rely on a custom binding being processed after another binding based on the order specified in the `data-bind` attribute. But bindings will instead be ordered based on their type (see item #2). To help users debug such problems, Knockout will output a warning message to the browser’s console if the actual run order of the bindings differs from the specified one. Users can solve this problem by specifying an appropriate type for their custom bindings.
4f123b2 @mbest Make sure all new functionality and all fixed bugs are represented by sp...
authored
23 3. Users using `with` that expect it to clear it’s contents if the given value is false (or falsy) should switch to using `withif`.
24 4. Users may assume that `this` in an event handler function will be the same as `$data`. But `this` will now be set to the handler’s object (see item #5). The `$data` object is always passed to the function as the first parameter, and users should update their code to use that instead: `function(data) { dosomethingwith(data); }` instead of `function() { dosomethingwith(this); }`
25 5. Any custom binding that manages the binding of its descendants will need to be changed. It should no longer return a specific object value from its `init` function (doing so will trigger an error). Instead it must set a `flags` property for the handler with a value of ko.bindingFlags.contentBind (see below for the full list of flags).
26 6. `ko.virtualElements.allowedBindings` is no longer used to determine which bindings can be used in container-less elements. Use the `canUseVirtual` flag instead (see below).
27 7. Two Knockout objects are no longer exported: `ko.utils.domNodeDisposal` and `ko.jsonExpressionRewriting`. Both objects were heavily modified in this update, and rather than explaining the changes, it was simpler (and space saving) to not export them.
28 8. The last parameter to `utils.setDomNodeChildrenFromArrayMapping` is a callback function that is called after nodes are added to the document. Anyone using this function and providing that callback will need to update their code to include a third parameter, `subscription`, and call `addDisposalNodes` on the subscription with any of the given nodes that should be watched.
29 9. Observables accessed within a binding’s `init` function will not be tracked and thus will not trigger updates for that binding. Only observables accessed in the `update` function will be tracked.
e7b06d7 @mbest Update README.md
authored
30
31 What are the new interfaces in this update?
32
33 1. Binding handler can set a `flags` property to tell Knockout how the binding is used. Many bindings won’t need to set any flags. The flags are numeric and multiple flags can be set by ORing them together: `flags: ko.bindingFlags.twoWay | ko.bindingFlags.contentSet`. The following are the available flags:
34 * `twoWay`: initialliy writes to the DOM from the model and updates the model property if the DOM changes
35 * `eventHandler`: calls the given function in response to an event
4f123b2 @mbest Make sure all new functionality and all fixed bugs are represented by sp...
authored
36 * `twoLevel`: expects a set of key/value pairs; these can be specified as `binding.key: value` or `binding: {key: value}`
e7b06d7 @mbest Update README.md
authored
37 * `contentSet`: erases or sets the element’s contents
38 * `contentBind`: has responsibility for binding (or not) the element’s contents
39 * `contentUpdate`: modifies or accesses the element’s contents after the content’s bindings have been processed
40 * `canUseVirtual`: can be used in container-less elements like `<!-- ko if: value --><!-- /ko -->`
4f123b2 @mbest Make sure all new functionality and all fixed bugs are represented by sp...
authored
41 * `noValue`: doesn’t require a value (default value is *true*)
e7b06d7 @mbest Update README.md
authored
42 2. `bindingContext.createChildContext` will accept an observable as a data value, which it will automatically unwrap and track for changes. A binding handler that uses this feature avoids having to create a new context and re-bind its descendants if the data value changes.
43 3. `ko.cleanAndRemoveNode` is a more descriptive synonym `ko.removeNode`.
44 4. `ko.computed` exports two new methods: `addDisposalNodes` and `replaceDisposalNodes`. The former can be used instead of (or in addition to) the `disposeWhenNodeIsRemoved` option. The big change is that computed observables can track multiple nodes, which can be changed dynamically. Only when all of the tracked nodes are removed will it be disposed.
45 5. Binding handler functions are called with `this` set to the handler object. This allows binding handlers to use general OO functionality such as inheritance.
4f123b2 @mbest Make sure all new functionality and all fixed bugs are represented by sp...
authored
46 6. `ko.applyBindingsToNode` accepts a fourth parameter, `shouldBindDescendants`.
e7b06d7 @mbest Update README.md
authored
47
48 This update was not meant to fix bugs. However the following bugs were fixed:
49
4f123b2 @mbest Make sure all new functionality and all fixed bugs are represented by sp...
authored
50 1. For `select` elements with both `options` and `value` bindings, where `value` is specified before `options`, removing the currently selected item from the array (or clearing the whole array) will now correctly clear the value. (Previously the value would not be updated.)
51 2. For `select` elements with a `value` binding and no options (where either no `options` binding is given or the binding is after the `value` binding), setting the value’s observable to any value will now reset the value to *undefined*. (Previously the value would be accepted.)
52 3. `ko.computed` now prevents itself from being called recursively. In other words, if a computed observables’s `read` function somehow triggers itself to be re-evaluated, that inner evaluation will not happen. (Previously such a situation would result in a Javascript stack error.)
53
54 Are there any other issues to watch for with this update?
c3be324 @SteveSanderson Updating license info
SteveSanderson authored
55
4f123b2 @mbest Make sure all new functionality and all fixed bugs are represented by sp...
authored
56 1. Processing bindings involves two steps: parsing the binding string to create a function that returns an object, and then calling the binding handlers for each of the properties in that object. Since Knockout uses a cache for the parsing step, each time the same binding string is processed, it will use the same function (with the same object structure) as the first time. With this update, the parsing code uses certain binding handler flags to determine the object structure. Thus the parsing step is no longer deterministic; the cache could become invalid if the type of a binding handler was changed. However, because this is such a fringe case, the cache will always return the original function even if the flags have changed. It’s up to the user to avoid changing the flags for a binding handler after applyBindings is run, or to call `ko.bindingProvider.instance.clearCache` (this is a new function) if the flags must be changed.
Something went wrong with that request. Please try again.