Knockout-REST

Knockout-REST is a simple library to extend Knockout.js objects with RESTful actions.

Author

Francesco Pontillo

Description:

The library implements classes and methods to access a RESTful service, GET, PUT, POST, DELETE for any resource. It aims to provide a general extensible framework for RESTful application consumers. Every entity:

• is an observable, nested objects as well
• has a dirty observable (if object.person.name changes, object gets dirty)
• can track its and its children's changes
• can undo all the changes in the item

License:

The library is released "as is", without any warranty nor promises. It is licensed under the MIT license.

Getting started

Knockout-REST requires three libraries:

• knockout-2.1.0.js (it should work with 2.0.0+), for the whole data-bind sorcery
• knockout.mapping-2.1.0.js, for mapping objects to and from our RESTful Web Service
• jQuery, uses $.ajax

Basic Usage

Knockout-REST is very simple to use. Let's first create a ViewModel for our page, assuming we want it to contain just a person, for now.

varVM=function(){varself=this;self.person;};

Let's now instantiate the view model, and create the person as a REST Entity.

varmVM=newVM();mVM.person=newko.pontillo.rest.entity();

The ko.pontillo.rest.entity() can accept an empty entity object: it will be used as soon as you do something like:

// Creates a new person, ready to be data-bound, if it's not alreadymVM.person.newEntity();

RESTful Actions

Every entity can be bound to a URL.

// GET a personmVM.person.Get("api/people/123");// PUT (update) a personmVM.person.Put("api/people/123");// DELETE a personmVM.person.Delete("api/people/123");// POST (create) a personmVM.person.Post("api/people");

Entity does not assume anything in regards to the resource URL, so you'll need to pass one every time you make a call to the Web Service. This default behavior can be overridden by extending the Entity and creating a custom class that handles URLs by itself.

Every RESTful Action on entities accepts a success callback. An error callback will be implemented in the future.

Change tracking

All entities have a few observables tracking the state of the entity itself.

• isUpdating checks if an entity is currently being updated from the server.
• isLoaded checks if an entity is loaded.
• isGot is true when an entity was got from the server, false otherwise.
• isError checks for an error state for an entity. Every error from the REST service sets the entity's isError to true.
• hasChanged is true when the entity was changed and the changes are not yet committed to the Web Service.

Undo changes

If you want to restore an entity without having to reload it from the Web Service, you can do so.

// First checks if the entity has changed// (optional, the check is made by the undo method)if(mVM.person.hasChanged()){// Undo all changes to the personmVM.person.undo();}

A simple example

// The ViewModel classvarVM=function(){varself=this;self.person;};// Create a new ViewModel objectvarmVM=newVM();// Instantiate a person as a REST entitymVM.person=newko.pontillo.rest.entity();// Get the personmVM.person.Get("api/people/123");// Click binding to the save button$("button#save").click(function(){// First checks if the entity has changedif(mVM.person.hasChanged()){// PUT (update) the personmVM.person.Put("api/people/123");}});// Click binding to the delete button$("button#delete").click(function(){// DELETE a personmVM.person.Delete("api/people/123");});// Click binding to the undo button$("button#undo").click(function(){// Undo all changes to the personmVM.person.undo();});// Apply the knockout bindingsko.applyBindings(mVM);

<divdata-bind="if: person().isLoaded()"><inputtype="text" data-bind="value: person().firstname" /><inputtype="text" data-bind="value: person().lastname" /><inputtype="button" id="save" /><inputtype="button" id="delete" /><inputtype="button" id="undo" /></div>