Add and remove watchlist subjects

Once users have created a watchlist and displayed it in a grid, they will want to add and remove subjects from it. The Watchlist API provides methods for inserting, appending and removing subjects from a watchlist.

Prerequisites

Please ensure that your installation meets the requirements and configuration outlined in Watchlist API prerequisites.

Adding and removing watchlist subjects

The Watchlist object manages the subscription to its server-side container on Transformer. In order to make the most efficient use of StreamLink resources, the subscription is only active when there are parties interested in the watchlist’s content. The Watchlist class tracks the number of interested parties by forcing all operations on a watchlist’s content to occur through instances of a second class: WatchlistContentsManager. A party signals its interest in the watchlist’s contents by requesting a WatchlistContentsManager object, and signals the termination of its interest by destroying the WatchlistContentsManager object. While at least one active WatchlistContentsManager object exists, the watchlist will maintain its subscription.

To acquire a contents manager for a particular watchlist, call Watchlist.getContentsManager:

var watchlistContentsManager = watchlist.getContentsManager();

When you no longer need the contents manager, call WatchlistContentsManager.destroy to give the Watchlist object the opportunity to shutdown the subscription if there are no other interested parties:

watchlistContentsManager.destroy();

The WatchlistGridDataProvider class uses the WatchlistContentsManager class internally to automatically synchronise changes made to the grid with the server-side watchlist.

Appending a subject

To append one or more instruments to a watchlist, call WatchlistContentsManager.append. Pass an array containing the subject names of the instruments.

var watchlistContentsManager = watchlist.getContentsManager();
watchlistContentsManager.append(['/FX/GBPUSD']);

Inserting a subject

To insert one or more instruments into a watchlist, call WatchlistContentsManager.insert. Pass an array containing the subject names of the instruments, and the index at which to insert them.

var watchlistContentsManager = watchlist.getContentsManager();
watchlistContentsManager.insert(['/FX/GBPUSD'], 2);

Removing a subject

To remove one or more instruments from a watchlist, call WatchlistContentsManager.remove. Pass an array containing the subject names of the instruments.

var watchlistContentsManager = watchlist.getContentsManager();
watchlistContentsManager.remove(['/FX/GBPUSD']);