Skip to main content

Events

The collaboration client has a set of events you can subscribe to. This helps you keep your app's UI in sync with any backend changes that happen.

There are two different ways to subscribe to events - global events and entity specific events

Global events#

Global events are events that are triggered any time any action takes place in the collaboration flow. These events get fired any time any entity a user belongs to is modified, created, or removed.

Global events can be subscribed to via the EventManager.subscribe function.

import { CollabClient } from '@pdftron/collab-client'
const client = new CollabClient({ ...options });
client.EventManager.subscribe('eventName', () => {
// Handle event here
});

Below is a list of all global events.

documentLoaded#

Triggered whenever a new document is loaded/displayed in the viewer.

Callback function is passed the Document instance that was loaded.

client.EventManager.subscribe('documentLoaded', (document) => {
console.log(`Document ${document.id} was loaded`)
});

documentChanged#

Triggered any time a document instance changed. This includes:

  • Any time a new user joins the document, or a user connects/disconnects from the document
  • Any time an annotation belonging to the document is added/edited/removed/marked as read
  • Any time the document name or 'isPublic' flag is updated

Callback function is passed the Document instance that was changed.

client.EventManager.subscribe('documentChanged', (document) => {
console.log(`Document ${document.id} was changed`)
});

documentDeleted#

Triggered when a document is deleted.

Callback is passed the ID of the document that was deleted.

client.EventManager.subscribe('documentDeleted', (id) => {
console.log(`Document ${id} was deleted`)
});

annotationAdded#

Triggered when an annotation is added to the currently opened document.

Callback is passed the instance of Annotation that was created.

client.EventManager.subscribe('annotationAdded', (annotation) => {
console.log(`Annotation ${annotation.id} was created`)
});

annotationChanged#

Triggered whenever an annotation is changed on the currently opened document. This event is not triggered when an annotation is marked as read.

Callback is passed the instance of Annotation that was changed.

client.EventManager.subscribe('annotationChanged', (annotation) => {
console.log(`Annotation ${annotation.id} was changed`)
});

annotationMarkedAsRead#

Triggered whenever an annotation is marked as read by the current user.

Callback is passed the instance of Annotation that was read.

client.EventManager.subscribe('annotationMarkedAsRead', (annotation) => {
console.log(`Annotation ${annotation.id} was marked as read`)
});

annotationDeleted#

Triggered whenever an annotation is deleted on the currently opened document.

Callback is passed the ID of the annotation that was deleted.

client.EventManager.subscribe('annotationDeleted', (id) => {
console.log(`Annotation ${id} was deleted`)
});

snapshotAdded#

Triggered whenever a snapshot of the currently opened document is created.

Callback is passed an instance of the Snapshot that was created.

client.EventManager.subscribe('snapshotAdded', (snapshot) => {
console.log(`Snapshot ${snapshot.name} was created`)
});

snapshotChanged#

Triggered whenever a snapshot of the currently opened document is edited.

Callback is passed an instance of the Snapshot that was edited.

client.EventManager.subscribe('snapshotChanged', (snapshot) => {
console.log(`Snapshot ${snapshot.name} was edited`)
});

snapshotDeleted#

Triggered whenever a snapshot of the currently opened document is deleted.

Callback is passed the ID of the snapshot that was deleted.

client.EventManager.subscribe('snapshotDeleted', (id) => {
console.log(`Snapshot ${id} was deleted`)
});

snapshotRestored#

Triggered whenever the currently opened document is restored to a snapshot.

Callback is passed an instance of the Snapshot that was restored. A second sync parameter is also passed, more info on that here.

client.EventManager.subscribe('snapshotRestored', (snapshot, sync) => {
console.log(`Snapshot ${snapshot.id} was restored`)
});

userLoggedIn#

Triggered whenever a user is logged in via loginAnonymously, loginWithPassword, or loginWithToken.

Callback is passed an instance of User, representing the user that was logged in.

client.EventManager.subscribe('userLoggedIn', (user) => {
console.log(`User ${user.id} was logged in`)
});

inviteReceived#

Triggered whenever the currently logged in user receives an invite to a document.

Callback is passed the Document that the user was invited to.

client.EventManager.subscribe('inviteReceived', (document) => {
console.log(`User was invited to ${document.name}`)
});

mentionAdded#

Triggered whenever the the user is mentioned in an annotation.

Callback is passed an instance of Mention.

client.EventManager.subscribe('mentionAdded', (mention) => {
console.log(`User was mentioned in ${mention.annotation.document.name}`)
});

mentionDeleted#

Triggered whenever an annotation the user is mentioned in is deleted.

Callback is passed the ID of the mention that was deleted.

client.EventManager.subscribe('mentionDeleted', (id) => {
console.log(`Mention ${id} was deleted`)
});

enteredPreviewMode#

Triggered whenever the viewer goes into preview mode. Preview mode is entered when a user is viewing a snapshot.

Callback is passed an instance of Snapshot that is being previewed.

client.EventManager.subscribe('enteredPreviewMode', (snapshot) => {
console.log(`Previewing ${snapshot.name}`)
});

exitedPreviewMode#

Triggered whenever the viewer leaves preview mode.

Callback is passed an instance of Snapshot that was being previewed.

client.EventManager.subscribe('exitedPreviewMode', (snapshot) => {
console.log(`No longer previewing ${snapshot.name}`)
});

annotationSizeError#

Triggered when maxAnnotationSize is set and an annotation is created that is larger than the threshold.

Callback is passed the instance of Annotation that was created.

client.EventManager.subscribe('annotationSizeError', (annotation) => {
console.log(`Annotation ${annotation.id} is too large`)
});

connectedUsersChanged#

Only triggered when the connected users feature is turned on.

This event is triggered when:

  • A user connects or disconnects to the currently opened document
  • A user changes the page they are currently viewing

Callback is passed three parameters:

  • users (User[]) A list of users that are currently viewing the document.
  • document (Document) The document the users connected to.
  • action ("ADD", "DELETE", or "EDIT) The action that triggered this event
client.EventManager.subscribe('connectedUsersChanged', (users, document) => {
for(const user of users) {
console.log(`${user.userName} is viewing page ${user.pageNumber} of ${document.name}`)
}
});

scrollSyncSessionsChanged#

Triggered whenever a scroll sync session is created or destroyed.

Callback is passed an array of ScrollSyncSession that are available to join.

client.EventManager.subscribe('scrollSyncSessionsChanged', (sessions) => {
for(const session of sessions) {
console.log(`${session.leader.userName} is leading a scroll sync session`)
}
});

joinedScrollSyncSession#

Triggered whenever a user joins a scroll sync session.

Callback is passed the ScrollSyncSession that the user joined.

client.EventManager.subscribe('joinedScrollSyncSession', (session) => {
console.log(`User joined scroll sync session ${session.id}`)
});

leftScrollSyncSession#

Triggered whenever a user leaves a scroll sync session.

Callback is passed the ID of the session that was left.

client.EventManager.subscribe('leftScrollSyncSession', (sessionId) => {
console.log(`User left scroll sync session ${sessionId}`)
});

annotationPermissionError#

Triggered when a user tried to add, edit, delete, or read an annotation without proper permissions.

Callback is passed two arguments:

  • action (string) The action the user tried to perform. One of: 'ADD' | 'DELETE' | 'MODIFY' | 'READ'
  • annotation (Annotation - optional) If available, the annotation instance they tried to alter is provided.
client.EventManager.subscribe('annotationPermissionError', (action, annotation) => {
switch(action) {
case 'ADD':
console.log(`User attempted to create annotation without permissions`);
break;
case 'DELETE':
console.log(`User attempted to delete annotation without permissions`);
break;
case 'MODIFY':
console.log(`User attempted to modify annotation without permissions`);
break;
case 'READ':
console.log(`User attempted to read annotation without permissions`);
break;
}
});

documentPermissionError#

Triggered when a user tried to add, edit, delete, read, or invite to a document without proper permissions.

Callback is passed two arguments:

  • action (string) The action the user tried to perform. One of: 'ADD' | 'DELETE' | 'MODIFY' | 'READ' | 'INVITE'
  • document (Document - optional) If available, the document instance they tried to alter is provided.
client.EventManager.subscribe('documentPermissionError', (action, annotation) => {
switch(action) {
case 'ADD':
console.log(`User attempted to create document without permissions`);
break;
case 'DELETE':
console.log(`User attempted to delete document without permissions`);
break;
case 'MODIFY':
console.log(`User attempted to modify document without permissions`);
break;
case 'READ':
console.log(`User attempted to read document without permissions`);
break;
case 'INVITE':
console.log(`User attempted to invite a user to a document without permission`);
break;
}
});

snapshotPermissionError#

Triggered when a user tried to add, edit, delete, read, or restore a snapshot without proper permissions.

Callback is passed two arguments:

  • action (string) The action the user tried to perform. One of: 'ADD' | 'DELETE' | 'MODIFY' | 'READ' | 'RESTORE'
  • snapshot (Snapshot - optional) If available, the snapshot instance they tried to alter is provided.
client.EventManager.subscribe('documentPermissionError', (action, annotation) => {
switch(action) {
case 'ADD':
console.log(`User attempted to create snapshot without permissions`);
break;
case 'DELETE':
console.log(`User attempted to delete snapshot without permissions`);
break;
case 'MODIFY':
console.log(`User attempted to modify snapshot without permissions`);
break;
case 'READ':
console.log(`User attempted to read snapshot without permissions`);
break;
case 'RESTORE':
console.log(`User attempted to restore a snapshot without permission`);
break;
}
});

Entity Specific Events#

In addition to the global events documented above, you can also subscribe to events on an entity level.

Call the subscribe function on the entity to subscribe to the events.

Document events#

Instances of Document triggers the following events:

  • onChange Triggered when the document instance changes. Callback function is passed the instance of the document
  • onDestroy Triggered when the Document is deleted. Callback function accepts the ID of the deleted document
  • snapshotAdded Triggered when a snapshot of this document is created. Callback function accepts the Snapshot that was created.
  • connectedUsersChanged Triggered when a user connects, disconnects, or views a new page of this document. Callback function accepts a list of users that are connected, and the action that triggered the event.
const user = await client.loginAnonymously("Joe")
const document = await user.getDocument('123')
document.subscribe('onChange', (document) => {
console.log(`Document ${document.name} was edited`);
})
document.subscribe('onDestroy', (id) => {
console.log(`Document ${id} was destroyed`);
})
document.subscribe('snapshotAdded', (snapshot) => {
console.log(`Snapshot ${snapshot.name} of ${document.name} was created`);
})
document.subscribe('connectedUsersChanged', (users) => {
for(const user of users) {
console.log(`${user.userName} is viewing page ${user.pageNumber} of ${document.name}`)
}
})

Annotation events#

Instances of Annotation triggers the following events:

  • markedAsRead Triggered when the annotation is marked as read. Callback function accepts the Annotation as a parameter.
  • onChange Triggered when the annotation instance changes. Callback function is passed the instance of the annotation
  • onDestroy Triggered when the Annotation is deleted. Callback function accepts the ID of the deleted annotation
const user = await client.loginAnonymously("Joe")
const document = await user.getDocument('123')
const annotations = await document.getAnnotations();
for(const annotation of annotations) {
annotation.subscribe('markedAsRead', (annot) => {
console.log(`Annotation ${annot.id} was marked as read`)
})
annotation.subscribe('onDestroy', (id) => {
console.log(`Annotation ${id} was destroyed`)
})
annotation.subscribe('onChange', (annot) => {
console.log(`Annotation ${annot.id} was changed`)
})
}

Mention events#

Instances of Mention triggers the following events:

  • markedAsRead Triggered when the Mention is marked as read. Callback function accepts the Mention as a parameter.
  • onChange Triggered when the Mention instance changes. Callback function is passed the instance of the mention.
  • onDestroy Triggered when the Mention is deleted. Callback function accepts the ID of the deleted mention
client.EventManager.subscribe('mentionAdded', (mention) => {
mention.subscribe('markedAsRead', (mention) => {
console.log(`Mention ${mention.id} was marked as read`);
})
mention.subscribe('onChange', (mention) => {
console.log(`Mention ${mention.id} was changed`);
})
mention.subscribe('onDestroy', (id) => {
console.log(`Mention ${id} was deleted`);
})
});

Snapshot events#

Instances of Snapshot triggers the following events:

  • restored Triggered when the Snapshot is restored. Callback function accepts the Snapshot as a parameter.
  • onChange Triggered when the Snapshot instance changes. Callback function is passed the instance of the snapshot.
  • onDestroy Triggered when the Snapshot is deleted. Callback function accepts the ID of the deleted snapshot.
const user = await client.loginAnonymously("Joe")
const document = await user.getDocument('123');
const mentions = await document.getMentions()
for(const mention of mentions) {
mention.subscribe('restored', (snapshot) => {
console.log(`Snapshot ${snapshot.name} was restored`)
})
mention.subscribe('onChange', (snapshot) => {
console.log(`Snapshot ${snapshot.name} was changed`)
})
mention.subscribe('onDestroy', (id) => {
console.log(`Snapshot ${id} was destroyed`)
})
}

Unsubscribing from events#

Every subscribe function returns a function that can be called to unsubscribe from the event.

const unsubscribe = client.EventManager.subscribe('annotationAdded', (annotation) => {
console.log(`Annotation ${annotation.id} was created`)
});
// To unsubscribe
unsubscribe();

Listening to an event only once#

To immediately unsubscribe from an event as soon as its triggered, call the unsubscribe function inside the callback function.

const unsubscribe = client.EventManager.subscribe('annotationAdded', (annotation) => {
console.log(`Annotation ${annotation.id} was created`);
unsubscribe();
});