Getting started

  1. How KO works and what benefits it brings
  2. Downloading and installing

Observables

  1. Creating view models with observables
  2. Working with observable arrays

Computed observables

  1. Using computed observables
  2. Writable computed observables
  3. How dependency tracking works
  4. Pure computed observables
  5. Reference

Bindings

Controlling text and appearance

  1. The visible binding
  2. The text binding
  3. The html binding
  4. The css binding
  5. The style binding
  6. The attr binding

Control flow

  1. The foreach binding
  2. The if binding
  3. The ifnot binding
  4. The with binding
  5. The component binding

Working with form fields

  1. The click binding
  2. The event binding
  3. The submit binding
  4. The enable binding
  5. The disable binding
  6. The value binding
  7. The textInput binding
  8. The hasFocus binding
  9. The checked binding
  10. The options binding
  11. The selectedOptions binding
  12. The uniqueName binding

Rendering templates

  1. The template binding

Binding syntax

  1. The data-bind syntax
  2. The binding context

Creating custom bindings

  1. Creating custom bindings
  2. Controlling descendant bindings
  3. Supporting virtual elements
  4. Custom disposal logic

Components

  1. Overview: What components and custom elements offer
  2. Defining and registering components
  3. The component binding
  4. Using custom elements
  5. Advanced: Custom component loaders

Further techniques

  1. Loading and saving JSON data
  2. Extending observables
  3. Rate-limiting observables
  4. Unobtrusive event handling
  5. Using fn to add custom functions
  6. Extending Knockout's binding syntax

Plugins

  1. The mapping plugin

More information

  1. Browser support
  2. Getting help
  3. Links to tutorials & examples
  4. Usage with AMD using RequireJs (Asynchronous Module Definition)

Loading and Saving JSON data

Knockout allows you to implement sophisticated client-side interactivity, but almost all web applications also need to exchange data with the server, or at least to serialize the data for local storage. The most convenient way to exchange or store data is in JSON format - the format that the majority of Ajax applications use today.

Loading or Saving Data

Knockout doesn’t force you to use any one particular technique to load or save data. You can use whatever mechanism is a convenient fit for your chosen server-side technology. The most commonly-used mechanism is jQuery’s Ajax helper methods, such as getJSON, post, and ajax. You can fetch data from the server:

$.getJSON("/some/url", function(data) { 
	// Now use this data to update your view models, 
	// and Knockout will update your UI automatically 
})

… or you can send data to the server:

var data = /* Your data in JSON format - see below */;
$.post("/some/url", data, function(returnedData) {
	// This callback is executed if the post was successful		
})

Or, if you don’t want to use jQuery, you can use any other mechanism for loading or saving JSON data. So, all Knockout needs to help you do is:

  • For saving, get your view model data into a simple JSON format so you can send it using one of the above techniques
  • For loading, update your view model using data that you’ve received using one of the above techniques

Converting View Model Data to Plain JSON

Your view models are JavaScript objects, so in a sense, you could just serialize them as JSON using any standard JSON serializer, such as JSON.stringify (a native function in modern browsers), or the json2.js library. However, your view models probably contain observables, computed observables, and observable arrays, which are implemented as JavaScript functions and therefore won’t always serialize cleanly without additional work on your behalf.

To make it easy to serialize view model data, including observables and the like, Knockout includes two helper functions:

  • ko.toJS — this clones your view model’s object graph, substituting for each observable the current value of that observable, so you get a plain copy that contains only your data and no Knockout-related artifacts
  • ko.toJSON — this produces a JSON string representing your view model’s data. Internally, it simply calls ko.toJS on your view model, and then uses the browser’s native JSON serializer on the result. Note: for this to work on older browsers that have no native JSON serializer (e.g., IE 7 or earlier), you must also reference the json2.js library.

For example, define a view model as follows:

var viewModel = {
    firstName : ko.observable("Bert"),
    lastName : ko.observable("Smith"),
    pets : ko.observableArray(["Cat", "Dog", "Fish"]),
    type : "Customer"
};
viewModel.hasALotOfPets = ko.computed(function() {
    return this.pets().length > 2
}, viewModel)

This contains a mix of observables, computed observables, observable arrays, and plain values. You can convert it to a JSON string suitable for sending to the server using ko.toJSON as follows:

var jsonData = ko.toJSON(viewModel);

// Result: jsonData is now a string equal to the following value
// '{"firstName":"Bert","lastName":"Smith","pets":["Cat","Dog","Fish"],"type":"Customer","hasALotOfPets":true}'

Or, if you just want the plain JavaScript object graph before serialization, use ko.toJS as follows:

var plainJs = ko.toJS(viewModel);

// Result: plainJS is now a plain JavaScript object in which nothing is observable. It's just data.
// The object is equivalent to the following:
//   {
//      firstName: "Bert",
//      lastName: "Smith",
//      pets: ["Cat","Dog","Fish"],
//      type: "Customer",
//      hasALotOfPets: true
//   }

Note that ko.toJSON accepts the same arguments as JSON.stringify. For example, it can be useful to have a “live” representation of your view model data when debugging a Knockout application. To generate a nicely formatted display for this purpose, you can pass the spaces argument into ko.toJSON and bind against your view model like:

<pre data-bind="text: ko.toJSON($root, null, 2)"></pre>

Updating View Model Data using JSON

If you’ve loaded some data from the server and want to use it to update your view model, the most straightforward way is to do it yourself. For example,

// Load and parse the JSON
var someJSON = /* Omitted: fetch it from the server however you want */;
var parsed = JSON.parse(someJSON);

// Update view model properties
viewModel.firstName(parsed.firstName);
viewModel.pets(parsed.pets);

In many scenarios, this direct approach is the simplest and most flexible solution. Of course, as you update the properties on your view model, Knockout will take care of updating the visible UI to match it.

However, many developers prefer to use a more conventions-based approach to updating their view models using incoming data without manually writing a line of code for every property to be updated. This can be beneficial if your view models have many properties, or deeply nested data structures, because it can greatly reduce the amount of manual mapping code you need to write. For more details about this technique, see the knockout.mapping plugin.