Knockback.js

Knockback.js API and Usage Examples

Welcome to Knockback.js!

Please browser the API reference on the left to learn more about the API.

Also check out the Tutorials (on the top nav bar) to learn how to solve some common use cases or to learn something new!

API Coding Conventions

Knockback uses the following conventions: ClassName, functionName, property_name, 'constant string', "dynamic string", CONSTANT_NAME

API Indicators

  • class: indicates a class function that needs to be called in the form kb.ClassName.functionName()

  • optional: indicates that function parameters or options can be left out

  • factory: indicates a factory function is being described. Please note that many of the Knockout classes have corresponding factory functions to reduce verbosity and to improve consistency with Knockout.js

    For example, 'ko.observable(model, 'name')' is equivalent to 'new ko.Observable(model, 'name')'

    Be careful to use the class if you call the kb.utils.observableInstanceOf utility function warning

  • dual purpose: indicates that a function is both a getter and a setter.

    For example, this one gets the model: 'view_model.model()' whereas this one sets the model: 'view_model.model(model)'

  • observable returned: indicates that an observable class is returned rather than 'this' from a constructor or function. This is used to so that they can be used like dual purpose functions and use Knockout's dependency tracking. If you derive from one of Knockback's observable classes, use kb.utils.wrappedObservable(instance) to return the observable instead of the class instance if you are overriding one of these special functions.

Other Things Worth Knowing

  1. Knockout Observables Foundations: All Knockback.js classes return Knockout.js observables so their dependencies can and should be managed like any Knockout observable.

  2. Namespace Aliasing: 'kb' and 'Knockback' can be used interchangeably

  3. Backbone.Model Signatures: Knockback.js does not require Backbone.Models for attribute watching, but requires Backbone.Model-like implementations that conform to the following signatures:
    • Backbone.Events: 'bind(event, callback)', 'unbind(event, callback)', and 'trigger(event, params...)'
    • Backbone.Model: 'get(attribute_name)'
    and triggers 'change' and/or "change:\#{attribute_name}" events when the Backbone.Models-like instance's attributes change.

    This fact is used when implementing a Custom Locale Manager and could be used to port another library like Spine.js to Knockback.js.

Note on Relationships between Models and ViewModels - Often One-To-Many

The distinction between Models and ViewModels is important:

  • Backbone.Models encapsulate the data and operations on the data, are serialized/deserialized from/to the server, and are in short Models.
  • ViewModels provide the attributes and logic to the templates often interacting with the Model data like Controllers. However, they may have their own data and logic that is purely View-related and that the server should never know about.

Besides providing a clean separation between data and display, this separation becomes important in a larger application. In a larger application, you often have different ways to present the same Model with different ViewModels. For example, a Model could have the following ViewModels:

  • Thumbnail View: the ViewModel could only expose a subset of the Model's attributes, dates/time may be in the shortest format possible, or maybe just an image would be provided to the template.
  • 'Cell View:' the ViewModel could again expose a subset of only the most relevant summary attributes, routing information to a detailed summary view, etc.
  • Editing View: the ViewModel could expose almost all of the Model's attributes, localized labels for each, data and functions for the editing controls and functionality, routing information to specialized editing views, etc.

Important to understand that in a larger application the relationship between Models and ViewModels tends to be one-to-many. In this application, there is a one-to-many relationship from the Priority model through the the HeaderViewModel and TodoViewModel ViewModels because each one uses the Priority for rendering their priority colors and providing priority settings data to their tooltip, but the actions on selecting a priority in the tool tip differ.