Setting up listen/trigger events for real-time collaboration in the client

In realtime collaboration, a client will merely act as a listener or trigger for events upon data creation/modification/deletion updating the current user or sending updates to other users.

1. Create a JavaScript file and name it main.js.
2. Instantiate WebViewer on a DOM element, making sure to wrap this code and any further code inside $(document).ready(). Initial document can be any PDF or XOD file.

JavaScript

$(document).ready(() => {
  WebViewer({
    path: "lib",
    initialDoc: "MY_INITIAL_DOC.pdf",
    documentId: "unique-id-for-this-document"
  }, document.getElementById('viewer'))
    .then(instance => {
      // do something...
    });
});

1. Create the server.

JavaScript

const server = new Server();

1. Bind a callback function to DocumentViewer.documentLoaded event.

JavaScript (SDK v8.0+)

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager } = instance.Core;

    documentViewer.addEventListener('documentLoaded', () => {
      // Code in later steps will be added here...
    });
  })

WebViewerInstance Core AnnotationManager DocumentViewer#documentLoaded

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    const { docViewer, annotManager } = instance;

    docViewer.on('documentLoaded', () => {
      // Code in later steps will be added here...
    });
  })

WebViewerInstance AnnotationManager DocumentViewer#documentLoaded

1. Inside the documentLoaded callback, bind another callback function to server's onAuthStateChanged event that is defined in server.js. A firebase.User object will be passed as a parameter.
2. If the user is not logged in we'll call the sign-in method that we defined in server.js.
3. If the user is logged in, we'll store their uid in the authorId variable, which will be used for client-side annotation permission checks.
4. We call server.checkAuthor with parameters authorId, openReturningUserPopup function and openNewUserPopup function. These functions will be discussed in next steps.
5. Then, we will send author information to the server and bind callback functions to annotation events. Details of the callback functions will be discussed in next steps.

JavaScript

let authorId = null;

server.bind('onAuthStateChanged', user => {
  // User is logged in
  if (user) {
    // Using uid property from Firebase Database as an author id
    // It is also used as a reference for server-side permission
    authorId = user.uid;
    // Check if user exists, and call appropriate callback functions
    server.checkAuthor(authorId, openReturningAuthorPopup, openNewAuthorPopup);
    // Bind server-side data events to callback functions
    // When loaded for the first time, onAnnotationCreated event will be triggered for all database entries
    server.bind('onAnnotationCreated', onAnnotationCreated);
    server.bind('onAnnotationUpdated', onAnnotationUpdated);
    server.bind('onAnnotationDeleted', onAnnotationDeleted);
  }
  // User is not logged in
  else {
    // Login
    server.signInAnonymously();
  }
});

1. Define callback functions for annotationCreated, annotationUpdated and server.annotationDeleted events. A data object will be passed as a parameter. For more information, refer to firebase.database.DataSnapshot.
2. openReturningAuthorPopup is a callback function triggered when author data is found in the database. It will receive authorName as a parameter, and open a popup with the authorName as a visual feedback.
3. openNewAuthorPopup is a callback function triggered when author data is not found. Then we will open a popup for a new author to setup an author name.
4. updateAuthor is a function which will set author name in both client and server using annotationManager.setCurrentUser and server.updateAuthor, respectively.

JavaScript (SDK v8.0+)

function openReturningAuthorPopup(authorName) {
  // The author name will be used for both WebViewer and annotations in PDF
  annotationManager.setCurrentUser(authorName);
  // Open popup for the returning author
  window.alert(`Welcome back ${authorName}`);
}

function openNewAuthorPopup() {
  // Open prompt for a new author
  const name = window.prompt('Welcome! Tell us your name :)');
  if (name) {
    updateAuthor(name);
  }
}

function updateAuthor(authorName) {
  // The author name will be used for both WebViewer and annotations in PDF
  annotationManager.setCurrentUser(authorName);
  // Create/update author information in the server
  server.updateAuthor(authorId, { authorName });
}

AnnotationManager.setCurrentUser

JavaScript (SDK v6.0+)

function openReturningAuthorPopup(authorName) {
  // The author name will be used for both WebViewer and annotations in PDF
  annotManager.setCurrentUser(authorName);
  // Open popup for the returning author
  window.alert(`Welcome back ${authorName}`);
}

function openNewAuthorPopup() {
  // Open prompt for a new author
  const name = window.prompt('Welcome! Tell us your name :)');
  if (name) {
    updateAuthor(name);
  }
}

function updateAuthor(authorName) {
  // The author name will be used for both WebViewer and annotations in PDF
  annotManager.setCurrentUser(authorName);
  // Create/update author information in the server
  server.updateAuthor(authorId, { authorName });
}

AnnotationManager.setCurrentUser

1. Define callback functions for annotationCreated, annotationUpdated and server.annotationDeleted events. A data object will be passed as a parameter. For more information, refer to firebase.database.DataSnapshot.
2. onAnnotationCreated and onAnnotationUpdated have the exact same behavior in this guide. They will use annotManager.importAnnotCommand to update the viewer with the xfdf change.
3. We also set a custom field authorId for the updated annotation to control client-side permission of the created/updated annotation.
4. onAnnotationDelete creates a delete command string from the annotation's id and is simply able to call importAnnotCommand on it.

JavaScript (SDK v8.0+)

function onAnnotationCreated(data) {
  // data.val() returns the value of server data in any type. In this case, it
  // would be an object with properties authorId and xfdf.
  const annotation = annotationManager.importAnnotCommand(data.val().xfdf)[0];
  annotation.authorId = data.val().authorId;
  annotationManager.redrawAnnotation(annotation);
  myWebViewer.getInstance().UI.fireEvent('updateAnnotationPermission', [annotation]);
}

function onAnnotationUpdated(data) {
  // Import the annotation based on xfdf command
  const annotation = "m": true,.importAnnotCommand(data.val().xfdf)[0];
  // Set a custom field authorId to be used in client-side permission check
  annotation.authorId = data.val().authorId;
  annotationManager.redrawAnnotation(annotation);
}

function onAnnotationDeleted(data) {
  // data.key would return annotationId since our server method is designed as
  // annotationsRef.child(annotationId).set(annotationData)
  const command = '<delete><id>' + data.key + '</id></delete>';
  annotationManager.importAnnotCommand(command);
}

AnnotationManager.redrawAnnotation AnnotationManager.importAnnotCommand

JavaScript (SDK v6.0+)

function onAnnotationCreated(data) {
  // data.val() returns the value of server data in any type. In this case, it
  // would be an object with properties authorId and xfdf.
  const annotation = annotManager.importAnnotCommand(data.val().xfdf)[0];
  annotation.authorId = data.val().authorId;
  annotManager.redrawAnnotation(annotation);
  myWebViewer.getInstance().fireEvent('updateAnnotationPermission', [annotation]);
}

function onAnnotationUpdated(data) {
  // Import the annotation based on xfdf command
  const annotation = annotManager.importAnnotCommand(data.val().xfdf)[0];
  // Set a custom field authorId to be used in client-side permission check
  annotation.authorId = data.val().authorId;
  annotManager.redrawAnnotation(annotation);
}

function onAnnotationDeleted(data) {
  // data.key would return annotationId since our server method is designed as
  // annotationsRef.child(annotationId).set(annotationData)
  const command = '<delete><id>' + data.key + '</id></delete>';
  annotManager.importAnnotCommand(command);
}

AnnotationManager.redrawAnnotation AnnotationManager.importAnnotCommand

1. After server callback functions are bound, we'll also bind a function to annotManager.annotationChanged event.
2. First parameter, e, has a property imported that is set to true by default for annotations internal to the document and annotations added by importAnnotCommand or importAnnotations.
3. Then we iterate through the annotations that are changed, which is passed as the second parameter.
4. Third parameter, type, defines which action it was. In this guide, we'll have the same behavior for both add and modify action types.
5. When annotations are added and modified, we will call server.createAnnotation or server.updateAnnotation which needs four variables: annotationId, authorId, parentAuthorId and xfdf.
6. annotationId can be retrieved from annotation.Id.
7. authorId was saved as a reference when user logged in.
8. parentAuthorId refers to the parent annotation's author id, if any. This will be used to distinguish replies, and will be referenced in server-side permission. Thus, we retrieve authorId of the parent annotation by using annotation.InReplyTo, which returns the annotation id of the parent annotation.
9. xfdf can be retrieved using annotationManager.getAnnotCommand. It will get an XML string specifying the added, modified and deleted annotations, which can be used to import the annotation using annotationManager.importAnnotCommand in server data callback functions.

JavaScript (SDK v8.0+)

annotationManager.addEventListener('annotationChanged', (annotations, type, { imported }) => {
  if (imported) {
    return;
  }
  annotations.forEach(annotation => {
    if (type === 'add') {
      const xfdf = annotationManager.getAnnotCommand();
      let parentAuthorId = null;
      if (annotation.InReplyTo) {
        parentAuthorId = annotationManager.getAnnotationById(annotation.InReplyTo).authorId || 'default';
      }
      server.createAnnotation(annotation.Id, {
        authorId: authorId,
        parentAuthorId: parentAuthorId,
        xfdf: xfdf
      });
    } else if (type === 'modify'){
      const xfdf = annotationManager.getAnnotCommand();
      let parentAuthorId = null;
      if (annotation.InReplyTo) {
        parentAuthorId = annotationManager.getAnnotationById(annotation.InReplyTo).authorId || 'default';
      }
      server.updateAnnotation(annotation.Id, {
        authorId: authorId,
        parentAuthorId: parentAuthorId,
        xfdf: xfdf
      });
    } else if (type === 'delete') {
      server.deleteAnnotation(annotation.Id);
    }
  });
});

JavaScript (SDK v6.0+)

annotManager.on('annotationChanged', (annotations, type, { imported }) => {
  if (imported) {
    return;
  }
  annotations.forEach(annotation => {
    if (type === 'add') {
      const xfdf = annotManager.getAnnotCommand();
      let parentAuthorId = null;
      if (annotation.InReplyTo) {
        parentAuthorId = annotManager.getAnnotationById(annotation.InReplyTo).authorId || 'default';
      }
      server.createAnnotation(annotation.Id, {
        authorId: authorId,
        parentAuthorId: parentAuthorId,
        xfdf: xfdf
      });
    } else if (type === 'modify'){
      const xfdf = annotManager.getAnnotCommand();
      let parentAuthorId = null;
      if (annotation.InReplyTo) {
        parentAuthorId = annotManager.getAnnotationById(annotation.InReplyTo).authorId || 'default';
      }
      server.updateAnnotation(annotation.Id, {
        authorId: authorId,
        parentAuthorId: parentAuthorId,
        xfdf: xfdf
      });
    } else if (type === 'delete') {
      server.deleteAnnotation(annotation.Id);
    }
  });
});

1. Lastly, we will overwrite the client-side permission checking function using annotManager.setPermissionCheckCallback. The default is set to compare the authorName. Instead, we will compare authorId created from the server.

JavaScript (SDK v8.0+)

annotationManager.setPermissionCheckCallback((author, annotation) => annotation.authorId === authorId);

JavaScript (SDK v6.0+)

annotManager.setPermissionCheckCallback((author, annotation) => annotation.authorId === authorId);