Codestin Search App

+ + You can even set multiple CSS classes based on the same condition by wrapping the names in quotes like: + +

+ + Non-boolean values are interpreted loosely as boolean. For example, `0` and `null` are treated as `false`, whereas `21` and non-`null` objects are treated as `true`. + + If your parameter references an observable value, the binding will add or remove the CSS class whenever the observable value changes. If the parameter doesn't reference an observable value, it will only add or remove the class once and will not do so again later. + + If you want to use dynamic CSS class names, then you can pass a string that corresponds to the CSS class or classes that you want to add to the element. If the parameter references an observable value, then the binding will remove any previously added classes and add the class or classes corresponding to the observable's new value. + + As usual, you can use arbitrary JavaScript expressions or functions as parameter values. KO will evaluate them and use the resulting values to determine the appropriate CSS classes to add or remove. + + * Additional parameters + + * None + +### Note: Applying CSS classes whose names aren't legal JavaScript variable names + +If you want to apply the CSS class `my-class`, you *can't* write this: + +

...

+ +... because `my-class` isn't a legal identifier name at that point. The solution is simple: just wrap the identifier name in quotes so that it becomes a string literal, which is legal in a JavaScript object literal. For example, + +

...

+ +### Dependencies + +None, other than the core Knockout library. \ No newline at end of file diff --git a/documentation/custom-bindings-controlling-descendant-bindings.md b/documentation/custom-bindings-controlling-descendant-bindings.md new file mode 100644 index 000000000..bec8230fc --- /dev/null +++ b/documentation/custom-bindings-controlling-descendant-bindings.md @@ -0,0 +1,94 @@ +--- +layout: documentation +title: Creating custom bindings that control descendant bindings +--- + +*Note: This is an advanced technique, typically used only when creating libraries of reusable bindings. It's not something you'll normally need to do when building applications with Knockout.* + +By default, bindings only affect the element to which they are applied. But what if you want to affect all descendant elements too? This is possible. Your binding can tell Knockout *not* to bind descendants at all, and then your custom binding can do whatever it likes to bind them in a different way. + +To do this, simply return `{ controlsDescendantBindings: true }` from your binding's `init` function. + +### Example: Controlling whether or not descendant bindings are applied + +For a very simple example, here's a custom binding called `allowBindings` that allows descendant bindings to be applied only if its value is `true`. If the value is `false`, then `allowBindings` tells Knockout that it is responsible for descendant bindings so they won't be bound as usual. + + ko.bindingHandlers.allowBindings = { + init: function(elem, valueAccessor) { + // Let bindings proceed as normal *only if* my value is false + var shouldAllowBindings = ko.unwrap(valueAccessor()); + return { controlsDescendantBindings: !shouldAllowBindings }; + } + }; + +To see this take effect, here's a sample usage: + +

+ +

Original

+ +

Original

+ +### Example: Supplying additional values to descendant bindings + +Normally, bindings that use `controlsDescendantBindings` will also call `ko.applyBindingsToDescendants(someBindingContext, element)` to apply the descendant bindings against some modified [binding context](binding-context.html). For example, you could have a binding called `withProperties` that attaches some extra properties to the binding context that will then be available to all descendant bindings: + + 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 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. 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: + +

+ Today I feel . +

+ +### Example: Adding extra levels in the binding context hierarchy + +Bindings such as [`with`](with-binding.html) and [`foreach`](foreach-binding.html) create extra levels in the binding context hierarchy. This means that their descendants can access data at outer levels by using `$parent`, `$parents`, `$root`, or `$parentContext`. + +If you want to do this in custom bindings, then instead of using `bindingContext.extend()`, use `bindingContext.createChildContext(someData)`. This returns a new binding context whose viewmodel is `someData` and whose `$parentContext` is `bindingContext`. If you want, you can then extend the child context with extra properties using `ko.utils.extend`. For example, + + 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 childBindingContext = bindingContext.createChildContext( + bindingContext.$rawData, + null, // Optionally, pass a string here as an alias for the data item in descendant contexts + 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 + return { controlsDescendantBindings: true }; + } + }; + +This updated `withProperties` binding could now be used in a nested way, with each level of nesting able to access the parent level via `$parentContext`: + +

+ The outer display mode is . +

+ The inner display mode is , but I haven't forgotten + that the outer display mode is . +

+ +By modifying binding contexts and controlling descendant bindings, you have a powerful and advanced tool to create custom binding mechanisms of your own. \ No newline at end of file diff --git a/documentation/custom-bindings-for-virtual-elements.md b/documentation/custom-bindings-for-virtual-elements.md new file mode 100644 index 000000000..3b8c7e6b3 --- /dev/null +++ b/documentation/custom-bindings-for-virtual-elements.md @@ -0,0 +1,119 @@ +--- +layout: documentation +title: Creating custom bindings that support virtual elements +--- + +*Note: This is an advanced technique, typically used only when creating libraries of reusable bindings. It's not something you'll normally need to do when building applications with Knockout.* + +Knockout's *control flow bindings* (e.g., [`if`](if-binding.html) and [`foreach`](foreach-binding.html)) can be applied not only to regular DOM elements, but also to "virtual" DOM elements defined by a special comment-based syntax. For example: + +

My heading

+ +Custom bindings can work with virtual elements too, but to enable this, you must explicitly tell Knockout that your binding understands virtual elements, by using the `ko.virtualElements.allowedBindings` API. + +### Example + +To get started, here's a custom binding that randomises the order of DOM nodes: + + ko.bindingHandlers.randomOrder = { + init: function(elem, valueAccessor) { + // Pull out each of the child elements into an array + var childElems = []; + while(elem.firstChild) + childElems.push(elem.removeChild(elem.firstChild)); + + // Put them back in a random order + while(childElems.length) { + var randomIndex = Math.floor(Math.random() * childElems.length), + chosenChild = childElems.splice(randomIndex, 1); + elem.appendChild(chosenChild[0]); + } + } + }; + +This works nicely with regular DOM elements. The following elements will be shuffled into a random order: + +

First

Second

Third

+ +However, it does *not* work with virtual elements. If you try the following: + + +

First

Second

Third

+ + +... then you'll get the error `The binding 'randomOrder' cannot be used with virtual elements`. Let's fix this. To make `randomOrder` usable with virtual elements, start by telling Knockout to allow it. Add the following: + + ko.virtualElements.allowedBindings.randomOrder = true; + +Now there won't be an error. However, it still won't work properly, because our `randomOrder` binding is coded using normal DOM API calls (`firstChild`, `appendChild`, etc.) which don't understand virtual elements. This is the reason why KO requires you to explicitly opt in to virtual element support: unless your custom binding is coded using virtual element APIs, it's not going to work properly! + +Let's update the code for `randomOrder`, this time using KO's virtual element APIs: + + ko.bindingHandlers.randomOrder = { + init: function(elem, valueAccessor) { + // Build an array of child elements + var child = ko.virtualElements.firstChild(elem), + childElems = []; + while (child) { + childElems.push(child); + child = ko.virtualElements.nextSibling(child); + } + + // Remove them all, then put them back in a random order + ko.virtualElements.emptyNode(elem); + while(childElems.length) { + var randomIndex = Math.floor(Math.random() * childElems.length), + chosenChild = childElems.splice(randomIndex, 1); + ko.virtualElements.prepend(elem, chosenChild[0]); + } + } + }; + +Notice how, instead of using APIs like `domElement.firstChild`, we're now using `ko.virtualElements.firstChild(domOrVirtualElement)`. The `randomOrder` binding will now correctly work with virtual elements, e.g., `...`. + +Also, `randomOrder` will still work with regular DOM elements, because all of the `ko.virtualElements` APIs are backwardly compatible with regular DOM elements. + +### Virtual Element APIs + +Knockout provides the following functions for working with virtual elements. + +* `ko.virtualElements.allowedBindings` + + An object whose keys determine which bindings are usable with virtual elements. Set `ko.virtualElements.allowedBindings.mySuperBinding = true` to allow `mySuperBinding` to be used with virtual elements. + +* `ko.virtualElements.emptyNode(containerElem)` + + Removes all child nodes from the real or virtual element `containerElem` (cleaning away any data associated with them to avoid memory leaks). + +* `ko.virtualElements.firstChild(containerElem)` + + Returns the first child of the real or virtual element `containerElem`, or `null` if there are no children. + +* `ko.virtualElements.insertAfter(containerElem, nodeToInsert, insertAfter)` + + Inserts `nodeToInsert` as a child of the real or virtual element `containerElem`, positioned immediately after `insertAfter` (where `insertAfter` must be a child of `containerElem`). + +* `ko.virtualElements.nextSibling(node)` + + Returns the sibling node that follows `node` in its real or virtual parent element, or `null` if there is no following sibling. + +* `ko.virtualElements.prepend(containerElem, nodeToPrepend)` + + Inserts `nodeToPrepend` as the first child of the real or virtual element `containerElem`. + +* `ko.virtualElements.setDomNodeChildren(containerElem, arrayOfNodes)` + + Removes all child nodes from the real or virtual element `containerElem` (in the process, cleaning away any data associated with them to avoid memory leaks), and then inserts all of the nodes from `arrayOfNodes` as its new children. + +Notice that this is *not* intended to be a complete replacement to the full set of regular DOM APIs. Knockout provides only a minimal set of virtual element APIs to make it possible to perform the kinds of transformations needed when implementing control flow bindings. \ No newline at end of file diff --git a/documentation/custom-bindings.md b/documentation/custom-bindings.md new file mode 100644 index 000000000..af241c68f --- /dev/null +++ b/documentation/custom-bindings.md @@ -0,0 +1,147 @@ +--- +layout: documentation +title: Creating custom bindings +--- + +You're not limited to using the built-in bindings like `click`, `value`, and so on --- you can create your own ones. This is how to control how observables interact with DOM elements, and gives you a lot of flexibility to encapsulate sophisticated behaviors in an easy-to-reuse way. + +For example, you can create interactive components like grids, tabsets, and so on, in the form of custom bindings (see the [grid example](../examples/grid.html)). + +### Registering your binding + +To register a binding, add it as a subproperty of `ko.bindingHandlers`: + + ko.bindingHandlers.yourBindingName = { + init: function(element, valueAccessor, allBindings, viewModel, bindingContext) { + // This will be called when the binding is first applied to an element + // Set up any initial state, event handlers, etc. here + }, + update: function(element, valueAccessor, allBindings, viewModel, bindingContext) { + // This will be called once when the binding is first applied to an element, + // and again whenever the associated observable changes value. + // Update the DOM element based on the supplied values here. + } + }; + +... and then you can use it on any number of DOM elements: + +

+ +Note: you don't actually have to provide both `init` *and* `update` callbacks --- you can just provide one or the other if that's all you need. + +### The "update" callback + +Whenever the associated observable changes, KO will call your `update` callback, passing the following parameters: + + * `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` 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: + + ko.bindingHandlers.slideVisible = { + update: function(element, valueAccessor, allBindings) { + // First get the latest data that we're bound to + var value = valueAccessor(); + + // Next, whether or not the supplied model property is observable, get its current value + var valueUnwrapped = ko.unwrap(value); + + // Grab some more data from another binding property + var duration = allBindings.get('slideDuration') || 400; // 400ms is default duration unless otherwise specified + + // Now manipulate the DOM element + if (valueUnwrapped == true) + $(element).slideDown(duration); // Make the element visible + else + $(element).slideUp(duration); // Make the element invisible + } + }; + +Now you can use this binding as follows: + +

You have selected the option

+ Gift wrap + + + +Of course, this is a lot of code at first glance, but once you've created your custom bindings they can very easily be reused in many places. + +### The "init" callback + +Knockout will call your `init` function once for each DOM element that you use the binding on. There are two main uses for `init`: + + * To set any initial state for the DOM element + * To register any event handlers so that, for example, when the user clicks on or modifies the DOM element, you can change the state of the associated observable + +KO will pass exactly the same set of parameters that it passes to [the `update` callback](#the_update_callback). + +Continuing the previous example, you might want `slideVisible` to set the element to be instantly visible or invisible when the page first appears (without any animated slide), so that the animation only runs when the user changes the model state. You could do that as follows: + + ko.bindingHandlers.slideVisible = { + init: function(element, valueAccessor) { + var value = ko.unwrap(valueAccessor()); // Get the current value of the current property we're bound to + $(element).toggle(value); // jQuery will hide/show the element depending on whether "value" or true or false + }, + update: function(element, valueAccessor, allBindings) { + // Leave as before + } + }; + +This means that if `giftWrap` was defined with the initial state `false` (i.e., `giftWrap: ko.observable(false)`) then the associated DIV would initially be hidden, and then would slide into view when the user later checks the box. + +### Modifying observables after DOM events + +You've already seen how to use `update` so that, when an observable changes, you can update an associated DOM element. But what about events in the other direction? When the user performs some action on a DOM element, you might want to updated an associated observable. + +You can use the `init` callback as a place to register an event handler that will cause changes to the associated observable. For example, + + ko.bindingHandlers.hasFocus = { + init: function(element, valueAccessor) { + $(element).focus(function() { + var value = valueAccessor(); + value(true); + }); + $(element).blur(function() { + var value = valueAccessor(); + value(false); + }); + }, + update: function(element, valueAccessor) { + var value = valueAccessor(); + if (ko.unwrap(value)) + element.focus(); + else + element.blur(); + } + }; + +Now you can both read and write the "focusedness" of an element by binding it to an observable: + +

Name:

+ + +

You're editing the name

+ + + + +### Note: Supporting virtual elements + +If you want a custom binding to be usable with Knockout's *virtual elements* syntax, e.g.: + + ... + +... then see [the documentation for virtual elements](custom-bindings-for-virtual-elements.html). \ No newline at end of file diff --git a/documentation/dependentObservables.md b/documentation/dependentObservables.md new file mode 100644 index 000000000..e374f83be --- /dev/null +++ b/documentation/dependentObservables.md @@ -0,0 +1,8 @@ +--- +layout: documentation +title: Dependent Observables +--- + +Since Knockout 2.0, dependent observables are now called *computed observables*. You can find documentation for them [here](computedObservables.html). + +Note that this rename does not cause any backward compatibility problems. At runtime, `ko.dependentObservable` refers to the same function as `ko.computed`, so your existing code will continue to work just fine. \ No newline at end of file diff --git a/documentation/disable-binding.md b/documentation/disable-binding.md new file mode 100644 index 000000000..122256e45 --- /dev/null +++ b/documentation/disable-binding.md @@ -0,0 +1,9 @@ +--- +layout: documentation +title: The "disable" binding +--- + +### Purpose +The `disable` binding causes the associated DOM element to be disabled only when the parameter value is `true`. This is useful with form elements like `input`, `select`, and `textarea`. + +This is the mirror image of the `enable` binding. For more information, see [documentation for the `enable` binding](enable-binding.html), because `disable` works in exactly the same way except that it negates whatever parameter you pass to it. \ No newline at end of file diff --git a/documentation/enable-binding.md b/documentation/enable-binding.md new file mode 100644 index 000000000..6a7ae6ed1 --- /dev/null +++ b/documentation/enable-binding.md @@ -0,0 +1,52 @@ +--- +layout: documentation +title: The "enable" binding +--- + +### Purpose +The `enable` binding causes the associated DOM element to be enabled only when the parameter value is `true`. This is useful with form elements like `input`, `select`, and `textarea`. + +### Example +

+ + I have a cellphone +

+ Your cellphone number: + +

+ + + +In this example, the "Your cellphone number" text box will initially be disabled. It will be enabled only when the user checks the box labelled "I have a cellphone". + +### Parameters + + * Main parameter + + A value that controls whether or not the associated DOM element should be enabled. + + Non-boolean values are interpreted loosely as boolean. For example, `0` and `null` are treated as `false`, whereas `21` and non-`null` objects are treated as `true`. + + If your parameter references an observable value, the binding will update the enabled/disabled state whenever the observable value changes. If the parameter doesn't reference an observable value, it will only set the state once and will not do so again later. + + * Additional parameters + + * None + +### Note: Using arbitrary JavaScript expressions + +You're not limited to referencing variables - you can reference arbitrary expressions to control an element's enabledness. For example, + + + +### Dependencies + +None, other than the core Knockout library. \ No newline at end of file diff --git a/documentation/event-binding.md b/documentation/event-binding.md new file mode 100644 index 000000000..905cfc6f0 --- /dev/null +++ b/documentation/event-binding.md @@ -0,0 +1,133 @@ +--- +layout: documentation +title: The "event" binding +--- + +### Purpose +The `event` binding allows you to add an event handler for a specified event so that your chosen JavaScript function will be invoked when that event is triggered for the associated DOM element. This can be used to bind to any event, such as `keypress`, `mouseover` or `mouseout`. + +### Example +

+ Mouse over me +

+ Details +

+ + + +Now, moving your mouse pointer on or off of the first element will invoke methods on the view model to toggle the `detailsEnabled` observable. The second element reacts to changes to the value of `detailsEnabled` by either showing or hiding itself. + +### Parameters + + * Main parameter + + You should pass a JavaScript object in which the property names correspond to event names, and the values correspond to the function that you want to bind to the event. + + You can reference any JavaScript function - it doesn't have to be a function on your view model. You can reference a function on any object by writing `event { mouseover: someObject.someFunction }`. + + * Additional parameters + + * None + +### Note 1: Passing a "current item" as a parameter to your handler function + +When calling your handler, Knockout will supply the current model value as the first parameter. This is particularly useful if you're rendering +some UI for each item in a collection, and you need to know which item the event refers to. For example, + +

You seem to be interested in:

+ + + +Two points to note about this example: + + * If you're inside a nested [binding context](binding-context.html), for example if you're inside a `foreach` or a `with` block, but your handler function + is on the root viewmodel or some other parent context, you'll need to use a prefix such as `$parent` or `$root` to locate the + handler function. + * In your viewmodel, it's often useful to declare `self` (or some other variable) as an alias for `this`. Doing so avoids any problems + with `this` being redefined to mean something else in event handlers or Ajax request callbacks. + +### Note 2: Accessing the event object, or passing more parameters + +In some scenarios, you may need to access the DOM event object associated with your event. Knockout will pass the event as the second parameter to your function, as in this example: + +

+ Mouse over me +

+ + + +If you need to pass more parameters, one way to do it is by wrapping your handler in a function literal that takes in a parameter, as in this example: + +

+ Mouse over me +

+ +Now, KO will pass the event to your function literal, which is then available to be passed to your handler. + +Alternatively, if you prefer to avoid the function literal in your view, you can use the [bind](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function/bind) function, which attaches specific parameter values to a function reference: + + + +### Note 3: Allowing the default action + +By default, Knockout will prevent the event from taking any default action. For example if you use the `event` binding to capture the `keypress` event of an `input` tag, the browser will only call your handler function and will *not* add the value of the key to the `input` element's value. A more common example is using [the click binding](click-binding.html), which internally uses this binding, where your handler function will be called, but the browser will *not* navigate to the link's `href`. This is a useful default because when you use the `click` binding, it's normally because you're using the link as part of a UI that manipulates your view model, not as a regular hyperlink to another web page. + +However, if you *do* want to let the default action proceed, just return `true` from your `event` handler function. + +### Note 4: Preventing the event from bubbling + +By default, Knockout will allow the event to continue to bubble up to any higher level event handlers. For example, if your element is handling a `mouseover` event and a parent of the element also handles that same event, then the event handler for both elements will be triggered. If necessary, you can prevent the event from bubbling by including an additional binding that is named `youreventBubble` and passing false to it, as in this example: + +

+ +

+ +Normally, in this case `myButtonHandler` would be called first, then the event would bubble up to `myDivHandler`. However, the `mouseoverBubble` binding that we added with a value of `false` prevents the event from making it past `myButtonHandler`. + +### Dependencies + +None, other than the core Knockout library. \ No newline at end of file diff --git a/documentation/extenders.md b/documentation/extenders.md new file mode 100644 index 000000000..3eabe523f --- /dev/null +++ b/documentation/extenders.md @@ -0,0 +1,137 @@ +--- +layout: documentation +title: Using extenders to augment observables +--- + +Knockout observables provide the basic features necessary to support reading/writing values and notifying subscribers when that value changes. In some cases, though, you may wish to add additional functionality to an observable. This might include adding additional properties to the observable or intercepting writes by placing a writeable computed observable in front of the observable. Knockout extenders provide an easy and flexible way to do this type of augmentation to an observable. + +### How to create an extender +Creating an extender involves adding a function to the `ko.extenders` object. The function takes in the observable itself as the first argument and any options in the second argument. It can then either return the observable or return something new like a computed observable that uses the original observable in some way. + + This simple `logChange` extender subscribes to the observable and uses the console to write any changes along with a configurable message. + + ko.extenders.logChange = function(target, option) { + target.subscribe(function(newValue) { + console.log(option + ": " + newValue); + }); + return target; + }; + +You would use this extender by calling the `extend` function of an observable and passing an object that contains a `logChange` property. + + this.firstName = ko.observable("Bob").extend({logChange: "first name"}); + +If the `firstName` observable's value was changed to `Ted`, then the console would show `first name: Ted`. + +### Live Example 1: Forcing input to be numeric + +This example creates an extender that forces writes to an observable to be numeric rounded to a configurable level of precision. In this case, the extender will return a new writeable computed observable that will sit in front of the real observable intercepting writes. + + + +{% capture live_example_id %}numericFields{% endcapture %} +{% capture live_example_view %} +

(round to whole number)

(round to two decimals)

+{% endcapture %} + +{% capture live_example_viewmodel %} +ko.extenders.numeric = function(target, precision) { + //create a writeable computed observable to intercept writes to our observable + var result = ko.computed({ + read: target, //always return the original observables value + write: function(newValue) { + var current = target(), + roundingMultiplier = Math.pow(10, precision), + newValueAsNum = isNaN(newValue) ? 0 : parseFloat(+newValue), + valueToWrite = Math.round(newValueAsNum * roundingMultiplier) / roundingMultiplier; + + //only write if it changed + if (valueToWrite !== current) { + target(valueToWrite); + } else { + //if the rounded value is the same, but a different value was written, force a notification for the current field + if (newValue !== current) { + target.notifySubscribers(valueToWrite); + } + } + } + }).extend({ notify: 'always' }); + + //initialize with current value to make sure it is rounded appropriately + result(target()); + + //return the new computed observable + return result; +}; + +function AppViewModel(one, two) { + this.myNumberOne = ko.observable(one).extend({ numeric: 0 }); + this.myNumberTwo = ko.observable(two).extend({ numeric: 2 }); +} + +ko.applyBindings(new AppViewModel(221.2234, 123.4525)); +{% endcapture %} + +{% include live-example-minimal.html %} + +Note that for this to automatically erase rejected values from the UI, it's necessary to use `.extend({ notify: 'always' })` on the computed observable. Without this, it's possible for the user to enter an invalid `newValue` that when rounded gives an unchanged `valueToWrite`. Then, since the model value would not be changing, there would be no notification to update the textbox in the UI. Using `{ notify: 'always' }` causes the textbox to refresh (erasing rejected values) even if the computed property has not changed value. + +### Live Example 2: Adding validation to an observable + +This example creates an extender that allows an observable to be marked as required. Instead of returning a new object, this extender simply adds additional sub-observables to the existing observable. Since observables are functions, they can actually have their own properties. However, when the view model is converted to JSON, the sub-observables will be dropped and we will simply be left with the value of our actual observable. This is a nice way to add additional functionality that is only relevant for the UI and does not need to be sent back to the server. + +{% capture live_example_id %}requiredFields{% endcapture %} +{% capture live_example_view %} +

+ + +

+{% endcapture %} + +{% capture live_example_viewmodel %} +ko.extenders.required = function(target, overrideMessage) { + //add some sub-observables to our observable + target.hasError = ko.observable(); + target.validationMessage = ko.observable(); + + //define a function to do validation + function validate(newValue) { + target.hasError(newValue ? false : true); + target.validationMessage(newValue ? "" : overrideMessage || "This field is required"); + } + + //initial validation + validate(target()); + + //validate whenever the value changes + target.subscribe(validate); + + //return the original observable + return target; +}; + +function AppViewModel(first, last) { + this.firstName = ko.observable(first).extend({ required: "Please enter a first name" }); + this.lastName = ko.observable(last).extend({ required: "" }); +} + +ko.applyBindings(new AppViewModel("Bob","Smith")); +{% endcapture %} + +{% include live-example-minimal.html %} + +### Applying multiple extenders + +More than one extender can be applied in a single call to the `.extend` method of an observable. + + this.firstName = ko.observable(first).extend({ required: "Please enter a first name", logChange: "first name" }); + +In this case, both the `required` and `logChange` extenders would be executed against our observable. \ No newline at end of file diff --git a/documentation/fn.md b/documentation/fn.md new file mode 100644 index 000000000..fa6e0ad19 --- /dev/null +++ b/documentation/fn.md @@ -0,0 +1,108 @@ +--- +layout: documentation +title: Adding custom functions using "fn" +--- + +Occasionally, you may find opportunities to streamline your code by attaching new functionality to Knockout's core value types. You can define custom functions on any of the following types: + +![](images/fn/type-hierarchy.png) + +Because of inheritance, if you attach a function to `ko.subscribable`, it will be available on all the others too. If you attach a function to `ko.observable`, it will be inherited by `ko.observableArray` but not by `ko.computed`. + +To attach a custom function, add it to one of the following extensibility points: + + * `ko.subscribable.fn` + * `ko.observable.fn` + * `ko.observableArray.fn` + * `ko.computed.fn` + +Then, your custom function will become available on all values of that type created from that point onwards. + +***Note:*** It's best to use this extensibility point only for custom functions that are truly applicable in a wide range of scenarios. You don't need to add a custom function to these namespaces if you're only planning to use it once. + +### Example: A filtered view of an observable array + +Here's a way to define a `filterByProperty` function that will become available on all subsequently-created `ko.observableArray` instances: + + ko.observableArray.fn.filterByProperty = function(propName, matchValue) { + return ko.computed(function() { + var allItems = this(), matchingItems = []; + for (var i = 0; i < allItems.length; i++) { + var current = allItems[i]; + if (ko.unwrap(current[propName]) === matchValue) + matchingItems.push(current); + } + return matchingItems; + }, this); + } + +This returns a new `ko.computed` value that provides a filtered view of the array, while leaving the original array unchanged. Because the filtered array is a `ko.computed`, it will be re-evaluated automatically whenever the underlying array changes. + +The following live example shows how you could use this: + + + +{% capture live_example_view %} +

All tasks ( )

+ + + + +

+ +

Done tasks ( )

+{% endcapture %} + +{% capture live_example_viewmodel %} +function Task(title, done) { + this.title = ko.observable(title); + this.done = ko.observable(done); +} + +function AppViewModel() { + this.tasks = ko.observableArray([ + new Task('Find new desktop background', true), + new Task('Put shiny stickers on laptop', false), + new Task('Request more reggae music in the office', true) + ]); + + // Here's where we use the custom function + this.doneTasks = this.tasks.filterByProperty("done", true); +} + +ko.applyBindings(new AppViewModel()); +{% endcapture %} + +{% include live-example-minimal.html %} + +#### It's not mandatory + +If you tend to filter observable arrays a lot, adding a `filterByProperty` globally to all observable arrays might make your code tidier. But if you only need to filter occasionally, you could instead choose *not* to attach to `ko.observableArray.fn`, and instead just construct `doneTasks` by hand as follows: + + this.doneTasks = ko.computed(function() { + var all = this.tasks(), done = []; + for (var i = 0; i < all.length; i++) + if (all[i].done()) + done.push(all[i]); + return done; + }, this); \ No newline at end of file diff --git a/documentation/foreach-binding.md b/documentation/foreach-binding.md new file mode 100644 index 000000000..de5ff2837 --- /dev/null +++ b/documentation/foreach-binding.md @@ -0,0 +1,280 @@ +--- +layout: documentation +title: The "foreach" binding +--- + +### Purpose +The `foreach` binding duplicates a section of markup for each entry in an array, and binds each copy of that markup to the corresponding array item. This is especially useful for rendering lists or tables. + +Assuming your array is an [observable array](observableArrays.html), whenever you later add, remove, or re-order array entries, the binding will efficiently update the UI to match - inserting or removing more copies of the markup, or re-ordering existing DOM elements, without affecting any other DOM elements. This is far faster than regenerating the entire `foreach` output after each array change. + +Of course, you can arbitrarily nest any number of `foreach` bindings along with other control-flow bindings such as `if` and `with`. + +### Example 1: Iterating over an array + +This example uses `foreach` to produce a read-only table with a row for each array entry. + + + + + + + + + + + +

First name	Last name

+ + + +### Example 2: Live example with add/remove + +The following example shows that, if your array is observable, then the UI will be kept in sync with changes to that array. + +{% capture live_example_view %} +

People

+ Name at position : + + Remove +

+ +{% endcapture %} + +{% capture live_example_viewmodel %} +function AppViewModel() { + var self = this; + + self.people = ko.observableArray([ + { name: 'Bert' }, + { name: 'Charles' }, + { name: 'Denise' } + ]); + + self.addPerson = function() { + self.people.push({ name: "New at " + new Date() }); + }; + + self.removePerson = function() { + self.people.remove(this); + } +} + +ko.applyBindings(new AppViewModel()); +{% endcapture %} + +{% include live-example-minimal.html %} + +### Parameters + + * Main parameter + + Pass the array that you wish to iterate over. The binding will output a section of markup for each entry. + + Alternatively, pass a JavaScript object literal with a property called `data` which is the array you wish to iterate over. The object + literal may also have other properties, such as `afterAdd` or `includeDestroyed` --- see below for details of these extra options and + examples of their use. + + If the array you supply is observable, the `foreach` binding will respond to any future changes in the array's contents by adding or + removing corresponding sections of markup in the DOM. + + * Additional parameters + + * None + +### Note 1: Referring to each array entry using $data + +As shown in the above examples, bindings within the `foreach` block can refer to properties on the array entries. For example, [Example 1](#example_1_iterating_over_an_array) referenced the `firstName` and `lastName` properties on each array entry. + +But what if you want to refer to the array entry itself (not just one of its properties)? In that case, you can use the [special context property](binding-context.html) `$data`. Within a `foreach` block, it means "the current item". For example, + +

+ The current item is: +

+ + + +If you wanted, you could use `$data` as a prefix when referencing properties on each entry. For example, you could rewrite part of [Example 1](#example_1_iterating_over_an_array) as follows: + + + +... but you don't have to, because `firstName` will be evaluated within the context of `$data` by default anyway. + +### Note 2: Using $index, $parent, and other context properties + +As you can see from Example 2 above, it's possible to use `$index` to refer to the zero-based index of the current array item. `$index` is an observable and is updated whenever the index of the item changes (e.g., if items are added to or removed from the array). + +Similarly, you can use `$parent` to refer to data from outside the `foreach`, e.g.: + +

+ likes the blog post +

+ +For more information about `$index` and other context properties such as `$parent`, see documentation for [binding context properties](binding-context.html). + +### Note 3: Using "as" to give an alias to "foreach" items + +As described in Note 1, you can refer to each array entry using the `$data` [context variable](binding-context.html). In some cases though, it may be useful to give the current item a more descriptive name using the `as` option like: + +

+ +Now anywhere inside this `foreach` loop, bindings will be able to refer to `person` to access the current array item, from the `people` array, that is being rendered. This can be especially useful in scenarios where you have nested `foreach` blocks and you need to refer to an item declared at a higher level in the hierarchy. For example: + +

+
- + : + +
+

+ + + +Tip: Remember to pass a *string literal value* to `as` (e.g., `as: 'category'`, *not* `as: category`), because you are giving a name for a new variable, not reading the value of a variable that already exists. + + +### Note 4: Using foreach without a container element + +In some cases, you might want to duplicate a section of markup, but you don't have any container element on which to put a `foreach` binding. For example, you might want to generate the following: + +

Header item
Item A
Item B
Item C

+ +In this example, there isn't anywhere to put a normal `foreach` binding. You can't put it on the `

` elements are allowed inside `

Header item
Item

+ ... +

The textbox has focus

` or an `` element depending on the model's `editing` property. Unfocusing the `` element sets `editing` to `false`, so the UI switches out of "edit" mode. + +{% capture live_example_id %}click_to_edit{% endcapture %} +{% capture live_example_view %} +

+ Name: + + +

Click the name to edit it; click elsewhere to apply changes.

+{% endcapture %} + +{% capture live_example_viewmodel %} +function PersonViewModel(name) { + // Data + this.name = ko.observable(name); + this.editing = ko.observable(false); + + // Behaviors + this.edit = function() { this.editing(true) } +} + +ko.applyBindings(new PersonViewModel("Bert Bertington")); +{% endcapture %} + +{% include live-example-minimal.html %} + + +### Parameters + + * Main parameter + + Pass `true` (or some value that evaluates as true) to focus the associated element. Otherwise, the associated element will be unfocused. + + When the user manually focuses or unfocuses the element, your value will be set to `true` or `false` accordingly. + + If the value you supply is observable, the `hasFocus` binding will update the element's focus state whenever that observable value changes. + + * Additional parameters + + * None + +### Dependencies + +None, other than the core Knockout library. \ No newline at end of file diff --git a/documentation/html-binding.md b/documentation/html-binding.md new file mode 100644 index 000000000..907cad90b --- /dev/null +++ b/documentation/html-binding.md @@ -0,0 +1,41 @@ +--- +layout: documentation +title: The "html" binding +--- + +### Purpose +The `html` binding causes the associated DOM element to display the HTML specified by your parameter. + +Typically this is useful when values in your view model are actually strings of HTML markup that you want to render. + +### Example +

+ + + +### Parameters + + * Main parameter + + KO sets the element's `innerHTML` property to your parameter value. Any previous content will be overwritten. + + If this parameter is an observable value, the binding will update the element's content whenever the value changes. If the parameter isn't observable, it will only set the element's content once and will not update it again later. + + If you supply something other than a number or a string (e.g., you pass an object or an array), the `innerHTML` will be equivalent to `yourParameter.toString()` + + * Additional parameters + + * None + +### Note: About HTML encoding + +Since this binding sets your element's content using `innerHTML`, you should be careful not to use it with untrusted model values, because that might open the possibility of a script injection attack. If you cannot guarantee that the content is safe to display (for example, if it is based on a different user's input that was stored in your database), then you can use [the text binding](text-binding.html), which will set the element's text value using `innerText` or `textContent` instead. + +### Dependencies + +None, other than the core Knockout library. \ No newline at end of file diff --git a/documentation/if-binding.md b/documentation/if-binding.md new file mode 100644 index 000000000..e66ba3a17 --- /dev/null +++ b/documentation/if-binding.md @@ -0,0 +1,90 @@ +--- +layout: documentation +title: The "if" binding +--- + +### Purpose +The `if` binding causes a section of markup to appear in your document (and to have its `data-bind` attributes applied), only if a specified expression evaluates to `true` (or a `true`-ish value such as a non-`null` object or nonempty string). + +`if` plays a similar role to [the `visible` binding](visible-binding.html). The difference is that, with `visible`, the contained markup always remains in the DOM and always has its `data-bind` attributes applied - the `visible` binding just uses CSS to toggle the container element's visiblity. The `if` binding, however, physically adds or removes the contained markup in your DOM, and only applies bindings to descendants if the expression is `true`. + +### Example 1 + +This example shows that the `if` binding can dynamically add and remove sections of markup as observable values change. + +{% capture live_example_view %} + Display message + +

Here is a message. Astonishing.

+{% endcapture %} + +{% capture live_example_viewmodel %} +ko.applyBindings({ + displayMessage: ko.observable(false) +}); +{% endcapture %} + +{% include live-example-minimal.html %} + +### Example 2 + +In the following example, the `

` element will be empty for "Mercury", but populated for "Earth". That's because Earth has a non-null `capital` property, whereas "Mercury" has `null` for that property. + +

+ Planet: +
+ Capital: +
+

+ + + + +It's important to understand that the `if` binding really is vital to make this code work properly. Without it, there would be an error when trying to evaluate `capital.cityName` in the context of "Mercury" where `capital` is `null`. In JavaScript, you're not allowed to evaluate subproperties of `null` or `undefined` values. + +### Parameters + + * Main parameter + + The expression you wish to evaluate. If it evaluates to `true` (or a true-ish value), the contained markup will be present in the document, and any `data-bind` attributes on it will be applied. If your expression evaluates to `false`, the contained markup will be removed from your document without first applying any bindings to it. + + If your expression involves any observable values, the expression will be re-evaluated whenever any of them change. Correspondingly, the markup within your `if` block can be added or removed dynamically as the result of the expression changes. `data-bind` attributes will be applied to **a new copy of the contained markup** whenever it is re-added. + + * Additional parameters + + * None + +### Note: Using "if" without a container element + +Sometimes you may want to control the presence/absence of a section of markup *without* having any container element that can hold an `if` binding. For example, you might want to control whether a certain `

` element appears alongside siblings that always appear: + +

This item always appears
I want to make this item present/absent dynamically

+ +In this case, you can't put `if` on the `

` too), and you can't put any other container around the second `

` (because HTML doesn't allow extra containers within `

This item always appears
I want to make this item present/absent dynamically

...

+ Featured menu item +

+ $ +

Choose some countries you'd like to visit:

+ Your country: + +

+ You have chosen a country with population + . +

Gift name	Price	+
		Delete

"; + var items = ko.observableArray(["Alpha", "Beta"]); + + ko.applyBindings({ items: items }, testNode); + expect(testNode).toContainText('AlphaAlphaBetaBeta'); + + // Check that modifying the observable array has the expected effect + items.splice(0, 1); + expect(testNode).toContainText('BetaBeta'); + items.push('Gamma'); + expect(testNode).toContainText('BetaBetaGammaGamma'); + }); +}); diff --git a/spec/observableArrayBehaviors.js b/spec/observableArrayBehaviors.js new file mode 100644 index 000000000..fa595760d --- /dev/null +++ b/spec/observableArrayBehaviors.js @@ -0,0 +1,279 @@ + +describe('Observable Array', function() { + beforeEach(function () { + testObservableArray = new ko.observableArray([1, 2, 3]); + notifiedValues = []; + testObservableArray.subscribe(function (value) { + notifiedValues.push(value ? value.slice(0) : value); + }); + beforeNotifiedValues = []; + testObservableArray.subscribe(function (value) { + beforeNotifiedValues.push(value ? value.slice(0) : value); + }, null, "beforeChange"); + }); + + it('Should be observable', function () { + expect(ko.isObservable(testObservableArray)).toEqual(true); + }); + + it('Should initialize to empty array if you pass no args to constructor', function() { + var instance = new ko.observableArray(); + expect(instance().length).toEqual(0); + }); + + it('Should require constructor arg, if given, to be array-like or null or undefined', function() { + // Try non-array-like args + expect(function () { ko.observableArray(1); }).toThrow(); + expect(function () { ko.observableArray({}); }).toThrow(); + + // Try allowed args + expect((new ko.observableArray([1,2,3]))().length).toEqual(3); + expect((new ko.observableArray(null))().length).toEqual(0); + expect((new ko.observableArray(undefined))().length).toEqual(0); + }); + + it('Should be able to write values to it', function () { + testObservableArray(['X', 'Y']); + expect(notifiedValues.length).toEqual(1); + expect(notifiedValues[0][0]).toEqual('X'); + expect(notifiedValues[0][1]).toEqual('Y'); + }); + + it('Should be able to mark single items as destroyed', function() { + var x = {}, y = {}; + testObservableArray([x, y]); + testObservableArray.destroy(y); + expect(testObservableArray().length).toEqual(2); + expect(x._destroy).toEqual(undefined); + expect(y._destroy).toEqual(true); + }); + + it('Should be able to mark multiple items as destroyed', function() { + var x = {}, y = {}, z = {}; + testObservableArray([x, y, z]); + testObservableArray.destroyAll([x, z]); + expect(testObservableArray().length).toEqual(3); + expect(x._destroy).toEqual(true); + expect(y._destroy).toEqual(undefined); + expect(z._destroy).toEqual(true); + }); + + it('Should be able to mark observable items as destroyed', function() { + var x = ko.observable(), y = ko.observable(); + testObservableArray([x, y]); + testObservableArray.destroy(y); + expect(testObservableArray().length).toEqual(2); + expect(x._destroy).toEqual(undefined); + expect(y._destroy).toEqual(true); + }); + + it('Should be able to mark all items as destroyed by passing no args to destroyAll()', function() { + var x = {}, y = {}, z = {}; + testObservableArray([x, y, z]); + testObservableArray.destroyAll(); + expect(testObservableArray().length).toEqual(3); + expect(x._destroy).toEqual(true); + expect(y._destroy).toEqual(true); + expect(z._destroy).toEqual(true); + }); + + it('Should notify subscribers on push', function () { + testObservableArray.push("Some new value"); + expect(notifiedValues).toEqual([[1, 2, 3, "Some new value"]]); + }); + + it('Should notify "beforeChange" subscribers before push', function () { + testObservableArray.push("Some new value"); + expect(beforeNotifiedValues).toEqual([[1, 2, 3]]); + }); + + it('Should notify subscribers on pop', function () { + var popped = testObservableArray.pop(); + expect(popped).toEqual(3); + expect(notifiedValues).toEqual([[1, 2]]); + }); + + it('Should notify "beforeChange" subscribers before pop', function () { + var popped = testObservableArray.pop(); + expect(popped).toEqual(3); + expect(beforeNotifiedValues).toEqual([[1, 2, 3]]); + }); + + it('Should notify subscribers on splice', function () { + var spliced = testObservableArray.splice(1, 1); + expect(spliced).toEqual([2]); + expect(notifiedValues).toEqual([[1, 3]]); + }); + + it('Should notify "beforeChange" subscribers before splice', function () { + var spliced = testObservableArray.splice(1, 1); + expect(spliced).toEqual([2]); + expect(beforeNotifiedValues).toEqual([[1, 2, 3]]); + }); + + it('Should notify subscribers on remove by value', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + notifiedValues = []; + var removed = testObservableArray.remove("Beta"); + expect(removed).toEqual(["Beta"]); + expect(notifiedValues).toEqual([["Alpha", "Gamma"]]); + }); + + it('Should notify subscribers on remove by predicate', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + notifiedValues = []; + var removed = testObservableArray.remove(function (value) { return value == "Beta"; }); + expect(removed).toEqual(["Beta"]); + expect(notifiedValues).toEqual([["Alpha", "Gamma"]]); + }); + + it('Should notify subscribers on remove multiple by value', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + notifiedValues = []; + var removed = testObservableArray.removeAll(["Gamma", "Alpha"]); + expect(removed).toEqual(["Alpha", "Gamma"]); + expect(notifiedValues).toEqual([["Beta"]]); + }); + + it('Should clear observable array entirely if you pass no args to removeAll()', function() { + testObservableArray(["Alpha", "Beta", "Gamma"]); + notifiedValues = []; + var removed = testObservableArray.removeAll(); + expect(removed).toEqual(["Alpha", "Beta", "Gamma"]); + expect(notifiedValues).toEqual([[]]); + }); + + it('Should notify "beforeChange" subscribers before remove', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + beforeNotifiedValues = []; + var removed = testObservableArray.remove("Beta"); + expect(removed).toEqual(["Beta"]); + expect(beforeNotifiedValues).toEqual([["Alpha", "Beta", "Gamma"]]); + }); + + it('Should not notify subscribers on remove by value with no match', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + notifiedValues = []; + var removed = testObservableArray.remove("Delta"); + expect(removed).toEqual([]); + expect(notifiedValues).toEqual([]); + }); + + it('Should not notify "beforeChange" subscribers before remove by value with no match', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + beforeNotifiedValues = []; + var removed = testObservableArray.remove("Delta"); + expect(removed).toEqual([]); + expect(beforeNotifiedValues).toEqual([]); + }); + + it('Should modify original array on remove', function () { + var originalArray = ["Alpha", "Beta", "Gamma"]; + testObservableArray(originalArray); + notifiedValues = []; + var removed = testObservableArray.remove("Beta"); + expect(originalArray).toEqual(["Alpha", "Gamma"]); + }); + + it('Should modify original array on removeAll', function () { + var originalArray = ["Alpha", "Beta", "Gamma"]; + testObservableArray(originalArray); + notifiedValues = []; + var removed = testObservableArray.removeAll(); + expect(originalArray).toEqual([]); + }); + + it('Should remove matching observable items', function() { + var x = ko.observable(), y = ko.observable(); + testObservableArray([x, y]); + notifiedValues = []; + var removed = testObservableArray.remove(y); + expect(testObservableArray()).toEqual([x]); + expect(removed).toEqual([y]); + expect(notifiedValues).toEqual([[x]]); + }); + + it('Should notify subscribers on replace', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + notifiedValues = []; + testObservableArray.replace("Beta", "Delta"); + expect(notifiedValues).toEqual([["Alpha", "Delta", "Gamma"]]); + }); + + it('Should notify "beforeChange" subscribers before replace', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + beforeNotifiedValues = []; + testObservableArray.replace("Beta", "Delta"); + expect(beforeNotifiedValues).toEqual([["Alpha", "Beta", "Gamma"]]); + }); + + it('Should notify subscribers after marking items as destroyed', function () { + var x = {}, y = {}, didNotify = false; + testObservableArray([x, y]); + testObservableArray.subscribe(function(value) { + expect(x._destroy).toEqual(undefined); + expect(y._destroy).toEqual(true); + didNotify = true; + }); + testObservableArray.destroy(y); + expect(didNotify).toEqual(true); + }); + + it('Should notify "beforeChange" subscribers before marking items as destroyed', function () { + var x = {}, y = {}, didNotify = false; + testObservableArray([x, y]); + testObservableArray.subscribe(function(value) { + expect(x._destroy).toEqual(undefined); + expect(y._destroy).toEqual(undefined); + didNotify = true; + }, null, "beforeChange"); + testObservableArray.destroy(y); + expect(didNotify).toEqual(true); + }); + + it('Should be able to return first index of item', function () { + testObservableArray(["Alpha", "Beta", "Gamma"]); + expect(testObservableArray.indexOf("Beta")).toEqual(1); + expect(testObservableArray.indexOf("Gamma")).toEqual(2); + expect(testObservableArray.indexOf("Alpha")).toEqual(0); + expect(testObservableArray.indexOf("fake")).toEqual(-1); + }); + + it('Should return 0 when you call myArray.length, and the true length when you call myArray().length', function() { + testObservableArray(["Alpha", "Beta", "Gamma"]); + expect(testObservableArray.length).toEqual(0); // Because JavaScript won't let us override "length" directly + expect(testObservableArray().length).toEqual(3); + }); + + it('Should be able to call standard mutators without creating a subscription', function() { + var timesEvaluated = 0, + newArray = ko.observableArray(["Alpha", "Beta", "Gamma"]); + + var computed = ko.computed(function() { + // Make a few standard mutations + newArray.push("Delta"); + newArray.remove("Beta"); + newArray.splice(2, 1); + + // Peek to ensure we really had the intended effect + expect(newArray.peek()).toEqual(["Alpha", "Gamma"]); + + // Also make use of the KO delete/destroy functions to check they don't cause subscriptions + newArray([{ someProp: 123 }]); + newArray.destroyAll(); + expect(newArray.peek()[0]._destroy).toEqual(true); + newArray.removeAll(); + expect(newArray.peek()).toEqual([]); + + timesEvaluated++; + }); + + // Verify that we haven't caused a subscription + expect(timesEvaluated).toEqual(1); + expect(newArray.getSubscriptionsCount()).toEqual(0); + + // Don't just trust getSubscriptionsCount - directly verify that mutating newArray doesn't cause a re-eval + newArray.push("Another"); + expect(timesEvaluated).toEqual(1); + }); +}) diff --git a/spec/observableArrayChangeTrackingBehaviors.js b/spec/observableArrayChangeTrackingBehaviors.js new file mode 100644 index 000000000..6f6d66ceb --- /dev/null +++ b/spec/observableArrayChangeTrackingBehaviors.js @@ -0,0 +1,304 @@ +describe('Observable Array change tracking', function() { + + it('Supplies changelists to subscribers', function() { + var myArray = ko.observableArray(['Alpha', 'Beta', 'Gamma']), + changelist; + + myArray.subscribe(function(changes) { + changelist = changes; + }, null, 'arrayChange'); + + // Not going to test all possible types of mutation, because we know the diffing + // logic is all in ko.utils.compareArrays, which is tested separately. Just + // checking that a simple 'push' comes through OK. + myArray.push('Delta'); + expect(changelist).toEqual([ + { status: 'added', value: 'Delta', index: 3 } + ]); + }); + + it('Only computes diffs when there\'s at least one active arrayChange subscription', function() { + captureCompareArraysCalls(function(callLog) { + var myArray = ko.observableArray(['Alpha', 'Beta', 'Gamma']); + + // Nobody has yet subscribed for arrayChange notifications, so + // array mutations don't involve computing diffs + myArray(['Another']); + expect(callLog.length).toBe(0); + + // When there's a subscriber, it does compute diffs + var subscription = myArray.subscribe(function() {}, null, 'arrayChange'); + myArray(['Changed']); + expect(callLog.length).toBe(1); + + // If all the subscriptions are disposed, it stops computing diffs + subscription.dispose(); + myArray(['Changed again']); + expect(callLog.length).toBe(1); // Did not increment + + // ... but that doesn't stop someone else subscribing in the future, + // then diffs are computed again + myArray.subscribe(function() {}, null, 'arrayChange'); + myArray(['Changed once more']); + expect(callLog.length).toBe(2); + }); + }); + + it('Reuses cached diff results', function() { + captureCompareArraysCalls(function(callLog) { + var myArray = ko.observableArray(['Alpha', 'Beta', 'Gamma']), + changelist1, + changelist2; + + myArray.subscribe(function(changes) { changelist1 = changes; }, null, 'arrayChange'); + myArray.subscribe(function(changes) { changelist2 = changes; }, null, 'arrayChange'); + myArray(['Gamma']); + + // See that, not only did it invoke compareArrays only once, but the + // return values from getChanges are the same array instances + expect(callLog.length).toBe(1); + expect(changelist1).toEqual([ + { status: 'deleted', value: 'Alpha', index: 0 }, + { status: 'deleted', value: 'Beta', index: 1 } + ]); + expect(changelist2).toBe(changelist1); + + // Then when there's a further change, there's a further diff + myArray(['Delta']); + expect(callLog.length).toBe(2); + expect(changelist1).toEqual([ + { status: 'deleted', value: 'Gamma', index: 0 }, + { status: 'added', value: 'Delta', index: 0 } + ]); + expect(changelist2).toBe(changelist1); + }); + }); + + it('Skips the diff algorithm when the array mutation is a known operation', function() { + captureCompareArraysCalls(function(callLog) { + var myArray = ko.observableArray(['Alpha', 'Beta', 'Gamma']), + browserSupportsSpliceWithoutDeletionCount = [1, 2].splice(1).length === 1; + + // Push + testKnownOperation(myArray, 'push', { + args: ['Delta', 'Epsilon'], + result: ['Alpha', 'Beta', 'Gamma', 'Delta', 'Epsilon'], + changes: [ + { status: 'added', value: 'Delta', index: 3 }, + { status: 'added', value: 'Epsilon', index: 4 } + ] + }); + + // Pop + testKnownOperation(myArray, 'pop', { + args: [], + result: ['Alpha', 'Beta', 'Gamma', 'Delta'], + changes: [ + { status: 'deleted', value: 'Epsilon', index: 4 } + ] + }); + + // Pop empty array + testKnownOperation(ko.observableArray([]), 'pop', { + args: [], result: [], changes: [] + }); + + // Shift + testKnownOperation(myArray, 'shift', { + args: [], + result: ['Beta', 'Gamma', 'Delta'], + changes: [ + { status: 'deleted', value: 'Alpha', index: 0 } + ] + }); + + // Shift empty array + testKnownOperation(ko.observableArray([]), 'shift', { + args: [], result: [], changes: [] + }); + + // Unshift + testKnownOperation(myArray, 'unshift', { + args: ['First', 'Second'], + result: ['First', 'Second', 'Beta', 'Gamma', 'Delta'], + changes: [ + { status: 'added', value: 'First', index: 0 }, + { status: 'added', value: 'Second', index: 1 } + ] + }); + + // Splice + testKnownOperation(myArray, 'splice', { + args: [2, 3, 'Another', 'YetAnother'], + result: ['First', 'Second', 'Another', 'YetAnother'], + changes: [ + { status: 'added', value: 'Another', index: 2 }, + { status: 'deleted', value: 'Beta', index: 2 }, + { status: 'added', value: 'YetAnother', index: 3 }, + { status: 'deleted', value: 'Gamma', index: 3 }, + { status: 'deleted', value: 'Delta', index: 4 } + ] + }); + + // Splice - no 'deletion count' supplied (deletes everything after start index) + if (browserSupportsSpliceWithoutDeletionCount) { + testKnownOperation(myArray, 'splice', { + args: [2], + result: ['First', 'Second'], + changes: [ + { status: 'deleted', value: 'Another', index: 2 }, + { status: 'deleted', value: 'YetAnother', index: 3 } + ] + }); + } else { + // Browser doesn't support that underlying operation, so just set the state + // to what it needs to be to run the remaining tests + myArray(['First', 'Second']); + } + + // Splice - deletion end index out of bounds + testKnownOperation(myArray, 'splice', { + args: [1, 50, 'X', 'Y'], + result: ['First', 'X', 'Y'], + changes: [ + { status: 'added', value: 'X', index: 1 }, + { status: 'deleted', value: 'Second', index: 1 }, + { status: 'added', value: 'Y', index: 2 } + ] + }); + + // Splice - deletion start index out of bounds + testKnownOperation(myArray, 'splice', { + args: [25, 3, 'New1', 'New2'], + result: ['First', 'X', 'Y', 'New1', 'New2'], + changes: [ + { status: 'added', value: 'New1', index: 3 }, + { status: 'added', value: 'New2', index: 4 } + ] + }); + + // Splice - deletion start index negative (means 'from end of array') + testKnownOperation(myArray, 'splice', { + args: [-3, 2, 'Blah', 'Another'], + result: ['First', 'X', 'Blah', 'Another', 'New2'], + changes: [ + { status: 'added', value: 'Blah', index: 2 }, + { status: 'deleted', value: 'Y', index: 2 }, + { status: 'added', value: 'Another', index: 3 }, + { status: 'deleted', value: 'New1', index: 3 } + ] + }); + + expect(callLog.length).toBe(0); // Never needed to run the diff algorithm + }); + }); + + it('Should support tracking of any observable using extender', function() { + var myArray = ko.observable(['Alpha', 'Beta', 'Gamma']).extend({trackArrayChanges:true}), + changelist; + + myArray.subscribe(function(changes) { + changelist = changes; + }, null, 'arrayChange'); + + myArray(['Alpha', 'Beta', 'Gamma', 'Delta']); + expect(changelist).toEqual([ + { status: 'added', value: 'Delta', index: 3 } + ]); + + // Should treat null value as an empty array + myArray(null); + expect(changelist).toEqual([ + { status : 'deleted', value : 'Alpha', index : 0 }, + { status : 'deleted', value : 'Beta', index : 1 }, + { status : 'deleted', value : 'Gamma', index : 2 }, + { status : 'deleted', value : 'Delta', index : 3 } + ]); + + // Check that extending the observable again doesn't break anything an only one diff is generated + var changelist2, callCount = 0; + myArray = myArray.extend({trackArrayChanges:true}); + + myArray.subscribe(function(changes) { + callCount++; + changelist2 = changes; + }, null, 'arrayChange'); + + myArray(['Gamma']); + expect(callCount).toEqual(1); + expect(changelist2).toEqual([ + { status : 'added', value : 'Gamma', index : 0 } + ]); + expect(changelist2).toBe(changelist); + }); + + it('Should support tracking of a computed observable using extender', function() { + var myArray = ko.observable(['Alpha', 'Beta', 'Gamma']), + myComputed = ko.computed(function() { + return myArray().slice(-2); + }).extend({trackArrayChanges:true}), + changelist; + + expect(myComputed()).toEqual(['Beta', 'Gamma']); + + myComputed.subscribe(function(changes) { + changelist = changes; + }, null, 'arrayChange'); + + myArray(['Alpha', 'Beta', 'Gamma', 'Delta']); + expect(myComputed()).toEqual(['Gamma', 'Delta']); + expect(changelist).toEqual([ + { status : 'deleted', value : 'Beta', index : 0 }, + { status : 'added', value : 'Delta', index : 1 } + ]); + }); + + function testKnownOperation(array, operationName, options) { + var changeList, + subscription = array.subscribe(function(changes) { + expect(array()).toEqual(options.result); + changeList = changes; + }, null, 'arrayChange'); + array[operationName].apply(array, options.args); + subscription.dispose(); + + // The ordering of added/deleted items for replaced entries isn't defined, so + // we'll sort by index and then status just so the tests can get consistent results + changeList.sort(compareChangeListItems); + expect(changeList).toEqual(options.changes); + } + + function compareChangeListItems(a, b) { + return (a.index - b.index) || a.status.localeCompare(b.status); + } + + // There's no public API for intercepting ko.utils.compareArrays, so we'll have to + // inspect the runtime to work out the private name(s) for it, and intercept them all. + // Then undo it all afterwards. + function captureCompareArraysCalls(callback) { + var origCompareArrays = ko.utils.compareArrays, + interceptedCompareArrays = function() { + callLog.push(Array.prototype.slice.call(arguments, 0)); + return origCompareArrays.apply(this, arguments); + }, + aliases = [], + callLog = []; + + // Find and intercept all the aliases + for (var key in ko.utils) { + if (ko.utils[key] === origCompareArrays) { + aliases.push(key); + ko.utils[key] = interceptedCompareArrays; + } + } + + try { + callback(callLog); + } finally { + // Undo the interceptors + for (var i = 0; i < aliases.length; i++) { + ko.utils[aliases[i]] = origCompareArrays; + } + } + } +}); diff --git a/spec/observableBehaviors.js b/spec/observableBehaviors.js new file mode 100644 index 000000000..b6fb4cc7d --- /dev/null +++ b/spec/observableBehaviors.js @@ -0,0 +1,254 @@ + +describe('Observable', function() { + it('Should be subscribable', function () { + var instance = new ko.observable(); + expect(ko.isSubscribable(instance)).toEqual(true); + }); + + it('Should advertise that instances are observable', function () { + var instance = new ko.observable(); + expect(ko.isObservable(instance)).toEqual(true); + }); + + it('Should be able to write values to it', function () { + var instance = new ko.observable(); + instance(123); + }); + + it('Should be able to write to multiple observable properties on a model object using chaining syntax', function() { + var model = { + prop1: new ko.observable(), + prop2: new ko.observable() + }; + model.prop1('A').prop2('B'); + + expect(model.prop1()).toEqual('A'); + expect(model.prop2()).toEqual('B'); + }); + + it('Should advertise that instances can have values written to them', function () { + var instance = new ko.observable(function () { }); + expect(ko.isWriteableObservable(instance)).toEqual(true); + }); + + it('Should be able to read back most recent value', function () { + var instance = new ko.observable(); + instance(123); + instance(234); + expect(instance()).toEqual(234); + }); + + it('Should initially have undefined value', function () { + var instance = new ko.observable(); + expect(instance()).toEqual(undefined); + }); + + it('Should be able to set initial value as constructor param', function () { + var instance = new ko.observable('Hi!'); + expect(instance()).toEqual('Hi!'); + }); + + it('Should notify subscribers about each new value', function () { + var instance = new ko.observable(); + var notifiedValues = []; + instance.subscribe(function (value) { + notifiedValues.push(value); + }); + + instance('A'); + instance('B'); + + expect(notifiedValues.length).toEqual(2); + expect(notifiedValues[0]).toEqual('A'); + expect(notifiedValues[1]).toEqual('B'); + }); + + it('Should be able to tell it that its value has mutated, at which point it notifies subscribers', function () { + var instance = new ko.observable(); + var notifiedValues = []; + instance.subscribe(function (value) { + notifiedValues.push(value.childProperty); + }); + + var someUnderlyingObject = { childProperty : "A" }; + instance(someUnderlyingObject); + expect(notifiedValues.length).toEqual(1); + expect(notifiedValues[0]).toEqual("A"); + + someUnderlyingObject.childProperty = "B"; + instance.valueHasMutated(); + expect(notifiedValues.length).toEqual(2); + expect(notifiedValues[1]).toEqual("B"); + }); + + it('Should notify "beforeChange" subscribers before each new value', function () { + var instance = new ko.observable(); + var notifiedValues = []; + instance.subscribe(function (value) { + notifiedValues.push(value); + }, null, "beforeChange"); + + instance('A'); + instance('B'); + + expect(notifiedValues.length).toEqual(2); + expect(notifiedValues[0]).toEqual(undefined); + expect(notifiedValues[1]).toEqual('A'); + }); + + it('Should be able to tell it that its value will mutate, at which point it notifies "beforeChange" subscribers', function () { + var instance = new ko.observable(); + var notifiedValues = []; + instance.subscribe(function (value) { + notifiedValues.push(value ? value.childProperty : value); + }, null, "beforeChange"); + + var someUnderlyingObject = { childProperty : "A" }; + instance(someUnderlyingObject); + expect(notifiedValues.length).toEqual(1); + expect(notifiedValues[0]).toEqual(undefined); + + instance.valueWillMutate(); + expect(notifiedValues.length).toEqual(2); + expect(notifiedValues[1]).toEqual("A"); + + someUnderlyingObject.childProperty = "B"; + instance.valueHasMutated(); + expect(notifiedValues.length).toEqual(2); + expect(notifiedValues[1]).toEqual("A"); + }); + + it('Should ignore writes when the new value is primitive and strictly equals the old value', function() { + var instance = new ko.observable(); + var notifiedValues = []; + instance.subscribe(notifiedValues.push, notifiedValues); + + for (var i = 0; i < 3; i++) { + instance("A"); + expect(instance()).toEqual("A"); + expect(notifiedValues).toEqual(["A"]); + } + + instance("B"); + expect(instance()).toEqual("B"); + expect(notifiedValues).toEqual(["A", "B"]); + }); + + it('Should ignore writes when both the old and new values are strictly null', function() { + var instance = new ko.observable(null); + var notifiedValues = []; + instance.subscribe(notifiedValues.push, notifiedValues); + instance(null); + expect(notifiedValues).toEqual([]); + }); + + it('Should ignore writes when both the old and new values are strictly undefined', function() { + var instance = new ko.observable(undefined); + var notifiedValues = []; + instance.subscribe(notifiedValues.push, notifiedValues); + instance(undefined); + expect(notifiedValues).toEqual([]); + }); + + it('Should notify subscribers of a change when an object value is written, even if it is identical to the old value', function() { + // Because we can't tell whether something further down the object graph has changed, we regard + // all objects as new values. To override this, set an "equalityComparer" callback + var constantObject = {}; + var instance = new ko.observable(constantObject); + var notifiedValues = []; + instance.subscribe(notifiedValues.push, notifiedValues); + instance(constantObject); + expect(notifiedValues).toEqual([constantObject]); + }); + + it('Should notify subscribers of a change even when an identical primitive is written if you\'ve set the equality comparer to null', function() { + var instance = new ko.observable("A"); + var notifiedValues = []; + instance.subscribe(notifiedValues.push, notifiedValues); + + // No notification by default + instance("A"); + expect(notifiedValues).toEqual([]); + + // But there is a notification if we null out the equality comparer + instance.equalityComparer = null; + instance("A"); + expect(notifiedValues).toEqual(["A"]); + }); + + it('Should ignore writes when the equalityComparer callback states that the values are equal', function() { + var instance = new ko.observable(); + instance.equalityComparer = function(a, b) { + return !(a && b) ? a === b : a.id == b.id + }; + + var notifiedValues = []; + instance.subscribe(notifiedValues.push, notifiedValues); + + instance({ id: 1 }); + expect(notifiedValues.length).toEqual(1); + + // Same key - no change + instance({ id: 1, ignoredProp: 'abc' }); + expect(notifiedValues.length).toEqual(1); + + // Different key - change + instance({ id: 2, ignoredProp: 'abc' }); + expect(notifiedValues.length).toEqual(2); + + // Null vs not-null - change + instance(null); + expect(notifiedValues.length).toEqual(3); + + // Null vs null - no change + instance(null); + expect(notifiedValues.length).toEqual(3); + + // Null vs undefined - change + instance(undefined); + expect(notifiedValues.length).toEqual(4); + + // undefined vs object - change + instance({ id: 1 }); + expect(notifiedValues.length).toEqual(5); + }); + + it('Should expose a "notify" extender that can configure the observable to notify on all writes, even if the value is unchanged', function() { + var instance = new ko.observable(); + var notifiedValues = []; + instance.subscribe(notifiedValues.push, notifiedValues); + + instance(123); + expect(notifiedValues.length).toEqual(1); + + // Typically, unchanged values don't trigger a notification + instance(123); + expect(notifiedValues.length).toEqual(1); + + // ... but you can enable notifications regardless of change + instance.extend({ notify: 'always' }); + instance(123); + expect(notifiedValues.length).toEqual(2); + + // ... or later disable that + instance.extend({ notify: null }); + instance(123); + expect(notifiedValues.length).toEqual(2); + }); + + it('Should be possible to replace notifySubscribers with a custom handler', function() { + var instance = new ko.observable(123); + var interceptedNotifications = []; + instance.subscribe(function() { throw new Error("Should not notify subscribers by default once notifySubscribers is overridden") }); + instance.notifySubscribers = function(newValue, eventName) { + interceptedNotifications.push({ eventName: eventName || "None", value: newValue }); + }; + instance(456); + + expect(interceptedNotifications.length).toEqual(2); + expect(interceptedNotifications[0].eventName).toEqual("beforeChange"); + expect(interceptedNotifications[1].eventName).toEqual("None"); + expect(interceptedNotifications[0].value).toEqual(123); + expect(interceptedNotifications[1].value).toEqual(456); + }); +}); diff --git a/spec/runner.html b/spec/runner.html new file mode 100644 index 000000000..cee40fbf6 --- /dev/null +++ b/spec/runner.html @@ -0,0 +1,99 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/spec/subscribableBehaviors.js b/spec/subscribableBehaviors.js new file mode 100644 index 000000000..f5dd8c850 --- /dev/null +++ b/spec/subscribableBehaviors.js @@ -0,0 +1,109 @@ + +describe('Subscribable', function() { + it('Should declare that it is subscribable', function () { + var instance = new ko.subscribable(); + expect(ko.isSubscribable(instance)).toEqual(true); + }); + + it('isSubscribable should return false for undefined', function () { + expect(ko.isSubscribable(undefined)).toEqual(false); + }); + + it('isSubscribable should return false for null', function () { + expect(ko.isSubscribable(null)).toEqual(false); + }); + + it('Should be able to notify subscribers', function () { + var instance = new ko.subscribable(); + var notifiedValue; + instance.subscribe(function (value) { notifiedValue = value; }); + instance.notifySubscribers(123); + expect(notifiedValue).toEqual(123); + }); + + it('Should be able to unsubscribe', function () { + var instance = new ko.subscribable(); + var notifiedValue; + var subscription = instance.subscribe(function (value) { notifiedValue = value; }); + subscription.dispose(); + instance.notifySubscribers(123); + expect(notifiedValue).toEqual(undefined); + }); + + it('Should be able to specify a \'this\' pointer for the callback', function () { + var model = { + someProperty: 123, + myCallback: function (arg) { expect(arg).toEqual('notifiedValue'); expect(this.someProperty).toEqual(123); } + }; + var instance = new ko.subscribable(); + instance.subscribe(model.myCallback, model); + instance.notifySubscribers('notifiedValue'); + }); + + it('Should not notify subscribers after unsubscription, even if the unsubscription occurs midway through a notification cycle', function() { + // This spec represents the unusual case where during notification, subscription1's callback causes subscription2 to be disposed. + // Since subscription2 was still active at the start of the cycle, it is scheduled to be notified. This spec verifies that + // even though it is scheduled to be notified, it does not get notified, because the unsubscription just happened. + var instance = new ko.subscribable(); + var subscription1 = instance.subscribe(function() { + subscription2.dispose(); + }); + var subscription2wasNotified = false; + var subscription2 = instance.subscribe(function() { + subscription2wasNotified = true; + }); + + instance.notifySubscribers('ignored'); + expect(subscription2wasNotified).toEqual(false); + }); + + it('Should be able to notify subscribers for a specific \'event\'', function () { + var instance = new ko.subscribable(); + var notifiedValue = undefined; + instance.subscribe(function (value) { notifiedValue = value; }, null, "myEvent"); + + instance.notifySubscribers(123, "unrelatedEvent"); + expect(notifiedValue).toEqual(undefined); + + instance.notifySubscribers(456, "myEvent"); + expect(notifiedValue).toEqual(456); + }); + + it('Should be able to unsubscribe for a specific \'event\'', function () { + var instance = new ko.subscribable(); + var notifiedValue; + var subscription = instance.subscribe(function (value) { notifiedValue = value; }, null, "myEvent"); + subscription.dispose(); + instance.notifySubscribers(123, "myEvent"); + expect(notifiedValue).toEqual(undefined); + }); + + it('Should be able to subscribe for a specific \'event\' without being notified for the default event', function () { + var instance = new ko.subscribable(); + var notifiedValue; + var subscription = instance.subscribe(function (value) { notifiedValue = value; }, null, "myEvent"); + instance.notifySubscribers(123); + expect(notifiedValue).toEqual(undefined); + }); + + it('Should be able to retrieve the number of active subscribers', function() { + var instance = new ko.subscribable(); + instance.subscribe(function() { }); + instance.subscribe(function() { }, null, "someSpecificEvent"); + expect(instance.getSubscriptionsCount()).toEqual(2); + }); + + it('Should be possible to replace notifySubscribers with a custom handler', function() { + var instance = new ko.subscribable(); + var interceptedNotifications = []; + instance.subscribe(function() { throw new Error("Should not notify subscribers by default once notifySubscribers is overridden") }); + instance.notifySubscribers = function(newValue, eventName) { + interceptedNotifications.push({ eventName: eventName, value: newValue }); + }; + instance.notifySubscribers(123, "myEvent"); + + expect(interceptedNotifications.length).toEqual(1); + expect(interceptedNotifications[0].eventName).toEqual("myEvent"); + expect(interceptedNotifications[0].value).toEqual(123); + }); +}); diff --git a/spec/templatingBehaviors.js b/spec/templatingBehaviors.js new file mode 100644 index 000000000..90b4e76e3 --- /dev/null +++ b/spec/templatingBehaviors.js @@ -0,0 +1,989 @@ + +var dummyTemplateEngine = function (templates) { + var inMemoryTemplates = templates || {}; + var inMemoryTemplateData = {}; + + function dummyTemplateSource(id) { + this.id = id; + } + dummyTemplateSource.prototype = { + text: function(val) { + if (arguments.length >= 1) + inMemoryTemplates[this.id] = val; + return inMemoryTemplates[this.id]; + }, + data: function(key, val) { + if (arguments.length >= 2) { + inMemoryTemplateData[this.id] = inMemoryTemplateData[this.id] || {}; + inMemoryTemplateData[this.id][key] = val; + } + return (inMemoryTemplateData[this.id] || {})[key]; + } + } + + this.makeTemplateSource = function(template) { + if (typeof template == "string") + return new dummyTemplateSource(template); // Named template comes from the in-memory collection + else if ((template.nodeType == 1) || (template.nodeType == 8)) + return new ko.templateSources.anonymousTemplate(template); // Anonymous template + }; + + this.renderTemplateSource = function (templateSource, bindingContext, options) { + var data = bindingContext['$data']; + options = options || {}; + var templateText = templateSource.text(); + if (typeof templateText == "function") + templateText = templateText(data, options); + + templateText = options.showParams ? templateText + ", data=" + data + ", options=" + options : templateText; + var templateOptions = options.templateOptions; // Have templateOptions in scope to support [js:templateOptions.foo] syntax + + var result; + with (bindingContext) { + with (data || {}) { + with (options.templateRenderingVariablesInScope || {}) { + // Dummy [renderTemplate:...] syntax + result = templateText.replace(/\[renderTemplate\:(.*?)\]/g, function (match, templateName) { + return ko.renderTemplate(templateName, data, options); + }); + + + var evalHandler = function (match, script) { + try { + var evalResult = eval(script); + return (evalResult === null) || (evalResult === undefined) ? "" : evalResult.toString(); + } catch (ex) { + throw new Error("Error evaluating script: [js: " + script + "]\n\nException: " + ex.toString()); + } + } + + // Dummy [[js:...]] syntax (in case you need to use square brackets inside the expression) + result = result.replace(/\[\[js\:([\s\S]*?)\]\]/g, evalHandler); + + // Dummy [js:...] syntax + result = result.replace(/\[js\:([\s\S]*?)\]/g, evalHandler); + } + } + } + + // Use same HTML parsing code as real template engine so as to trigger same combination of IE weirdnesses + // Also ensure resulting nodelist is an array to mimic what the default templating engine does, so we see the effects of not being able to remove dead memo comment nodes. + return ko.utils.arrayPushAll([], ko.utils.parseHtmlFragment(result)); + }; + + this.rewriteTemplate = function (template, rewriterCallback) { + // Only rewrite if the template isn't a function (can't rewrite those) + var templateSource = this.makeTemplateSource(template); + if (typeof templateSource.text() != "function") + return ko.templateEngine.prototype.rewriteTemplate.call(this, template, rewriterCallback); + }; + this.createJavaScriptEvaluatorBlock = function (script) { return "[js:" + script + "]"; }; +}; +dummyTemplateEngine.prototype = new ko.templateEngine(); + +describe('Templating', function() { + beforeEach(function() { + ko.setTemplateEngine(new ko.nativeTemplateEngine()); + }); + beforeEach(jasmine.prepareTestNode); + + it('Template engines can return an array of DOM nodes', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ x: [document.createElement("div"), document.createElement("span")] })); + ko.renderTemplate("x", null); + }); + + it('Should not be able to render a template until a template engine is provided', function () { + expect(function () { + ko.setTemplateEngine(undefined); + ko.renderTemplate("someTemplate", {}); + }).toThrow(); + }); + + it('Should be able to render a template into a given DOM element', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "ABC" })); + ko.renderTemplate("someTemplate", null, null, testNode); + expect(testNode.childNodes.length).toEqual(1); + expect(testNode.innerHTML).toEqual("ABC"); + }); + + it('Should be able to render an empty template', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ emptyTemplate: "" })); + ko.renderTemplate("emptyTemplate", null, null, testNode); + expect(testNode.childNodes.length).toEqual(0); + }); + + it('Should be able to access newly rendered/inserted elements in \'afterRender\' callback', function () { + var passedElement, passedDataItem; + var myCallback = function(elementsArray, dataItem) { + expect(elementsArray.length).toEqual(1); + passedElement = elementsArray[0]; + passedDataItem = dataItem; + } + var myModel = {}; + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "ABC" })); + ko.renderTemplate("someTemplate", myModel, { afterRender: myCallback }, testNode); + expect(passedElement.nodeValue).toEqual("ABC"); + expect(passedDataItem).toEqual(myModel); + }); + + it('Should automatically rerender into DOM element when dependencies change', function () { + var dependency = new ko.observable("A"); + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: function () { + return "Value = " + dependency(); + } + })); + + ko.renderTemplate("someTemplate", null, null, testNode); + expect(testNode.childNodes.length).toEqual(1); + expect(testNode.innerHTML).toEqual("Value = A"); + + dependency("B"); + expect(testNode.childNodes.length).toEqual(1); + expect(testNode.innerHTML).toEqual("Value = B"); + }); + + it('Should not rerender DOM element if observable accessed in \'afterRender\' callback is changed', function () { + var observable = new ko.observable("A"), count = 0; + var myCallback = function(elementsArray, dataItem) { + observable(); // access observable in callback + }; + var myTemplate = function() { + return "Value = " + (++count); + }; + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: myTemplate })); + ko.renderTemplate("someTemplate", {}, { afterRender: myCallback }, testNode); + expect(testNode.childNodes.length).toEqual(1); + expect(testNode.innerHTML).toEqual("Value = 1"); + + observable("B"); + expect(testNode.childNodes.length).toEqual(1); + expect(testNode.innerHTML).toEqual("Value = 1"); + }); + + it('If the supplied data item is observable, evaluates it and has subscription on it', function () { + var observable = new ko.observable("A"); + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: function (data) { + return "Value = " + data; + } + })); + ko.renderTemplate("someTemplate", observable, null, testNode); + expect(testNode.innerHTML).toEqual("Value = A"); + + observable("B"); + expect(testNode.innerHTML).toEqual("Value = B"); + }); + + it('Should stop updating DOM nodes when the dependency next changes if the DOM node has been removed from the document', function () { + var dependency = new ko.observable("A"); + var template = { someTemplate: function () { return "Value = " + dependency() } }; + ko.setTemplateEngine(new dummyTemplateEngine(template)); + + ko.renderTemplate("someTemplate", null, null, testNode); + expect(testNode.childNodes.length).toEqual(1); + expect(testNode.innerHTML).toEqual("Value = A"); + + testNode.parentNode.removeChild(testNode); + dependency("B"); + expect(testNode.childNodes.length).toEqual(1); + expect(testNode.innerHTML).toEqual("Value = A"); + }); + + it('Should be able to render a template using data-bind syntax', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "template output" })); + testNode.innerHTML = "
"; + ko.applyBindings(null, testNode); + expect(testNode.childNodes[0].innerHTML).toEqual("template output"); + }); + + it('Should remove existing content when rendering a template using data-bind syntax', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "template output" })); + testNode.innerHTML = "
existing content
"; + ko.applyBindings(null, testNode); + expect(testNode.childNodes[0].innerHTML).toEqual("template output"); + }); + + it('Should be able to tell data-bind syntax which object to pass as data for the template (otherwise, uses viewModel)', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "result = [js: childProp]" })); + testNode.innerHTML = "
"; + ko.applyBindings({ someProp: { childProp: 123} }, testNode); + expect(testNode.childNodes[0].innerHTML).toEqual("result = 123"); + }); + + it('Should re-render a named template when its data item notifies about mutation', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "result = [js: childProp]" })); + testNode.innerHTML = "
"; + + var myData = ko.observable({ childProp: 123 }); + ko.applyBindings({ someProp: myData }, testNode); + expect(testNode.childNodes[0].innerHTML).toEqual("result = 123"); + + // Now mutate and notify + myData().childProp = 456; + myData.valueHasMutated(); + expect(testNode.childNodes[0].innerHTML).toEqual("result = 456"); + }); + + it('Should stop tracking inner observables immediately when the container node is removed from the document', function() { + var innerObservable = ko.observable("some value"); + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "result = [js: childProp()]" })); + testNode.innerHTML = "
"; + ko.applyBindings({ someProp: { childProp: innerObservable} }, testNode); + + expect(innerObservable.getSubscriptionsCount()).toEqual(1); + ko.removeNode(testNode.childNodes[0]); + expect(innerObservable.getSubscriptionsCount()).toEqual(0); + }); + + it('Should be able to pick template via an observable model property', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ + firstTemplate: "First template output", + secondTemplate: "Second template output" + })); + + var chosenTemplate = ko.observable("firstTemplate"); + testNode.innerHTML = "
"; + ko.applyBindings({ chosenTemplate: chosenTemplate }, testNode); + expect(testNode.childNodes[0].innerHTML).toEqual("First template output"); + + chosenTemplate("secondTemplate"); + expect(testNode.childNodes[0].innerHTML).toEqual("Second template output"); + }); + + it('Should be able to pick template via an observable model property when specified as "name"', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ + firstTemplate: "First template output", + secondTemplate: "Second template output" + })); + + var chosenTemplate = ko.observable("firstTemplate"); + testNode.innerHTML = "
"; + ko.applyBindings({ chosenTemplate: chosenTemplate }, testNode); + expect(testNode.childNodes[0].innerHTML).toEqual("First template output"); + + chosenTemplate("secondTemplate"); + expect(testNode.childNodes[0].innerHTML).toEqual("Second template output"); + }); + + it('Should be able to pick template as a function of the data item using data-bind syntax, with the binding context available as a second parameter', function () { + var templatePicker = function(dataItem, bindingContext) { + // Having the entire binding context available means you can read sibling or parent level properties + expect(bindingContext.$parent.anotherProperty).toEqual(456); + return dataItem.myTemplate; + }; + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "result = [js: childProp]" })); + testNode.innerHTML = "
"; + ko.applyBindings({ someProp: { childProp: 123, myTemplate: "someTemplate" }, templateSelectorFunction: templatePicker, anotherProperty: 456 }, testNode); + expect(testNode.childNodes[0].innerHTML).toEqual("result = 123"); + }); + + it('Should be able to chain templates, rendering one from inside another', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ + outerTemplate: "outer template output, [renderTemplate:innerTemplate]", // [renderTemplate:...] is special syntax supported by dummy template engine + innerTemplate: "inner template output " + })); + testNode.innerHTML = "
"; + ko.applyBindings(null, testNode); + expect(testNode.childNodes[0]).toContainHtml("outer template output, inner template output 123"); + }); + + it('Should rerender chained templates when their dependencies change, without rerendering parent templates', function () { + var observable = new ko.observable("ABC"); + var timesRenderedOuter = 0, timesRenderedInner = 0; + ko.setTemplateEngine(new dummyTemplateEngine({ + outerTemplate: function () { timesRenderedOuter++; return "outer template output, [renderTemplate:innerTemplate]" }, // [renderTemplate:...] is special syntax supported by dummy template engine + innerTemplate: function () { timesRenderedInner++; return observable() } + })); + testNode.innerHTML = "
"; + ko.applyBindings(null, testNode); + expect(testNode.childNodes[0]).toContainHtml("outer template output, abc"); + expect(timesRenderedOuter).toEqual(1); + expect(timesRenderedInner).toEqual(1); + + observable("DEF"); + expect(testNode.childNodes[0]).toContainHtml("outer template output, def"); + expect(timesRenderedOuter).toEqual(1); + expect(timesRenderedInner).toEqual(2); + }); + + it('Should stop tracking inner observables referenced by a chained template as soon as the chained template output node is removed from the document', function() { + var innerObservable = ko.observable("some value"); + ko.setTemplateEngine(new dummyTemplateEngine({ + outerTemplate: "outer template output, [renderTemplate:innerTemplate]", + innerTemplate: "result = [js: childProp()]" + })); + testNode.innerHTML = "
"; + ko.applyBindings({ someProp: { childProp: innerObservable} }, testNode); + + expect(innerObservable.getSubscriptionsCount()).toEqual(1); + ko.removeNode(document.getElementById('innerTemplateOutput')); + expect(innerObservable.getSubscriptionsCount()).toEqual(0); + }); + + it('Should handle data-bind attributes from inside templates, regardless of element and attribute casing', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "" })); + ko.renderTemplate("someTemplate", null, null, testNode); + expect(testNode.childNodes[0].value).toEqual("Hi"); + }); + + it('Should handle data-bind attributes that include newlines from inside templates', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "" })); + ko.renderTemplate("someTemplate", null, null, testNode); + expect(testNode.childNodes[0].value).toEqual("Hi"); + }); + + it('Data binding syntax should be able to reference variables put into scope by the template engine', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "" })); + ko.renderTemplate("someTemplate", null, { templateRenderingVariablesInScope: { message: "hello"} }, testNode); + expect(testNode.childNodes[0].value).toEqual("hello"); + }); + + it('Should handle data-bind attributes with spaces around equals sign from inside templates and reference variables', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "" })); + ko.renderTemplate("someTemplate", null, { templateRenderingVariablesInScope: { message: "hello"} }, testNode); + expect(testNode.childNodes[0].value).toEqual("hello"); + }); + + it('Data binding syntax should be able to use $element in binding value', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "
" })); + ko.renderTemplate("someTemplate", null, null, testNode); + expect(testNode.childNodes[0]).toContainText("DIV"); + }); + + it('Data binding syntax should be able to use $context in binding value to refer to the context object', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "
" })); + ko.renderTemplate("someTemplate", {}, null, testNode); + expect(testNode.childNodes[0]).toContainText("true"); + }); + + it('Data binding syntax should defer evaluation of variables until the end of template rendering (so bindings can take independent subscriptions to them)', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ + someTemplate: "[js: message = 'goodbye'; undefined; ]" + })); + ko.renderTemplate("someTemplate", null, { templateRenderingVariablesInScope: { message: "hello"} }, testNode); + expect(testNode.childNodes[0].value).toEqual("goodbye"); + }); + + it('Data binding syntax should use the template\'s \'data\' object as the viewModel value (so \'this\' is set correctly when calling click handlers etc.)', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ + someTemplate: "" + })); + var viewModel = { + didCallMyFunction : false, + someFunctionOnModel : function() { this.didCallMyFunction = true } + }; + ko.renderTemplate("someTemplate", viewModel, null, testNode); + var buttonNode = testNode.childNodes[0]; + expect(buttonNode.tagName).toEqual("BUTTON"); // Be sure we're clicking the right thing + buttonNode.click(); + expect(viewModel.didCallMyFunction).toEqual(true); + }); + + it('Data binding syntax should permit nested templates, and only bind inner templates once when using getBindingAccessors', function() { + this.restoreAfter(ko.bindingProvider, 'instance'); + + // Will verify that bindings are applied only once for both inline (rewritten) bindings, + // and external (non-rewritten) ones + var originalBindingProvider = ko.bindingProvider.instance; + ko.bindingProvider.instance = { + nodeHasBindings: function(node, bindingContext) { + return (node.tagName == 'EM') || originalBindingProvider.nodeHasBindings(node, bindingContext); + }, + getBindingAccessors: function(node, bindingContext) { + if (node.tagName == 'EM') { + return { + text: function() { + return ++model.numExternalBindings; + } + }; + } + return originalBindingProvider.getBindingAccessors(node, bindingContext); + } + }; + + ko.setTemplateEngine(new dummyTemplateEngine({ + outerTemplate: "Outer
", + innerTemplate: "Inner via inline binding: " + + "Inner via external binding: " + })); + var model = { numRewrittenBindings: 0, numExternalBindings: 0 }; + testNode.innerHTML = "
"; + ko.applyBindings(model, testNode); + expect(model.numRewrittenBindings).toEqual(1); + expect(model.numExternalBindings).toEqual(1); + expect(testNode.childNodes[0]).toContainHtml("outer
inner via inline binding: 1inner via external binding: 1
"); + }); + + it('Data binding syntax should permit nested templates, and only bind inner templates once when using getBindings', function() { + this.restoreAfter(ko.bindingProvider, 'instance'); + + // Will verify that bindings are applied only once for both inline (rewritten) bindings, + // and external (non-rewritten) ones. Because getBindings actually gets called twice, we need + // to expect two calls (but still it's a single binding). + var originalBindingProvider = ko.bindingProvider.instance; + ko.bindingProvider.instance = { + nodeHasBindings: function(node, bindingContext) { + return (node.tagName == 'EM') || originalBindingProvider.nodeHasBindings(node, bindingContext); + }, + getBindings: function(node, bindingContext) { + if (node.tagName == 'EM') + return { text: ++model.numExternalBindings }; + return originalBindingProvider.getBindings(node, bindingContext); + } + }; + + ko.setTemplateEngine(new dummyTemplateEngine({ + outerTemplate: "Outer
", + innerTemplate: "Inner via inline binding: " + + "Inner via external binding: " + })); + var model = { numRewrittenBindings: 0, numExternalBindings: 0 }; + testNode.innerHTML = "
"; + ko.applyBindings(model, testNode); + expect(model.numRewrittenBindings).toEqual(1); + expect(model.numExternalBindings).toEqual(2); + expect(testNode.childNodes[0]).toContainHtml("outer
inner via inline binding: 1inner via external binding: 2
"); + }); + + describe('Data binding \'foreach\' option', function() { + it('Should remove existing content', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "template content" })); + testNode.innerHTML = "
existing content
"; + + ko.applyBindings({ myCollection: [ {} ] }, testNode); + expect(testNode.childNodes[0]).toContainHtml("template content"); + }); + + it('Should render for each item in an array but doesn\'t rerender everything if you push or splice', function () { + var myArray = new ko.observableArray([{ personName: "Bob" }, { personName: "Frank"}]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "
The item is [js: personName]
" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("
the item is bob
the item is frank
"); + var originalBobNode = testNode.childNodes[0].childNodes[0]; + var originalFrankNode = testNode.childNodes[0].childNodes[1]; + + myArray.push({ personName: "Steve" }); + expect(testNode.childNodes[0]).toContainHtml("
the item is bob
the item is frank
the item is steve
"); + expect(testNode.childNodes[0].childNodes[0]).toEqual(originalBobNode); + expect(testNode.childNodes[0].childNodes[1]).toEqual(originalFrankNode); + }); + + it('Should apply bindings within the context of each item in the array', function () { + var myArray = new ko.observableArray([{ personName: "Bob" }, { personName: "Frank"}]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "The item is " })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("the item is bobthe item is frank"); + }); + + it('Should only bind each group of output nodes once', function() { + var initCalls = 0; + ko.bindingHandlers.countInits = { init: function() { initCalls++ } }; + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: [1,2,3] }, testNode); + expect(initCalls).toEqual(3); // 3 because there were 3 items in myCollection + }); + + it('Should handle templates in which the very first node has a binding', function() { + // Represents https://github.com/SteveSanderson/knockout/pull/440 + // Previously, the rewriting (which introduces a comment node before the bound node) was interfering + // with the array-to-DOM-node mapping state tracking + ko.setTemplateEngine(new dummyTemplateEngine({ mytemplate: "
" })); + testNode.innerHTML = "
"; + + // Bind against initial array containing one entry. UI just shows "original" + var myArray = ko.observableArray(["original"]); + ko.applyBindings({ items: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("
original
"); + + // Now replace the entire array contents with one different entry. + // UI just shows "new" (previously with bug, showed "original" AND "new") + myArray(["new"]); + expect(testNode.childNodes[0]).toContainHtml("
new
"); + }); + + it('Should handle chained templates in which the very first node has a binding', function() { + // See https://github.com/SteveSanderson/knockout/pull/440 and https://github.com/SteveSanderson/knockout/pull/144 + ko.setTemplateEngine(new dummyTemplateEngine({ + outerTemplate: "
[renderTemplate:innerTemplate]x", // [renderTemplate:...] is special syntax supported by dummy template engine + innerTemplate: "inner " + })); + testNode.innerHTML = "
"; + + // Bind against initial array containing one entry. + var myArray = ko.observableArray(["original"]); + ko.applyBindings({ items: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("
original
inner 123x"); + + // Now replace the entire array contents with one different entry. + myArray(["new"]); + expect(testNode.childNodes[0]).toContainHtml("
new
inner 123x"); + }); + + it('Should handle templates in which the very first node has a binding but it does not reference any observables', function() { + // Represents https://github.com/SteveSanderson/knockout/issues/739 + // Previously, the rewriting (which introduces a comment node before the bound node) was interfering + // with the array-to-DOM-node mapping state tracking + ko.setTemplateEngine(new dummyTemplateEngine({ mytemplate: "
[js:name()]
" })); + testNode.innerHTML = "
"; + + // Bind against array, referencing an observable property + var myItem = { name: ko.observable("a") }; + ko.applyBindings({ items: [myItem] }, testNode); + expect(testNode.childNodes[0]).toContainHtml("
a
"); + + // Modify the observable property and check that UI is updated + // Previously with the bug, it wasn't updated because the removal of the memo comment caused the array-to-DOM-node computed to be disposed + myItem.name("b"); + expect(testNode.childNodes[0]).toContainHtml("
b
"); + }); + + it('Should apply bindings with an $index in the context', function () { + var myArray = new ko.observableArray([{ personName: "Bob" }, { personName: "Frank"}]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "The item # is " })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("the item # is 0the item # is 1"); + }); + + it('Should update bindings that reference an $index if the list changes', function () { + var myArray = new ko.observableArray([{ personName: "Bob" }, { personName: "Frank"}]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "The item is " })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("the item bobis 0the item frankis 1"); + + var frank = myArray.pop(); // remove frank + expect(testNode.childNodes[0]).toContainHtml("the item bobis 0"); + + myArray.unshift(frank); // put frank in the front + expect(testNode.childNodes[0]).toContainHtml("the item frankis 0the item bobis 1"); + }); + + it('Should accept array with "undefined" and "null" items', function () { + var myArray = new ko.observableArray([undefined, null]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "The item is " })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("the item is undefinedthe item is null"); + }); + + it('Should update DOM nodes when a dependency of their mapping function changes', function() { + var myObservable = new ko.observable("Steve"); + var myArray = new ko.observableArray([{ personName: "Bob" }, { personName: myObservable }, { personName: "Another" }]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "
The item is [js: ko.utils.unwrapObservable(personName)]
" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("
the item is bob
the item is steve
the item is another
"); + var originalBobNode = testNode.childNodes[0].childNodes[0]; + + myObservable("Steve2"); + expect(testNode.childNodes[0]).toContainHtml("
the item is bob
the item is steve2
the item is another
"); + expect(testNode.childNodes[0].childNodes[0]).toEqual(originalBobNode); + + // Ensure we can still remove the corresponding nodes (even though they've changed), and that doing so causes the subscription to be disposed + expect(myObservable.getSubscriptionsCount()).toEqual(1); + myArray.splice(1, 1); + expect(testNode.childNodes[0]).toContainHtml("
the item is bob
the item is another
"); + myObservable("Something else"); // Re-evaluating the observable causes the orphaned subscriptions to be disposed + expect(myObservable.getSubscriptionsCount()).toEqual(0); + }); + + it('Should treat a null parameter as meaning \'no items\'', function() { + var myArray = new ko.observableArray(["A", "B"]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "hello" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0].childNodes.length).toEqual(2); + + // Now set the observable to null and check it's treated like an empty array + // (because how else should null be interpreted?) + myArray(null); + expect(testNode.childNodes[0].childNodes.length).toEqual(0); + }); + + it('Should accept an \"as\" option to define an alias for the iteration variable', function() { + // Note: There are more detailed specs (e.g., covering nesting) associated with the "foreach" binding which + // uses this templating functionality internally. + var myArray = new ko.observableArray(["A", "B"]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "[js:myAliasedItem]" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainText("AB"); + }); + + it('Should stop tracking inner observables when the container node is removed', function() { + var innerObservable = ko.observable("some value"); + var myArray = new ko.observableArray([{obsVal:innerObservable}, {obsVal:innerObservable}]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "The item is [js: ko.utils.unwrapObservable(obsVal)]" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(innerObservable.getSubscriptionsCount()).toEqual(2); + + ko.removeNode(testNode.childNodes[0]); + expect(innerObservable.getSubscriptionsCount()).toEqual(0); + }); + + it('Should stop tracking inner observables related to each array item when that array item is removed', function() { + var innerObservable = ko.observable("some value"); + var myArray = new ko.observableArray([{obsVal:innerObservable}, {obsVal:innerObservable}]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "The item is [js: ko.utils.unwrapObservable(obsVal)]" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(innerObservable.getSubscriptionsCount()).toEqual(2); + + myArray.splice(1, 1); + expect(innerObservable.getSubscriptionsCount()).toEqual(1); + myArray([]); + expect(innerObservable.getSubscriptionsCount()).toEqual(0); + }); + + it('Should omit any items whose \'_destroy\' flag is set (unwrapping the flag if it is observable)', function() { + var myArray = new ko.observableArray([{ someProp: 1 }, { someProp: 2, _destroy: 'evals to true' }, { someProp : 3 }, { someProp: 4, _destroy: ko.observable(false) }]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "
someProp=[js: someProp]
" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("
someprop=1
someprop=3
someprop=4
"); + }); + + it('Should include any items whose \'_destroy\' flag is set if you use includeDestroyed', function() { + var myArray = new ko.observableArray([{ someProp: 1 }, { someProp: 2, _destroy: 'evals to true' }, { someProp : 3 }]); + ko.setTemplateEngine(new dummyTemplateEngine({ itemTemplate: "
someProp=[js: someProp]
" })); + testNode.innerHTML = "
"; + + ko.applyBindings({ myCollection: myArray }, testNode); + expect(testNode.childNodes[0]).toContainHtml("
someprop=1
someprop=2
someprop=3
"); + }); + + it('Should be able to render a different template for each array entry by passing a function as template name, with the array entry\'s binding context available as a second parameter', function() { + var myArray = new ko.observableArray([ + { preferredTemplate: 1, someProperty: 'firstItemValue' }, + { preferredTemplate: 2, someProperty: 'secondItemValue' } + ]); + ko.setTemplateEngine(new dummyTemplateEngine({ + firstTemplate: "
Template1Output, [js:someProperty]
", + secondTemplate: "
Template2Output, [js:someProperty]
" + })); + testNode.innerHTML = "
"; + + var getTemplate = function(dataItem, bindingContext) { + // Having the item's binding context available means you can read sibling or parent level properties + expect(bindingContext.$parent.anotherProperty).toEqual(123); + + return dataItem.preferredTemplate == 1 ? 'firstTemplate' : 'secondTemplate'; + }; + ko.applyBindings({ myCollection: myArray, getTemplateModelProperty: getTemplate, anotherProperty: 123 }, testNode); + expect(testNode.childNodes[0]).toContainHtml("
template1output, firstitemvalue
template2output, seconditemvalue
"); + }); + + it('Should update all child contexts and bindings when used with a top-level observable view model', function() { + var myVm = ko.observable({items: ['A', 'B', 'C'], itemValues: { 'A': [1, 2, 3], 'B': [4, 5, 6], 'C': [7, 8, 9] }}); + var engine = new dummyTemplateEngine({ + itemTemplate: "The item has ", + valueTemplate: " . ," + }); + engine.createJavaScriptEvaluatorBlock = function (script) { return "[[js:" + script + "]]"; }; // because we're using a binding with brackets + ko.setTemplateEngine(engine); + + testNode.innerHTML = "
"; + + ko.applyBindings(myVm, testNode); + expect(testNode.childNodes[0]).toContainText("The 0 item A has 0.1,1.2,2.3, The 1 item B has 0.4,1.5,2.6, The 2 item C has 0.7,1.8,2.9, "); + + myVm({items: ['C', 'B', 'A'], itemValues: { 'A': [1, 2, 30], 'B': [4, 5, 60], 'C': [7, 8, 90] }}); + expect(testNode.childNodes[0]).toContainText("The 0 item C has 0.7,1.8,2.90, The 1 item B has 0.4,1.5,2.60, The 2 item A has 0.1,1.2,2.30, "); + }); + + }); + + it('Data binding syntax should support \"if\" condition', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ myTemplate: "Value: [js: myProp().childProp]" })); + testNode.innerHTML = "
"; + + var viewModel = { myProp: ko.observable({ childProp: 'abc' }) }; + ko.applyBindings(viewModel, testNode); + + // Initially there is a value + expect(testNode.childNodes[0]).toContainText("Value: abc"); + + // Causing the condition to become false causes the output to be removed + viewModel.myProp(null); + expect(testNode.childNodes[0]).toContainText(""); + + // Causing the condition to become true causes the output to reappear + viewModel.myProp({ childProp: 'def' }); + expect(testNode.childNodes[0]).toContainText("Value: def"); + }); + + it('Data binding syntax should support \"ifnot\" condition', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ myTemplate: "Hello" })); + testNode.innerHTML = "
"; + + var viewModel = { shouldHide: ko.observable(true) }; + ko.applyBindings(viewModel, testNode); + + // Initially there is no output (shouldHide=true) + expect(testNode.childNodes[0]).toContainText(""); + + // Causing the condition to become false causes the output to be displayed + viewModel.shouldHide(false); + expect(testNode.childNodes[0]).toContainText("Hello"); + + // Causing the condition to become true causes the output to disappear + viewModel.shouldHide(true); + expect(testNode.childNodes[0]).toContainText(""); + }); + + it('Data binding syntax should support \"if\" condition in conjunction with foreach', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ myTemplate: "Value: [js: myProp().childProp]" })); + testNode.innerHTML = "
"; + + var viewModel = { myProp: ko.observable({ childProp: 'abc' }) }; + ko.applyBindings(viewModel, testNode); + expect(testNode.childNodes[0].childNodes[0].nodeValue).toEqual("Value: abc"); + expect(testNode.childNodes[0].childNodes[1].nodeValue).toEqual("Value: abc"); + expect(testNode.childNodes[0].childNodes[2].nodeValue).toEqual("Value: abc"); + + // Causing the condition to become false causes the output to be removed + viewModel.myProp(null); + expect(testNode.childNodes[0]).toContainText(""); + + // Causing the condition to become true causes the output to reappear + viewModel.myProp({ childProp: 'def' }); + expect(testNode.childNodes[0].childNodes[0].nodeValue).toEqual("Value: def"); + expect(testNode.childNodes[0].childNodes[1].nodeValue).toEqual("Value: def"); + expect(testNode.childNodes[0].childNodes[2].nodeValue).toEqual("Value: def"); + }); + + it('Should be able to populate checkboxes from inside templates, despite IE6 limitations', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "" })); + ko.renderTemplate("someTemplate", null, { templateRenderingVariablesInScope: { isChecked: true } }, testNode); + expect(testNode.childNodes[0].checked).toEqual(true); + }); + + it('Should be able to populate radio buttons from inside templates, despite IE6 limitations', function () { + ko.setTemplateEngine(new dummyTemplateEngine({ someTemplate: "" })); + ko.renderTemplate("someTemplate", null, { templateRenderingVariablesInScope: { someValue: 'abc' } }, testNode); + expect(testNode.childNodes[0].checked).toEqual(true); + }); + + it('Data binding \'templateOptions\' should be passed to template', function() { + var myModel = { + someAdditionalData: { myAdditionalProp: "someAdditionalValue" }, + people: new ko.observableArray([ + { name: "Alpha" }, + { name: "Beta" } + ]) + }; + ko.setTemplateEngine(new dummyTemplateEngine({myTemplate: "
Person [js:name] has additional property [js:templateOptions.myAdditionalProp]
"})); + testNode.innerHTML = "
"; + + ko.applyBindings(myModel, testNode); + expect(testNode.childNodes[0]).toContainHtml("
person alpha has additional property someadditionalvalue
person beta has additional property someadditionalvalue
"); + }); + + it('If the template binding is updated, should dispose any template subscriptions previously associated with the element', function() { + var myObservable = ko.observable("some value"), + myModel = { + subModel: ko.observable({ myObservable: myObservable }) + }; + ko.setTemplateEngine(new dummyTemplateEngine({myTemplate: "The value is [js:myObservable()]"})); + testNode.innerHTML = "
"; + ko.applyBindings(myModel, testNode); + + // Right now the template references myObservable, so there should be exactly one subscription on it + expect(testNode.childNodes[0]).toContainText("The value is some value"); + expect(myObservable.getSubscriptionsCount()).toEqual(1); + var renderedNode1 = testNode.childNodes[0].childNodes[0]; + + // By changing the object for subModel, we force the data-bind value to be re-evaluated and the template to be re-rendered, + // setting up a new template subscription, so there have now existed two subscriptions on myObservable... + myModel.subModel({ myObservable: myObservable }); + expect(testNode.childNodes[0].childNodes[0]).not.toEqual(renderedNode1); + + // ...but, because the old subscription should have been disposed automatically, there should only be one left + expect(myObservable.getSubscriptionsCount()).toEqual(1); + }); + + it('Should be able to specify a template engine instance using data-bind syntax', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ theTemplate: "Default output" })); // Not going to use this one + var alternativeTemplateEngine = new dummyTemplateEngine({ theTemplate: "Alternative output" }); + + testNode.innerHTML = "
"; + ko.applyBindings({ chosenEngine: alternativeTemplateEngine }, testNode); + + expect(testNode.childNodes[0]).toContainText("Alternative output"); + }); + + it('Should be able to bind $data to an alias using \'as\'', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ + myTemplate: "ValueLiteral: [js:item.prop], ValueBound: " + })); + testNode.innerHTML = "
"; + ko.applyBindings({ someItem: { prop: 'Hello' } }, testNode); + expect(testNode.childNodes[0]).toContainText("ValueLiteral: Hello, ValueBound: Hello"); + }); + + it('Data-bind syntax should expose parent binding context as $parent if binding with an explicit \"data\" value', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ + myTemplate: "ValueLiteral: [js:$parent.parentProp], ValueBound: " + })); + testNode.innerHTML = "
"; + ko.applyBindings({ someItem: {}, parentProp: 'Hello' }, testNode); + expect(testNode.childNodes[0]).toContainText("ValueLiteral: Hello, ValueBound: Hello"); + }); + + it('Data-bind syntax should expose all ancestor binding contexts as $parents', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ + outerTemplate: "
", + middleTemplate: "
", + innerTemplate: "(Data:[js:$data.val], Parent:[[js:$parents[0].val]], Grandparent:[[js:$parents[1].val]], Root:[js:$root.val], Depth:[js:$parents.length])" + })); + testNode.innerHTML = "
"; + + ko.applyBindings({ + val: "ROOT", + outerItem: { + val: "OUTER", + middleItem: { + val: "MIDDLE", + innerItem: { val: "INNER" } + } + } + }, testNode); + expect(testNode.childNodes[0].childNodes[0]).toContainText("(Data:INNER, Parent:MIDDLE, Grandparent:OUTER, Root:ROOT, Depth:3)"); + }); + + it('Should not be allowed to rewrite templates that embed anonymous templates', function() { + // The reason is that your template engine's native control flow and variable evaluation logic is going to run first, independently + // of any KO-native control flow, so variables would get evaluated in the wrong context. Example: + // + //
+ // ${ somePropertyOfEachArrayItem } <-- This gets evaluated *before* the foreach binds, so it can't reference array entries + //
+ // + // It should be perfectly OK to fix this just by preventing anonymous templates within rewritten templates, because + // (1) The developer can always use their template engine's native control flow syntax instead of the KO-native ones - that will work + // (2) The developer can use KO's native templating instead, if they are keen on KO-native control flow or anonymous templates + + ko.setTemplateEngine(new dummyTemplateEngine({ + myTemplate: "
Childprop: [js: childProp]
" + })); + testNode.innerHTML = "
"; + + expect(function () { + ko.applyBindings({ someData: { childProp: 'abc' } }, testNode); + }).toThrowContaining("This template engine does not support anonymous templates nested within its templates"); + }); + + it('Should not be allowed to rewrite templates that embed control flow bindings', function() { + // Same reason as above (also include binding names with quotes and spaces to show that formatting doesn't matter) + ko.utils.arrayForEach(['if', 'ifnot', 'with', 'foreach', '"if"', ' with '], function(bindingName) { + ko.setTemplateEngine(new dummyTemplateEngine({ myTemplate: "
Hello
" })); + testNode.innerHTML = "
"; + + ko.utils.domData.clear(testNode); + expect(function () { + ko.applyBindings({ someData: { childProp: 'abc' } }, testNode); + }).toThrowContaining("This template engine does not support"); + }); + }); + + it('Data binding syntax should permit nested templates using virtual containers (with arbitrary internal whitespace and newlines)', function() { + ko.setTemplateEngine(new dummyTemplateEngine({ + outerTemplate: "Outer ", + innerTemplate: "Inner via inline binding: " + })); + var model = { }; + testNode.innerHTML = "
"; + ko.applyBindings(model, testNode); + expect(testNode.childNodes[0]).toContainHtml("outer inner via inline binding: sometext"); + }); + + it('Should be able to render anonymous templates using virtual containers', function() { + ko.setTemplateEngine(new dummyTemplateEngine()); + testNode.innerHTML = "Start Childprop: [js: childProp] End"; + ko.applyBindings({ someData: { childProp: 'abc' } }, testNode); + expect(testNode).toContainHtml("start childprop: abcend"); + }); + + it('Should be able to use anonymous templates that contain first-child comment nodes', function() { + // This represents issue https://github.com/SteveSanderson/knockout/issues/188 + // (IE < 9 strips out leading comment nodes when you use .innerHTML) + ko.setTemplateEngine(new dummyTemplateEngine({})); + testNode.innerHTML = "start
hello
"; + ko.applyBindings(null, testNode); + expect(testNode).toContainHtml('start
hellohello
'); + }); + + it('Should allow anonymous templates output to include top-level virtual elements, and will bind their virtual children only once', function() { + delete ko.bindingHandlers.nonexistentHandler; + var initCalls = 0; + ko.bindingHandlers.countInits = { init: function () { initCalls++ } }; + testNode.innerHTML = "
"; + ko.applyBindings(null, testNode); + expect(initCalls).toEqual(1); + }); + + it('Should be possible to combine template rewriting, foreach, and a node preprocessor', function() { + this.restoreAfter(ko.bindingProvider, 'instance'); + + // This spec verifies that the use of fixUpContinuousNodeArray in templating.js correctly handles the scenario + // where a memoized comment node is the first node outputted by 'foreach', and it gets removed by unmemoization. + // In this case we rely on fixUpContinuousNodeArray to work out which remaining nodes correspond to the 'foreach' + // output so they can later be removed when the model array changes. + var originalBindingProvider = ko.bindingProvider.instance, + preprocessingBindingProvider = function() { }; + preprocessingBindingProvider.prototype = originalBindingProvider; + ko.bindingProvider.instance = new preprocessingBindingProvider(); + ko.bindingProvider.instance.preprocessNode = function(node) { + // This preprocessor doesn't change the rendered nodes. But simply having a preprocessor means + // that templating.js has to recompute which DOM nodes correspond to the foreach output, since + // you might have modified that set. + return [node]; + }; + + ko.setTemplateEngine(new dummyTemplateEngine({})); + testNode.innerHTML = "
OK.
"; + var items = ko.observableArray(['Alpha', 'Beta']); + ko.applyBindings({ items: items }, testNode); + expect(testNode).toContainText('Alpha OK. Beta OK. '); + + // Check that 'foreach' knows which set of elements to remove when an item vanishes from the model array, + // even though the original 'foreach' output's first node, the memo comment, was removed during unmemoization. + items.shift(); + expect(testNode).toContainText('Beta OK. '); + }); + + it('Should not throw errors if trying to apply text to a non-rendered node', function() { + // Represents https://github.com/SteveSanderson/knockout/issues/660 + // A can't go directly into a , so modern browsers will silently strip it. We need to verify this doesn't + // throw errors during unmemoization (when unmemoizing, it will try to apply the text to the following text node + // instead of the node you intended to bind to). + // Note that IE < 9 won't strip the ; instead it has much stranger behaviors regarding unexpected DOM structures. + // It just happens not to give an error in this particular case, though it would throw errors in many other cases + // of malformed template DOM. + ko.setTemplateEngine(new dummyTemplateEngine({ + myTemplate: " " // The whitespace after the closing span is what triggers the strange HTML parsing + })); + testNode.innerHTML = "
"; + ko.applyBindings(null, testNode); + // Since the actual template markup was invalid, we don't really care what the + // resulting DOM looks like. We are only verifying there were no exceptions. + }); +}) diff --git a/spec/utilsBehaviors.js b/spec/utilsBehaviors.js new file mode 100644 index 000000000..a2b04769f --- /dev/null +++ b/spec/utilsBehaviors.js @@ -0,0 +1,30 @@ +describe('unwrapObservable', function() { + it('Should return the underlying value of observables', function() { + var someObject = { abc: 123 }, + observablePrimitiveValue = ko.observable(123), + observableObjectValue = ko.observable(someObject), + observableNullValue = ko.observable(null), + observableUndefinedValue = ko.observable(undefined), + computedValue = ko.computed(function() { return observablePrimitiveValue() + 1; }); + + expect(ko.utils.unwrapObservable(observablePrimitiveValue)).toBe(123); + expect(ko.utils.unwrapObservable(observableObjectValue)).toBe(someObject); + expect(ko.utils.unwrapObservable(observableNullValue)).toBe(null); + expect(ko.utils.unwrapObservable(observableUndefinedValue)).toBe(undefined); + expect(ko.utils.unwrapObservable(computedValue)).toBe(124); + }); + + it('Should return the supplied value for non-observables', function() { + var someObject = { abc: 123 }; + + expect(ko.utils.unwrapObservable(123)).toBe(123); + expect(ko.utils.unwrapObservable(someObject)).toBe(someObject); + expect(ko.utils.unwrapObservable(null)).toBe(null); + expect(ko.utils.unwrapObservable(undefined)).toBe(undefined); + }); + + it('Should be aliased as ko.unwrap', function() { + expect(ko.unwrap).toBe(ko.utils.unwrapObservable); + expect(ko.unwrap(ko.observable('some value'))).toBe('some value'); + }); +}); \ No newline at end of file diff --git a/upgrade-notes/v3.0.0.md b/upgrade-notes/v3.0.0.md new file mode 100644 index 000000000..99eab28f3 --- /dev/null +++ b/upgrade-notes/v3.0.0.md @@ -0,0 +1,38 @@ +--- +layout: documentation +title: v3.0.0 Upgrade Notes +pathprefix: ../ +mainmenukeyoverride: installation +--- + +Knockout.js takes backward compatibility seriously. If you're using a recent v2.x build, you will typically be able to drop in Knockout v3.0.0 without having to make any changes to your application code. Version 3.0.0 is intended to be fully backward-compatible except for a few carefully chosen design changes that enable major new features or fix longstanding issues. + +### 1. Computed properties now notify only when their value changes + +In Knockout v2.x, `ko.computed` properties would issue a "change" notification to their subscribers whenever they *re-evaluated*, even if the evaluation result was clearly identical to the previous one. + +Many Knockout developers found this inconvenient because it caused unnecessary re-processing or duplicate actions. By popular demand we've changed the default behavior so that `ko.computed` does not issue "change" notifications after re-evaluation if the new value is definitely identical to the previous one (i.e., it's a primitive - string/boolean/number/null/undefined - and equals the previous value). + +This makes `ko.computed` consistent with `ko.observable`, which has always suppressed notifications if you reassign the same primitive value to it. + +**Restoring the earlier behavior** + +If you have a computed property that requires the v2.x behavior, i.e., you want repeated notifications even if the computed value is primitive and unchanged, you can enable this as follows: + + myComputed.extend({ notify: 'always' }); + +### 2. Bindings are now refreshed independently + +In Knockout v2.x, all bindings on the same element would refresh at the same time. Consider the following example: + + + +If your viewmodel changes `acceptsTerms`, then of course Knockout will re-run the `checked` binding to update the checkbox in the UI. But what you might not have realised is that, in v2.x, Knockout would *also* re-run the `visible` binding even though `showTerms` hasn't changed. Although this usually caused no problems, it could lead to surprising bugs in advanced scenarios with custom binding handlers. + +Knockout v3 has a greatly improved binding mechanism that refreshes all bindings independently and only when necessary. This improves performance and eliminates a whole category of potential problems with cross-binding dependencies. This change will only affect you if your code relies on v2.x's undocumented implementation detail of cross-binding dependencies. In this case, you will need to update your code to stop relying on the obsolete behavior. + +### 3. optionsCaption now HTML-encodes its output + +In v2.x, [`optionsCaption`]({{ page.pathprefix }}documentation/options-binding.html) did not HTML-encode its value. This was very inconvenient for developers who needed to display untrusted user-provided values, and was a security issue for developers who didn't notice it. Knockout v3 now does HTML-encode `optionsCaption` values for display, making it consistent with the `text` binding which has always done so. + +If you previously solved this by manually HTML-encoding strings before supplying them to `optionsCaption`, you'll need to remove that logic otherwise the string will be double-encoded.

Text value:
Password:
Bool value:
Selected option:
Multi-selected options:
Radio button selection:

Text value (updates on change):
Text value (updates on keystroke):
Text value (multi-line):
Password:
Checkbox:
Drop-down list:
Multi-select drop-down list:
Radio buttons:	+ Alpha + Beta + Gamma +

Getting started

Observables

Bindings

Controlling text and appearance

Control flow

Working with form fields

Rendering templates

Binding syntax

Creating custom bindings

Further techniques

Plugins

More information

Introductory examples

Detailed examples

Run it:

Source code:

Source code: View

Source code: View model

Live example

Source code: View

Source code: View model

{{ page.title }}

{{ page.title }}

Hello, !

All tasks ( )

Done tasks ( )

People

Participants

People

Stuff you have typed:

What's in the model?

HTML controls

Hello, !

Key concepts

More features

Get started

New: Interactive tutorials

Live example

Hello SyntaxHighlighter