> Markdown version of [Quick Start Guide](https://vaadin.com/docs/next/tools/collaboration/tutorial). Section index: [llms.txt](https://vaadin.com/docs/next/tools/llms.txt)

# <a id="ce.tutorial"></a>Getting Started with Collaboration Kit (deprecated since V25.3)

> **Warning:** Collaboration Kit is superseded by [signals](https://vaadin.com/docs/next/flow/ui-state/shared-signals.md) and is scheduled for removal in Vaadin 26.
>
> See [Migrating from Collaboration Kit to Signals](https://vaadin.com/docs/next/tools/collaboration/migrating-to-signals.md) for how.

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).

## <a id="ce.tutorial.setup"></a>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`.

### <a id="ce.tutorial.push"></a>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.

```java
@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.

## <a id="ce.tutorial.add_collaborative_features"></a>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:

`TutorialView.java`

```java
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;
    }
}
```

### <a id="creating-a-simple-view"></a>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.

`TutorialView.java`

```java
@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);
    }
}
```

### <a id="providing-user-information"></a>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.

`TutorialView.java`

```java
// NOTE: Use the user id of the logged-in user
// instead
String userId = System.identityHashCode(UI.getCurrentOrThrow()) + "";
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.

### <a id="adding-user-avatars"></a>Adding User Avatars

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

`TutorialView.java`

```java
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.

### <a id="adding-field-collaboration"></a>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](https://vaadin.com/docs/next/flow/binding-data/components-binder.md) 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:

`TutorialView.java`

```java
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.

## <a id="ce.tutorial.run"></a>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`