0.7 Documents

A Doc is a client's view on a sharejs document. It is is uniquely identified by its name and collection. Documents should not be created directly. Create them with Connection.get()

TODO More on document creation.

Subscriptions

We can subscribe a document to stay in sync with the server.

doc.subscribe(function(error) {
  doc.state // = 'ready'
  doc.subscribed // = true
})

The server now sends us all changes concerning this document and these are applied to our snapshot. If the subscription was successful the initial snapshot and version sent by the server are loaded into the document.

To stop listening to the changes we call doc.unsubscribe().

If we just want to load the data but not stay up-to-date, we call

  doc.fetch(function(error) {
    doc.snapshot // sent by server
  })

TODO What happens when the document does not exist yet.

Editing documents

To edit a document we have to create an editing context

  context = doc.context()

The context is an object exposing the type API of the documents OT type.

  doc.type = 'text'
  context.insert(0, 'In the beginning')
  doc.snapshot // 'In the beginning...'

If a operation is applied on the snapshot the _onOp on the context is called. The type implementation then usually triggers a corresponding event.

Events

You can use doc.on(eventName, callback) to subscribe to the following events:

• before op (op, localSite) Fired before an operation is applied to the document.
• op (op, localSite) Fired right after an operation (or part of an operation) has been applied to the document. Submitting another op here is invalid - wait until 'after op' if you want to submit more operations. - changed (op)
• after op (op, localSite) Fired after an operation has been applied. You can submit more ops here.
• subscribed (error) The document was subscribed
• unsubscribed (error) The document was unsubscribed
• created (context) The document was created. That means its type was set and it has some initial data.
• del (context, snapshot)
• error