> Markdown version of [Topic API](https://vaadin.com/docs/next/tools/collaboration/advanced/topic-api). Section index: [llms.txt](https://vaadin.com/docs/next/tools/llms.txt)

# <a id="ce.topic-tutorial"></a>Getting Started with Topic API (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 tutorial shows how to use the low-level Collaboration Kit APIs, by updating and subscribing to a topic map.

To be more productive in creating collaborative applications, use the high-level APIs as described in the [Quick Start Guide](https://vaadin.com/docs/next/tools/collaboration/tutorial.md).

## <a id="ce.topic-tutorial.setup"></a>Preparations

Follow the preparation steps in the [Preparing the Application](https://vaadin.com/docs/next/tools/collaboration/tutorial.md#ce.tutorial.setup) in the Quick Start Guide.

## <a id="ce.topic-tutorial.add-collaboration-features"></a>Add Collaboration Features

This tutorial shows how to build a view with a checkbox where the user can choose whether they’re in a *Friday mood*.

### <a id="create-a-simple-view"></a>Create a Simple View

First, create the view with a checkbox, but not any collaborative functionality — at least not yet.

`TopicView.java`

```java
@Route(value = "collaboration/topic", layout = MainView.class)
public class TopicView extends VerticalLayout {

    private final Checkbox checkbox;

    public TopicView() {
        checkbox = new Checkbox("Is it Friday?");
        add(checkbox);
    }
}
```

### <a id="define-topic-connection"></a>Define Topic Connection

Sharing data between multiple users happens through a `TopicConnection` instance. By default, the connection is deactivated until its related component is attached to the UI.

Open a connection to the `tutorial` topic, and define the activation callback which is triggered when the current `TopicView` component (i.e., `this`) is attached. The user who is related to the topic connection must be defined.

`TopicView.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);
CollaborationEngine.getInstance().openTopicConnection(this, "tutorial",
        localUser, topic -> {
            return null;
        });
```

The activation callback should return a registration, which Collaboration Kit runs when the connection is deactivated. Since the example does not yet register any listeners that need clean-up, it can return `null`.

### <a id="define-topic-category"></a>Define Topic Category

The topic stores collaborative data in named maps and lists.

In the activation callback, get a map by its name:

`TopicView.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);
CollaborationEngine.getInstance().openTopicConnection(this, "tutorial",
        localUser, topic -> {
            CollaborationMap fieldValues = topic
                    .getNamedMap("fieldValues");
            return null;
        });
```

### <a id="pass-values-to-topic"></a>Pass Values to Topic

The first actual step to making the application collaborative is to update the topic whenever the checkbox value changes. The key `isFriday` is associated with the value of the checkbox. Add a value change listener that updates the related topic map.

`TopicView.java`

```java
CollaborationEngine.getInstance().openTopicConnection(this, "tutorial",
        localUser, topic -> {
            CollaborationMap fieldValues = topic
                    .getNamedMap("fieldValues");
            Registration registration = checkbox
                    .addValueChangeListener(valueChangeEvent -> {
                        fieldValues.put("isFriday",
                                valueChangeEvent.getValue());
                    });
            return registration;
        });
```

The topic’s structure now looks as follows:

```
Topic maps
|_ fieldValues
  |_ isFriday: true/false
```

> **Tip: Add Scope to Topic Data**
>
> By default, values are stored in the Topic until explicitly removed. You can use methods accepting a scope parameter and use `EntryScope.CONNECTION` to have the entry removed when the connection is deactivated.

### <a id="subscribe-to-topic-changes"></a>Subscribe to Topic Changes

The final part of the code is to subscribe to updates to the topic map, and to update the checkbox if the related map is changed. This is also done in the activation callback so that the subscription is opened only when the view is actually used.

It’s also necessary to return the registration of the listener so it can be removed when the component is detached to avoid leaking memory.

`TopicView.java`

```java
CollaborationEngine.getInstance().openTopicConnection(this, "tutorial",
        localUser, topic -> {
            CollaborationMap fieldValues = topic
                    .getNamedMap("fieldValues");
            Registration registration = checkbox
                    .addValueChangeListener(valueChangeEvent -> {
                        fieldValues.put("isFriday",
                                valueChangeEvent.getValue());
                    });
            fieldValues.subscribe(event -> {
                if ("isFriday".equals(event.getKey())) {
                    checkbox.setValue(Boolean.TRUE
                            .equals(event.getValue(Boolean.class)));
                }
            });
            return registration;
        });
```

> **Tip: Combining Registrations**
>
> In case there are many registrations, they can be combined by `Registration.combine(registration1, registration2);`.

## <a id="ce.topic-tutorial.run"></a>Run the Application

Follow the instructions in the application’s `README.md` file to start the application. Then open `http://localhost:8080/` in multiple browser tabs to see how a change made in one tab is automatically shown in the other tabs.

`D24BC999-9D07-4390-BC29-F57C87DBA927`