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.
Need help? Visit our