#Set up socket.io as you normally would
sio = io.listen expressApp
#create an instance of the Skull.Server
skullServer = new Skull.Server sio
#Create a namespace where we'll expose the models
app = @skullServer.of '/app'
#Expose your models to the world.
app.addModel '/todos', new TodoModel()
app.addModel '/myModel', new MyModel()
#Models must be subclasses of Skull.Model and must implement the methods 'create', 'update', 'delete'. See below.
#See example/app/example.coffee for server-side example

Must subclass Skull.Model and must implement the 'create', 'update', 'delete' and 'read' methods.
See example/app/index.coffee for examples on how to create the models.

A method has the following signature and implementation:

create: (data, callback, socket) ->
#save the data to the database or whatever
#notify the initiating user that the action succeeded
callback null, data
#emit the 'create' event. Skull will automatically broadcast this event to all other connected users.
@emit 'create', data, socket
#The last parameter is the socket which initiated the action. If omitted, the event is sent to all
#users in the namespace.

A model may also implement 'broadcast' and 'clientCommand' methods.

The 'broadcast' event is used to notify other users of something. It usually doesn't involve changing the model's data.
Client models will receive the 'server-broadcast' event, which you can bind to.
This server-side snippet will just forward the event to all clients.

Private models are models which contain different data depending on the user who accesses them (eg. user settings).
In your server-side code, these models must be derived from Skull.SidModel and they act as 'dispatchers' which forward messages between the client and the specific model for that client.

Check out examples/app to see how user settings are implemented there.

Model locking is used to handle multiple users trying to change the same model at the same time.

The idea:

Before a model can be edited, call model.tryLock() on the client side. When the server confirms the lock, show the edit controls.
Then call model.save() to commit the changes to the server. This will also unlock the model.
If user cancels edit, call model.unlock().

model.tryLock() may fail if another user is currently editing (holding the lock). In this case, the err argument of the callback will
be non-null.

Models are automatically unlocked when the socket which holds the lock disconnects.

The format of the filter parameter depends on how you want to filter your data. Usually, it contains the id of
the parent item, but you can implement more advanced filters. To achieve this, override the 'matchFilter' method of your server-side model.

The filter parameter can also be an array. This is useful if you want to display multiple subsets of the data:

model.fetch filter: [id_post: 1, id_post: 2]

See the example/emodels sample which implements model filtering.
Notice how browsers which display the same post receive update events, while others don't.

Because of how Backbone is designed, I find that it is more convenient to use a relational database to store your data on the server.
Document stores, like MongoDB, can be used, but it requires you to model your data in a relational way, eg. I found it difficult to
elegantly use embedded documents/collections with Backbone + Skull.

This project would have been impossible without the incredible work of the wizards who created CoffeeScript, Backbone.js,
socket.io, express and of course node.js. For me these guys are an inspiration.