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.

Import user data into the viewer

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

JavaScript (SDK v8.0+)

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

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

JavaScript (SDK v7.0+)

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

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

Provide a callback function to lookup users

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.

JavaScript

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;
    });
  });

Listen to the mentionChanged event to capture mentions in a comment

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.

JavaScript (SDK v8.0+)

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: '[e-mail]',
      //     annotId: '...', // the annotation to which the mention belongs to
      //   },
      //   {
      //     value: 'Jane Doe',
      //     email: '[e-mail]'
      //     annotId: '...',
      //   },
      // ]
    })
  });

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.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: '[e-mail]',
      //     annotId: '...', // the annotation to which the mention belongs to
      //   },
      //   {
      //     value: 'Jane Doe',
      //     email: '[e-mail]'
      //     annotId: '...',
      //   },
      // ]
    })
  });

Set the allowed trailing characters

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

JavaScript (SDK v8.0+)

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!'
  });

JavaScript (SDK v7.0+)

WebViewer(...)
  .then(instance => {
    instance.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.mentions.setAllowedTrailingCharacters([' ', ',']);
     // this is now considered as a mention, because comma is an allowed trailing character
    '@John Doe, Hello!'
  });