Hide

Namespace: realtime

Child classes
AttributeChangedEvent

An event indicating that a document attribute has changed.

BaseModelEvent

An event that indicates a change to the collaborative model. All specific model event types inherit from this class.

CollaborativeList

A collaborative list. A list can contain other Realtime collaborative objects, custom collaborative objects, JavaScript primitive values, or JavaScript objects that can be serialized to JSON.

Changes to the list will automatically be synced with the server and other collaborators. To listen for changes, add EventListeners for the following event types:

  • gapi.drive.realtime.EventType.VALUES_ADDED

  • gapi.drive.realtime.EventType.VALUES_REMOVED

  • gapi.drive.realtime.EventType.VALUES_SET

CollaborativeMap

A collaborative map. A map's key must be a string. The values can contain other Realtime collaborative objects, custom collaborative objects, JavaScript primitive values or JavaScript objects that can be serialized to JSON.

Changes to the map will automatically be synced with the server and other collaborators. To listen for changes, add EventListeners for the gapi.drive.realtime.EventType.VALUE_CHANGED event type.

CollaborativeObject

CollaborativeObject contains behavior common to all built in collaborative types.

CollaborativeString

Creates a new collaborative string. Unlike regular JavaScript strings, collaborative strings are mutable.

Changes to the string will automatically be synced with the server and other collaborators. To listen for changes, add EventListeners for the following event types:

  • gapi.drive.realtime.EventType.TEXT_INSERTED
  • gapi.drive.realtime.EventType.TEXT_DELETED
Collaborator
CollaboratorJoinedEvent

An event indicating that a new collaborator has joined the document.

CollaboratorLeftEvent
Document

A Realtime document. A document consists of a Realtime model and a set of collaborators. Listen on the document for the following events:

  • gapi.drive.realtime.EventType.ATTRIBUTE_CHANGED
  • gapi.drive.realtime.EventType.COLLABORATOR_LEFT
  • gapi.drive.realtime.EventType.COLLABORATOR_JOINED
  • gapi.drive.realtime.EventType.DOCUMENT_SAVE_STATE_CHANGED
DocumentClosedError

An error that is thrown when attempting to access a closed document (or any model or collaborative object associated with a closed document).

DocumentSaveStateChangedEvent

An event that indicates that the save state of a document has changed. If isSaving is false, the document is completely saved and up to date.

Error

An error affecting the realtime document.

EventTarget

An event target which can dispatch events to interested listeners. Listeners subscribe via addEventListener.

IndexReference

An IndexReference is a pointer to a specific location in a collaborative list or string. This pointer automatically shifts as new elements are added to and removed from the object.

To listen for changes to the referenced index, add an EventListener for gapi.drive.realtime.EventType.REFERENCE_SHIFTED.

Model

The collaborative model is the data model for a Realtime document. The document's object graph should be added to the model under the root object. All objects that are part of the model must be accessible from this root.

The model class is also used to create instances of built in and custom collaborative objects via the appropriate create method.

Listen on the model for the following events:

  • gapi.drive.realtime.EventType.UNDO_REDO_STATE_CHANGED
ObjectChangedEvent

Event fired when a collaborative object changes. This event will bubble to all of the ancestors of the changed object. It includes an array of events describing the specific changes.

ReferenceShiftedEvent

Event fired when an index reference shifts.

TextDeletedEvent

Event fired when text is removed from a string.

TextInsertedEvent

Event fired when text is inserted into a string.

UndoRedoStateChangedEvent

An event indicating that canUndo or canRedo changed.

ValueChangedEvent

Event fired when a map or custom object property changes.

ValuesAddedEvent

Event fired when items are added to a collaborative list.

ValuesRemovedEvent

Event fired when items are removed from a collaborative list.

ValuesSetEvent

Event fired when items in a collaborative list are changed in place.

Namespaces
custom void

A namespace that includes methods for registering and working with custom collaborative objects.

databinding void

A namespace that includes classes and methods for binding collaborative objects to UI elements.

Properties
Attribute string

Metadata attributes for a Realtime document. To be notified when an attribute is changed, subscribe to the gapi.drive.realtime.EventType.ATTRIBUTE_CHANGED event on the Document object.

CollaborativeTypes string

Type names for built-in collaborative types.

ErrorType string

Errors that can occur while loading or collaborating on a document.

EventType string

Events fired by the document or collaborative objects.

Methods
debug() void

Opens the debugger application on the current page. The debugger shows all realtime documents that the page has loaded and is able to view, edit and debug all aspects of each realtime document.

enableTestMode() void

Enables test mode for the Realtime API. After test mode is enabled, any file that is loaded will not be loaded from the server and no network requests will be made. Instead, the loaded data model will be empty and all changes will persist only until the page is reloaded. Event handlers will fire normally. This mode is intended for use in unit testing.

load(fileId, onLoaded[, opt_initializerFn][, opt_errorFn]) void

Loads the Realtime document associated with fileId. If no Realtime document is associated with fileId, a new Realtime document associated with fileId will be created.

loadAppDataDocument(onLoaded[, opt_initializerFn][, opt_errorFn]) void

Loads a Realtime document that is appropriate for storing data that is application and user specific, such as preferences. For a given authenticated user and application, this document is guaranteed to be a singleton. If no such a document exists, it will be created in the authenticated application's hidden "Application Data" folder (if the "Application Data" folder does not exist it will be created as well).

To use this function, the OAuth token must have the drive.appdata scope. See https://developers.google.com/drive/appdata for more details on the Application Data folder.

loadFromJson(json[, opt_errorFn]) gapi.drive.realtime.Document

Loads an in-memory document from a json string. This document does not talk to the server and will only exist in memory for as long as the browser session exists.

newInMemoryDocument([opt_onLoaded][, opt_initializerFn][, opt_errorFn]) gapi.drive.realtime.Document

Creates a new file with fake network communications. This file will not talk to the server and will only exist in memory for as long as the browser session persists.

Properties

static
Attribute  string

Metadata attributes for a Realtime document. To be notified when an attribute is changed, subscribe to the gapi.drive.realtime.EventType.ATTRIBUTE_CHANGED event on the Document object.

Property

Name Type Optional Description

IS_READ_ONLY

string

 

An attribute which indicates whether the document is read-only.

Defaults to is_read_only.

static
CollaborativeTypes  string

Type names for built-in collaborative types.

Properties

Name Type Optional Description

COLLABORATIVE_MAP

string

 

The type name for a collaborative map.

Defaults to Map.

COLLABORATIVE_LIST

string

 

The type name for a collaborative list.

Defaults to List.

COLLABORATIVE_STRING

string

 

The type name for a collaborative string.

Defaults to EditableString.

INDEX_REFERENCE

string

 

The type name for an index reference.

Defaults to IndexReference.

static
ErrorType  string

Errors that can occur while loading or collaborating on a document.

Properties

Name Type Optional Description

CONCURRENT_CREATION

string

 

Another user created the document's initial state after gapi.drive.realtime.load was called but before the local creation was saved.

Defaults to concurrent_creation.

INVALID_COMPOUND_OPERATION

string

 

A compound operation was still open at the end of a synchronous block. Compound operations must always be ended in the same synchronous block that they are started.

Defaults to invalid_compound_operation.

INVALID_JSON_SYNTAX

string

 

The user tried to decode a brix model that contained invalid json.

Defaults to invalid_json_syntax.

MISSING_PROPERTY

string

 

The user tried to decode a brix model that was missing a neccessary property.

Defaults to missing_property.

NOT_FOUND

string

 

The provided document ID could not be found.

Defaults to not_found.

FORBIDDEN

string

 

The user associated with the provided OAuth token is not authorized to access the provided document ID.

Defaults to forbidden.

SERVER_ERROR

string

 

An internal error occurred in the Drive Realtime API server.

Defaults to server_error.

CLIENT_ERROR

string

 

An internal error occurred in the Drive Realtime API client.

Defaults to client_error.

TOKEN_REFRESH_REQUIRED

string

 

The provided OAuth token is no longer valid and must be refreshed.

Defaults to token_refresh_required.

INVALID_ELEMENT_TYPE

string

 

The provided JSON element does not have the expected type.

Defaults to invalid_element_type.

NO_WRITE_PERMISSION

string

 

The user does not have permission to edit the document.

Defaults to no_write_permission.

static
EventType  string

Events fired by the document or collaborative objects.

Properties

Name Type Optional Description

OBJECT_CHANGED

string

 

A collaborative object has changed. This event wraps a specific event, and bubbles to ancestors.

Defaults to object_changed.

VALUES_SET

string

 

Values in a list are changed in place.

Defaults to values_set.

VALUES_ADDED

string

 

New values have been added to the list.

Defaults to values_added.

VALUES_REMOVED

string

 

Values have been removed from the list.

Defaults to values_removed.

VALUE_CHANGED

string

 

A map or custom object value has changed. Note this could be a new value or deleted value.

Defaults to value_changed.

TEXT_INSERTED

string

 

Text has been inserted into a string.

Defaults to text_inserted.

TEXT_DELETED

string

 

Text has been removed from a string.

Defaults to text_deleted.

COLLABORATOR_JOINED

string

 

A new collaborator joined the document. Listen on the gapi.drive.realtime.Document for these changes.

Defaults to collaborator_joined.

COLLABORATOR_LEFT

string

 

A collaborator left the document. Listen on the gapi.drive.realtime.Document for these changes.

Defaults to collaborator_left.

REFERENCE_SHIFTED

string

 

An index reference changed.

Defaults to reference_shifted.

DOCUMENT_SAVE_STATE_CHANGED

string

 

The document save state changed. Listen on the gapi.drive.realtime.Document for these changes.

Defaults to document_save_state_changed.

UNDO_REDO_STATE_CHANGED

string

 

The model canUndo/canRedo state changed. Listen on the gapi.drive.realtime.Model for these changes.

Defaults to undo_redo_state_changed.

ATTRIBUTE_CHANGED

string

 

A metadata attribute of the document changed. This is fired on changes to:

  • gapi.drive.realtime.Attribute.IS_READ_ONLY
Listen on the gapi.drive.realtime.Document for these changes.

Defaults to attribute_changed.

Methods

static
debug()

Opens the debugger application on the current page. The debugger shows all realtime documents that the page has loaded and is able to view, edit and debug all aspects of each realtime document.

static
enableTestMode()

Enables test mode for the Realtime API. After test mode is enabled, any file that is loaded will not be loaded from the server and no network requests will be made. Instead, the loaded data model will be empty and all changes will persist only until the page is reloaded. Event handlers will fire normally. This mode is intended for use in unit testing.

Deprecated
Use newInMemoryDocument instead.

static
load(fileId, onLoaded[, opt_initializerFn][, opt_errorFn])

Loads the Realtime document associated with fileId. If no Realtime document is associated with fileId, a new Realtime document associated with fileId will be created.

Parameters

Name Type Optional Description

fileId

string

 

The ID of the file to load.

onLoaded

function(non-null gapi.drive.realtime.Document)

 

A callback that will be called when the Realtime document is ready. The created or opened Realtime document object will be passed to this function.

opt_initializerFn

function(non-null gapi.drive.realtime.Model)

Yes

An optional initialization function that will be called before onLoaded only the first time that the document is loaded. The document's gapi.drive.realtime.Model object will be passed to this function.

opt_errorFn

function(non-null gapi.drive.realtime.Error)

Yes

An optional error handling function that will be called if an error occurs while the document is being loaded or edited. A gapi.drive.realtime.Error object describing the error will be passed to this function.

static
loadAppDataDocument(onLoaded[, opt_initializerFn][, opt_errorFn])

Loads a Realtime document that is appropriate for storing data that is application and user specific, such as preferences. For a given authenticated user and application, this document is guaranteed to be a singleton. If no such a document exists, it will be created in the authenticated application's hidden "Application Data" folder (if the "Application Data" folder does not exist it will be created as well).

To use this function, the OAuth token must have the drive.appdata scope. See https://developers.google.com/drive/appdata for more details on the Application Data folder.

Parameters

Name Type Optional Description

onLoaded

function(non-null gapi.drive.realtime.Document)

 

A callback that will be called when the realtime document is ready. The created or opened Realtime document object will be passed to this function.

opt_initializerFn

function(non-null gapi.drive.realtime.Model)

Yes

An optional initialization function that will be called before onLoaded only the first time that the document is loaded. The document's gapi.drive.realtime.Model object will be passed to this function.

opt_errorFn

function(non-null gapi.drive.realtime.Error)

Yes

An optional error handling function that will be called if an error occurs while the document is being loaded or edited. A gapi.drive.realtime.Error object describing the error will be passed to this function.

static
loadFromJson(json[, opt_errorFn]) → gapi.drive.realtime.Document

Loads an in-memory document from a json string. This document does not talk to the server and will only exist in memory for as long as the browser session exists.

Parameters

Name Type Optional Description

json

string

 

The json string of the document being imported.

Value can be null.

opt_errorFn

function(non-null gapi.drive.realtime.Error)

Yes

An optional error handling function that will be called if an error occurs while the document is being loaded or edited. A gapi.drive.realtime.Error object describing the error will be passed to this function.

Returns

gapi.drive.realtime.Document An in memory document with the model parsed from the json.

static
newInMemoryDocument([opt_onLoaded][, opt_initializerFn][, opt_errorFn]) → gapi.drive.realtime.Document

Creates a new file with fake network communications. This file will not talk to the server and will only exist in memory for as long as the browser session persists.

Parameters

Name Type Optional Description

opt_onLoaded

function(non-null gapi.drive.realtime.Document)

Yes

A callback that will be called when the realtime document is ready. The created or opened realtime document object will be passed to this function.

opt_initializerFn

function(non-null gapi.drive.realtime.Model)

Yes

An optional initialization function that will be called before onLoaded only the first time that the document is loaded. The document's gapi.drive.realtime.Model object will be passed to this function.

opt_errorFn

function(non-null gapi.drive.realtime.Error)

Yes

An optional error handling function that will be called if an error occurs while the document is being loaded or edited. A gapi.drive.realtime.Error object describing the error will be passed to this function.

Returns

gapi.drive.realtime.Document the new in memory document.

Send feedback about...

Realtime API