Getting Started with Collaboration Kit

Preparing the Application
Adding Collaboration Features
Running the Application

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

Users can see the avatars of all who are using the application;
When someone enters a new value to a field, it’s propagated to all users; and
Users can see who is editing each field (i.e., field highlight).

Important

License Required for Production

Collaboration Kit follows a runtime billing model, based on the number of users using collaborative features in an application. Developers can start with a free 50-users-per-month license, or request a commercial license with a larger quota of end users. See the Production Configuration section to learn how to download and install a license.

Preparing the Application

First, you’ll have to set up a Vaadin Project. You can download a new Vaadin project from https://start.vaadin.com/?preset=collaboration.

Enabling Server Push

Add @Push annotation on top of your AppShellConfigurator. This enables the server to propagate updates between clients in real time. In Spring applications, you can implement the interface in your main application class.

@Push
@SpringBootApplication
public class Application extends SpringBootServletInitializer implements AppShellConfigurator {

    public static void main(String... args) {
        SpringApplication.run(Application.class, args);
    }
}

Note	Manual Push Mode Not Supported If you configure push to use `PushMode.MANUAL`, Collaboration Kit won’t work because it doesn’t manually invoke `UI.push()` to send the user interactions to the other connected users. Collaboration Kit works, though, with any of the transport modes for push.

Adding Collaboration Features

This tutorial shows how to build a form in which 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 with any collaborative functionality — not at the start.

@Route(value = "collaboration/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 identifier should be the unique identifier of the currently logged-in user. This tutorial uses an identifier based on the UI instance, instead of a user-based identifier. This allows simulating multiple users by opening the view in multiple browser tabs.

// NOTE: 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 an abbreviation of the name — since the above example doesn’t 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; you don’t have to set it.

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, the components need 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 identifier. A topic is similar to a chat room — it has an identifier that’s unique in the context of the application. Participating members receive all updates made to any topic in which they’re participating. Topic identifiers are freeform strings (e.g., "app" or "contract-126-address"). In this example, there is only one topic on which to work, so you can use any hard-coded topic identifier.

If the application was expanded so that there would be a view for editing person entities, you’d need to have unique topic identifiers for each entity. For example, you could have "person/123" as a topic identifier, where "123" would be different for 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, 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, you’ll need to provide the type that’s edited and the local user’s information. After initializing, use the regular binder methods to bind the person object’s name property to the text field component, and the date of birth property to the date picker component.

Finally, set the topic on which to connect — the same as for CollaborationAvatarGroup — and a supplier for the initial bean value that populates the fields when the first user connects to the topic. The supplier could load the editable item from a backend, but in this example it populates 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 propagates the field values among users, as well as displays the currently focused user with the field highlight.

Running the Application

Follow the instructions in the application’s README.md file to start it. Then 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.

5F96993D-DDC3-48F8-A2FE-D49ABB4C1865

Documentation