Hide

Build a Collaborative Data Model

The Realtime data model stores your application’s data. When you insert or modify data in the model, it is automatically persisted and shared, and any conflicts between different users' changes are automatically resolved.

Model Structure

The API provides building blocks for storing different types of data within the model. You use these building blocks to create a model structure that makes sense for your use case.

The group of objects that have built-in collaboration are collectively called collaborative objects. These objects automatically resolve conflicts between users at a fine level of granularity. The primary collaborative object types are:

  • CollaborativeString: A string with character by character collaboration.
  • CollaborativeList: An ordered list of valid object types.
  • CollaborativeMap: A map from a string key to any valid object type.
  • IndexReference: A pointer to a particular location in a CollaborativeString or CollaborativeList. Useful for tracking user cursors or ranges of text.

Additionally, you can create custom collaborative objects, which are JavaScript objects with properties that are CollaborativeObject types. For more information about using custom collaborative objects, see Custom Objects.

Collaborative objects can also contain non-collaborative objects, including strings, numbers, booleans, Objects and Arrays. These objects are treated as an atomic unit: if multiple collaborators make changes to any part of this object, one collaborator’s entire version will win. This is useful for situations where a merge between different users' edits would not make sense.

Each model initially contains a single CollaborativeMap with an ID of root. Application-specific objects should be added to the root or to another collaborative object which can be reached from the root CollaborativeMap. Collaborative objects that aren't reachable from the root can't be used by other collaborators and won't be available when your application is reloaded.

Document Lifecycle

Pre-Load

Before a model is loaded, you may register any custom object types and the collaborative fields they contain. See custom objects. If you use custom object, the API needs this information before gapi.drive.realtime.load is invoked in order to properly construct the JavaScript representation of the model.

Model Initialization

Model initialization is performed exactly once for each Realtime document the first time the document is loaded. This is distinct from loading, which occurs each time a user opens the document.

At initialization time you should construct the CollaborativeObjects that make up a valid empty data model for your application. These are the objects that should always be present in order for the model to be valid.

Your initialization function must be passed to gapi.drive.realtime.load when your application loads a document.

Loading the Document and Model

Model load is performed each time the document is loaded. At this time you should tie your UI to the model by examining the current model state to initialize your view, and set up appropriate event listeners to be notified of changes to the model. See Model Events.

You may specify an onLoaded handler that will be called when document loading is complete. The hander is passed in when loading a document via gapi.drive.realtime.load.

Editing and Collaboration on an Active Document

While the document is open, the model can change at any time based on collaborator changes. Listen to the events that you registered in your onLoad handler to be informed of changes. You can write to the model at any time. Changes are automatically saved as they are made. You can verify the save state by listening for DocumentSaveStateChangedEvents on the Document.

Document Close

Documents can be closed by calling Document.close. Additionally, certain fatal errors cause the document to be closed automatically. Once the document is closed, no changes will be saved and any attempt to access the data model will cause a DocumentClosedError.

Send feedback about...

Realtime API