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.

Your entry point to the API

The WatchlistService object is your entry point to the Watchlist API. As with other services, you obtain a reference to the WatchlistService object through the Caplin Trader Service Registry.

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.ADDED and WatchlistServiceEvents.REMOVED events. Listeners to the 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.REMOVED event will receive an event whenever a watchlist has been removed.

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 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 method. The callback will be called once on the successful creation of the watchlist, with the new Watchlist object passed to the callback as a function parameter.

  • Method 2: Register an event handler (a listener) for the 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 object:

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 method. This method changes the name of the watchlist on Transformer, and then Transformer pushes the change to all subscribing StreamLink clients. The local watchlist object’s name is updated by the WatchlistService object on being advised of the change by Transformer.

watchlist.setName('new name');

Delete a watchlist

To delete a watchlist, use the 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.REMOVED event if you need to clean up any references to the deleted watchlists.

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: