Presence Badges

TextSync supports the concept of presence indicators in the shape of "badges". Each collaborator connected to the document is represented by a badge displayed just above the text editor. Badges will display a collaborator's name and image from Gravatar. If any of these details aren't supplied, they will be auto-generated.

Usage

Enabling / Disabling Presence Badges

Presence badges are enabled by default. If you wish to disable them, you can set collaboratorBadges to false when instantiating the TextSync instance.

1
2
3
4
textSyncInstance.createEditor({
  /* ... other config ... */
  collaboratorBadges: false
});

Receiving Callbacks

If you wish to perform your own actions on collaborator join and leave events, you can register callbacks. There are two callbacks which may be registered.

  • onCollaboratorsJoined is fired when one of more users join the editing session.
  • onCollaboratorsLeft is fired when one of more users leave the editing session.
1
2
3
4
5
6
7
8
9
10
11
12
13
textSyncInstance.createEditor({
  /* ... other config ... */
  onCollaboratorsJoined: (users) => {
    for (const user of users) {
      console.info("New user arrived:", user);
    }
  },
  onCollaboratorsLeft: (users) => {
    for (const user of users) {
      console.info("Existing user left:", user);
    }
  }
});

The callbacks fire regardless of the state of the collaboratorBadgesoption.

Data example

See the reference for a description of the arguments provided to the callbacks. Some illustrative examples are provided here.

onCollaboratorsJoined:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
  {
    name: 'Grace Hopper',
    avatar: 'http://gravatar-image.com/grace-hopper',
    siteId: 91206,
    timestamp: '1991-06-08T12:00:000.007Ya102079Z'
  },
  {
    name: 'Tim Berners-Lee',
    avatar: 'http://gravatar-image.com/tim-berners-lee',
    siteId: 80655,
    timestamp: '1977-07-05T12:54:20.007102079Z'
  }
]

onCollaboratorsLeft:

1
2
3
4
5
6
[
  {
    siteId: 959595,
    timestamp: '2000-07-11T12:54:20.007102079Z'
  }
]

When a TextSync document first loads, onCollaboratorsJoined will be invoked to provide information on the users already in the session.

Customisation

There are two options to visually customise the badges:

Override Existing CSS

Available CSS classes:

  • .tsync-presence-container - container div along the top of the editor toolbar

  • .tsync-badge-wrapper - div around the badge

  • .tsync-badge - the badge

  • .tsync-tooltip - the name tooltip above the badge (appears on hover)

Badge DOM tree

1
2
3
4
5
6
7
div.tsync-presence-container
 |
 +-div.tsync-badge-wrapper
    |
    +-div.tsync-badge
    |
    +-span.tsync-tooltip

Build Your Own Badges

If you prefer, you can switch off the default badges and use the data from the callback to control your own presentation of the current collaborators.

Did you find this document useful?

We are always striving to create the most accurate and informative docs as possible. If there is something especially wrong (or right) here then please let us know.