can-connect/real-time/real-time

Use

To use real-time, create a connection with its dependent behaviors like:

var todoConnection = connect(
   ["real-time",
    "constructor",
    "constructor-store",
    "constructor-callbacks-once",
    "data-url"],{
  url: "/todos"
});

Next, use the connection to load lists and save those lists in the store:

todoConnection.getList({complete: false}).then(function(todos){
  todoConnection.addListReference(todos);
})

Finally, use one of the createInstance, updateInstance, and destroyInstance methods to tell the connection that data has changed. The connection will update (by calling splice) each list accordingly.

Example

The following demo shows two lists that use this connection. The "Run Code" button sends the connection data changes which the connection will then update lists accordingly:

This example creates a todoList function and todoItem function that manage the behavior of a list of todos and a single todo respectfully. It uses Object.observe to observe changes in the todo list and individual todo data. Other frameworks will typically provide their own observable system.

todoList

When todoList is created, it is passed the set of data to load. It uses this to get todos from the todoConnection like:

todosConnection.getList(set).then(function(retrievedTodos){

It then adds those todos to the listStore so they can be updated automatically. And, it listens to changes in todos and calls an update function:

todosConnection.addListReference(todos);
Object.observe(todos, update, ["add", "update", "delete"] );

The update function is able to inserted new todoItems in the page when items are added to or removed from todos. We exploit that by calling update as if it just added each todo in the list:

update(todos.map(function(todo, i){
  return {
    type: "add",
    name: ""+i
  };
}));

todoItem

The todoItem creates an element that updates with changes in its todo. It listens to changes in the todo and saves the todo in the instanceStore with the following:

Object.observe(todo, update, ["add", "update", "delete"] );
todosConnection.addInstanceReference(todo);

A todoItem needs to be able to stop listening on the todo and remove itself from the instanceStore if the todo is removed from the page. To provide this teardown functionality, todoItem listens to a "removed" event on its element and unobserves the todo and removes it from the instanceStore:

$(li).bind("removed", function(){
  Object.unobserve(todo, update, ["add", "update", "delete"] );
  todosConnection.deleteInstanceReference(todo);
});