Mentions

To make the realtime collaboration flow even better, WebViewer provides APIs that can be used to capture mentions in the notes panel. The mentions contain the data that can be sent to a server, and notify other users in the same collaboration session.

The first thing to enable the mentions feature in the viewer is to import user data using setUserData.

WebViewer(...)
  .then(instance => {
    const userData = [
      {
        value: 'John Doe', // required property
        email: 'johndoe@gmail.com', // optional property
        // you can have more optional properties here, and they will be passed back in the mentionChanged event callback
      },
      {
        value: 'Jane Doe',
        email: 'janedoe@gmail.com'
      },
    ];

    instance.UI.mentions.setUserData(userData);
  });

Instead of providing a hardcoded list and setting user data, you can provide a callback function that will look up the users based on the user entry.

WebViewer(...)
  .then(function(instance) {
    instance.mentions.setMentionLookupCallback(async (userData, searchTerm) => {
      const matches = [];
      userData.forEach((user) => {
        if (user.name === 'John Doe') {
          matches.push(user);
        }
      });
      return matches;
    });
  });

The instance.UI.mentions instance exposes a mentionChanged event that works in a very similar way as annotationChanged. This event will be triggered whenever a mention is added, modified, or deleted from the notes panel.

WebViewer(...)
  .then(instance => {
    instance.UI.mentions.on('mentionChanged', (mentions, action) => {
      if (action === 'add') {
        // a new mention was just added to a comment
      }

      if (action === 'modify') {
        // the mentioned names in a comment didn't change, but the surrounding text was changed
      }

      if (action === 'delete') {
        // a mention was just deleted from a comment
      }

      console.log(mentions);
      // [
      //   {
      //     value: 'John Doe',
      //     email: 'johndoe@gmail.com',
      //     annotId: '...', // the annotation to which the mention belongs to
      //   },
      //   {
      //     value: 'Jane Doe',
      //     email: 'janedoe@gmail.com'
      //     annotId: '...',
      //   },
      // ]
    })
  });

By default, a user name won't be considered as a mention if it is followed by any characters except a space, but this setting can be changed by using the setAllowedTrailingCharacters API

WebViewer(...)
  .then(instance => {
    instance.UI.mentions.setUserData([
      {
        value: 'John Doe',
      },
    ]);
     // this is considered as a mention, because `@John Doe` is at the end of the string
    'Hello, @John Doe'
     // this is considered as a mention, because `@John Doe` is followed by a space
    'Hello, @John Doe How are you?'
     // this is NOT considered as a mention, because `@John Doe` is followed by a comma
    '@John Doe, Hello!'
     instance.UI.mentions.setAllowedTrailingCharacters([' ', ',']);
     // this is now considered as a mention, because comma is an allowed trailing character
    '@John Doe, Hello!'
  });