# Create, rename, and delete watchlists

When implementing a watchlist solution using the Watchlist API, one of your coding tasks will be to create functionality to enable users to create, rename and delete watchlists.

## Prerequisites

Please ensure that your installation meets the requirements and configuration outlined in [Watchlist API prerequisites](watchlist-api-prerequisites.md).

## Your entry point to the API

The [WatchlistService,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService) object is your entry point to the Watchlist API. As with other services, you obtain a reference to the [WatchlistService,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService) object through the Caplin Trader [Service Registry,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_core_ServiceRegistry).

```js
var ServiceRegistry = require('caplin/core/ServiceRegistry');
var watchlistService = ServiceRegistry.getService('caplin.watchlist.watchlist-service');
```

## Maintain a list of watchlists

A key feature to provide users with is a list of the watchlists they have created. Users will use the list to select an existing watchlist to display, rename or delete.

You can maintain a dynamic collection of a user’s watchlists by registering listeners for the [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).ADDED and [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).REMOVED events. Listeners to the [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).ADDED event will receive an event for each existing watchlist followed by events for new watchlists as and when they are created. Listeners to the `[WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).REMOVED` event will receive an event whenever a watchlist has been removed.

```js
var ServiceRegistry = require('caplin/core/ServiceRegistry');
var WatchlistServiceEvents = require('caplin/watchlist/WatchlistServiceEvents');

var watchlistService = ServiceRegistry.getService('caplin.watchlist.watchlist-service');

// Map of watchlists
var watchlists = {};

watchlistService.on(WatchlistServiceEvents.ADDED, function(watchlist) {
     watchlists['' + watchlist.getId()] = watchlist;
     alert('watchlist with following name has been added: ', watchlist.getName());
});

watchlistService.on(WatchlistServiceEvents.REMOVED, function(watchlist) {
    delete watchlists['' + watchlist.getId()];
    alert('watchlist with following name has been removed: ', watchlist.getName());
});
```

## Create a new watchlist

Create the watchlist using the [WatchlistService.create,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService#create) method. The method sends a command to Transformer to create a watchlist and returns immediately. If the command is successful, the Watchlist API will create a local Watchlist object for the new watchlist, and you can acquire a reference to this object in one of two ways:

* **Method 1**: Pass a callback function to the [WatchlistService.create,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService#create) method. The callback will be called once on the successful creation of the watchlist, with the new [Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) object passed to the callback as a function parameter.
* **Method 2**: Register an event handler (a listener) for the [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).ADDED event (see Retrieving and maintaining a list of watchlists). Unlike the callback in method 1, the listener is not restricted to receiving the creation event of a specific watchlist but instead receives creation events for all watchlists created by the user, whether on the same device or on another device under a concurrent login.

Here’s an example of creating a watchlist that uses **Method 1** to create and obtain a [Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) object:

```js
var ServiceRegistry = require('caplin/core/ServiceRegistry');
var watchlistService = ServiceRegistry.getService('caplin.watchlist.watchlist-service');

watchlistService.create('demo watchlist',
    function() { console.log('error creating watchlist'); },
    function(watchlist) { id = watchlist.getId(); console.log('success creating watchlist:', id, watchlist.getName()); }
);
```

## Rename a watchlist

To change the name of a watchlist use the [Watchlist.setName,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist#setName) method. This method changes the name of the watchlist on Transformer, and then Transformer pushes the change to all subscribing [StreamLink](../../../caplin-platform/streamlink/index.md) clients. The local watchlist object’s name is updated by the [WatchlistService,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService) object on being advised of the change by [Transformer](../../../caplin-platform/transformer/index.md).

```js
watchlist.setName('new name');
```

## Delete a watchlist

To delete a watchlist, use the [WatchlistService.dispose,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService#dispose) method. This method takes an array of watchlists as its first argument and so can be used to delete multiple watchlists in one operation. A reference to a single watchlist must be passed as a single element array. Note that the success callback doesn’t receive an array of the watchlists that have been deleted; you should use a listener to the [WatchlistServiceEvents,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistServiceEvents).REMOVED event if you need to clean up any references to the deleted watchlists.

```js
var ServiceRegistry = require('caplin/core/ServiceRegistry');
var watchlistService = ServiceRegistry.getService('caplin.watchlist.watchlist-service');

var watchlist = watchlistService.getById(id);

watchlistService.dispose([watchlist],
    function(watchlists) { console.log('error disposing watchlist', watchlists); },
    function() { console.log('success disposing watchlist'); }
);
```

---

**See also:**

* [Watchlist API interfaces and classes](watchlists-watchlist-api-interfaces-and-classes.md)
* How can I... [Add and remove watchlist subjects](watchlists-working-with-watchlists.md)
* How can I... [Configure Transformer to host synchronised watchlists](../../../caplin-platform/transformer/configure-transformer-to-host-synchronised-watchlists.md)