Getting Started With Collaboration Engine

Preparing the Application
Adding Collaboration Features
Running the Application

This guide shows the basic steps to set up Collaboration Engine in your Vaadin project and add the following collaboration features to a simple form:

Users can see the avatars of all the users who are using the application at the same time.
When someone enters a new value to a field, it is propagated to all users.
Users can see who is currently editing each field (a feature referred to as field highlight).

Important

Collaboration Engine requires a license file for use in production mode

Collaboration Engine follows a runtime billing model, based on the number of users using collaborative features in an application. Developers can start with a free 20 user / month license, or request a commercial license with a larger quota of end users. Visit the Setting up for production section of our documentation to learn how to download and install a license.

Preparing the Application

Setting Up a Vaadin Project

Download a new Vaadin project from https://start.vaadin.com/?preset=lts.

Installing Collaboration Engine

Collaboration Engine is a dependency that you add to your Vaadin project.

In the project’s pom.xml file, add Collaboration Engine as a dependency, under the <dependencies> tag in the root (and not the one under <dependencyManagement>):

<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>collaboration-engine</artifactId>
    <version>3.1.0</version>
</dependency>

Consult the releases page to find the version number of the latest release.

Enabling Server Push

Add @Push annotation on top of your root layout. This enables the server to propagate updates between clients in real time. By default, the root layout of the project is MainView.java.

@Push
public class MainView extends AppLayout {

Note	Manual push mode is not supported If you explicitly configure push to use `PushMode.MANUAL`, Collaboration Engine does not work, as it doesn’t manually invoke `UI.push()` to send the user interactions to the other connected users. Collaboration Engine works with any of the transport modes for push.

Adding Collaboration Features

This tutorial shows how to build a form where the users can edit the name and date of birth of a person.

Consider a Person bean class such as follows:

public static class Person {
    private String name;
    private LocalDate dateOfBirth;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public LocalDate getDateOfBirth() {
        return dateOfBirth;
    }

    public void setDateOfBirth(LocalDate dateOfBirth) {
        this.dateOfBirth = dateOfBirth;
    }
}

Creating a Simple View

To start writing the actual application, create a view with a text field and a date picker but not yet any collaborative functionality.

@Route(value = "ce/tutorial", layout = MainView.class)
public class TutorialView extends VerticalLayout {

    public TutorialView() {
        TextField nameField = new TextField("Name");
        DatePicker dateOfBirthField = new DatePicker("Date of birth");
        add(nameField, dateOfBirthField);
    }
}

Providing User Information

The UserInfo class represents a user of a collaborative application. It has properties such as name and image, which are used to display information about who else is currently viewing the same view or editing a field.

The user id should be the unique identifier of the currently logged-in user. Note that this tutorial uses an id based on the UI instance instead of a user-based id. This allows simulating multiple users by opening the view in multiple browser tabs.

// NOTE: In a real application, use the user id of the logged in user
// instead
String userId = System.identityHashCode(UI.getCurrent()) + "";
UserInfo localUser = new UserInfo(userId, "User " + userId);

The name is displayed to other users when editing a field, and the user’s avatar contains the abbreviation of the name (as the above example does not provide a user image).

UserInfo also has a colorIndex property. It defines which color is used in the user’s avatar as well as in the field highlight when editing a field. This property is generated automatically, so you don’t have to set it explicitly.

Adding User Avatars

To display the avatars of all users who are currently using the application, create a CollaborationAvatarGroup component.

CollaborationAvatarGroup avatarGroup = new CollaborationAvatarGroup(
        localUser, "tutorial");
addComponentAsFirst(avatarGroup);

First of all, the components needs the local user’s information (the UserInfo object which was created in the earlier example), to know how to render the user’s avatar.

As a second constructor argument, the component needs a topic ID. A topic can be compared to a chat room - it has an id that is unique in the context of the application. Participating members receive all updates made to any topic that they are participating in. Topic ids are freeform strings of your choice, such as “app” or “contract-126-address”. In this example, there is only one topic to work on, so we can use any hard-coded topic ID.

Note that if the application was expanded so that there would be a view for editing person entities, you’d need to have unique topic IDs for each entity. For example, you could have a topic ID "person/123", where "123" would be unique to each person. In that case, the same CollaborationAvatarGroup component could be reused for editing different persons by changing the topic with the setTopic() method.

Adding Field Collaboration

To enable collaboration with the text field and date picker components, we’ll use a class called CollaborationBinder. It extends the functionality of the Binder class, which binds values between Java beans and Vaadin field components. Read Binding Data to Forms to learn more about the binder.

To initialize a collaboration binder, we need to provide the type that will be edited, as well as the local user’s information. After initializing, we use the regular binder methods to bind the person object’s name property to our text field component, and the date of birth property to our date picker component.

Finally, we set the topic to connect to (the same as for CollaborationAvatarGroup) and a supplier for the initial bean value that will populate the fields when the first user connects to the topic. The supplier could load the editable item from a backend, but in this example we populate the fields with an empty Person object.

CollaborationBinder<Person> binder = new CollaborationBinder<>(
        Person.class, localUser);
binder.forField(nameField).bind("name");
binder.forField(dateOfBirthField).bind("dateOfBirth");
binder.setTopic("tutorial", () -> new Person());

The example takes care of propagating the field values among users, as well as displaying the currently focused user with the field highlight.

Running the Application

Follow instructions in the application’s README.md file to start the application.
Open http://localhost:8080/ in multiple browser tabs and test the application: notice the avatars, focus the fields and notice the field highlight, enter new values and notice how the fields update in the other tabs.

768E6425-1233-42EB-85C5-439E71485AD5

Docs