Collaboration Avatar Group

Getting Started
Configuring Avatars
Scoping Avatars with Topics
Displaying User’s Avatar

Collaboration Kit includes an extension to Vaadin’s AvatarGroup component, called CollaborationAvatarGroup. It updates automatically the displayed avatars based on the users who are currently present in a view. You can see an example of this in the screenshot here:

CollaborationAvatarGroup Example

When CollaborationAvatarGroup is attached, the user’s avatar is added to the group for all users. When it becomes detached — typically because of navigating to another view or closing the browser tab — the user’s avatar is removed.

Getting Started

To get started with CollaborationAvatarGroup, provide the UserInfo that represents the current active user and the unique identifier of the topic on which to connect. Then add the component to your view:

User userEntity = userService.getCurrentUser();
UserInfo userInfo = new UserInfo(userEntity.getId());

CollaborationAvatarGroup avatarGroup = new CollaborationAvatarGroup(
        userInfo, "ensuranceClaims");
add(avatarGroup);

Note

Unavailable Classes

The User and UserService classes aren’t available in Collaboration Kit. They’re shown in the example here as classes that might exist in an application for user management. The topic identifier, "ensuranceClaims" can be any string to identify what the users are collaborating on.

After running the application and opening the view, you should see your own avatar. Try opening the view in another browser tab at the same time, as a separate user entity — distinguished by the identifier provided to UserInfo. Both tabs should display the avatars of both users.

Configuring Avatars

Avatars are configured mostly through the UserInfo object. When no other information is available, the avatar displays a generic icon.

Name & Abbreviation

When a user name is provided via UserInfo::setName, an abbreviation is generated automatically and displayed in the avatar. To display a custom abbreviation, UserInfo::setAbbreviation can be used.

Hovering the mouse over the avatar displays the full name like a tooltip. The name is also presented in the overflow drop-down. When all the avatars won’t fit into the group, the last avatar — which has text such as "+3" — can be clicked to show the overflown avatars and their names in a drop-down list.

Images from URL

To display an image inside the avatar, you have two options. First, if the image is hosted somewhere, you can provide its URL as a string with UserInfo::setImage. Setting an image, though, isn’t a replacement for the name property. When an image is provided, name is still displayed in a tooltip on hover and in the overflow drop-down list.

Images from Backend

The way to load images from a database into components such as Image or Avatar, is to use StreamResources. CollaborationAvatarGroup supports stream resources with the setImageProvider method. It takes a function that generates StreamResources for users based on their UserInfo.

For example, if the user entity contains the image as a byte array, you can create a StreamResource that loads those bytes and let the framework take care of hosting the image like so:

avatarGroup.setImageProvider(userInfo -> {
    StreamResource streamResource = new StreamResource(
            "avatar_" + userInfo.getId(), () -> {
                User userEntity = userService
                        .findById(userInfo.getId());
                byte[] imageBytes = userEntity.getImage();
                return new ByteArrayInputStream(imageBytes);
            });
    streamResource.setContentType("image/png");
    return streamResource;
});

Regarding this image provider pattern, StreamResource isn’t serializable as JSON. As a result, it can’t be included in UserInfo or sent back and forth through Collaboration Kit.

Scoping Avatars with Topics

Using different topic identifiers in the setTopic method allows defining which users can see each other’s avatars in the group. If everyone in the view should see each other in the same avatar group, the topic identifier can be any constant string. All that matters is that it doesn’t potentially conflict with other avatar groups in other views. The view name could be used as the topic identifier in this case.

The same CollaborationAvatarGroup component is often re-used for different topics. An example of this would be a form view that’s used for editing different entities, where you want to see only the avatars of the users who are editing the same entity. In this case, the topic identifier should be specific to the edited entity.

The example here is related to a form for editing different Person entities. When selecting the entity to edit, the topic could be updated as follows:

private void personSelected(long personId) {
    avatarGroup.setTopic("person/" + personId);
}

If the form uses CollaborationBinder, it makes sense to use the same topic identifier for the binder and the avatar group.

Setting the topic to null disables the connection to Collaboration Kit. The group won’t display any avatars until a non-null topic identifier is provided.

Displaying User’s Avatar

It’s a common design pattern to display the user’s avatar separately from the other avatars. To achieve this, you can exclude the user’s avatar from the CollaborationAvatarGroup and create a separate Avatar component. You can then add it anywhere in the view, independent of the other avatars.

// Exclude own avatar from the group:
avatarGroup.setOwnAvatarVisible(false);

// Create another component for own avatar:
Avatar ownAvatar = new Avatar();
ownAvatar.setName(userEntity.getName());
ownAvatar.setImage(userEntity.getImageUrl());

add(ownAvatar);

You can set the same name, abbreviation, and image properties as contained in the UserInfo. To load the image from a backend, you can pass a StreamResource directly to the Avatar::setImageResource method.

2374106C-8FD4-4AED-B1F3-5045FFF81F55

Docs