Display a watchlist in a grid

After creating a user-interface to create, rename and delete watchlists, the next task is to enable a user to display a watchlist in a grid. The Watchlist API provides an implementation of the GridDataProvider interface to link a Grid component to a Transformer-managed watchlist.

Prerequisites

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

Linking a watchlist to a grid component

The Watchlist API provides a WatchlistGridDataProvider class to link a grid to a watchlist. The WatchlistGridDataProvider performs the following operations for you:

  • Reads the XML grid definition and retrieves the pertinent Watchlist object from the Watchlist Service by passing the ID of the watchlist to WatchlistService.getById. See below for the original source of the watchlist’s ID.

  • Manages the lifecycle of a WatchlistContentsManager for the watchlist in response to lifecycle events from the grid.

  • Responds to requests by the grid to add and remove content by sending messages to Transformer to add and remove subjects from the watchlist. This includes instruments added via drag and drop functionality implemented using a grid decorator.

  • Updates the selection of financial instruments displayed by the grid when changes are pushed from Transformer via Liberator.

To link a grid to a watchlist, you will need the server-side ID of the watchlist, and this is accessible from the Watchlist.getId method. The source of the Watchlist object depends on whether the watchlist has been newly created or already exists:

  • New watchlist: the new Watchlist object will be passed to the success callback parameter of the WatchlistService.create method

  • Existing watchlist: references to a user’s existing watchlists can be maintained in an array by using the WatchlistServiceEvents.ADDED and WatchlistServiceEvents.REMOVED events. For more details, see Create, delete and rename watchlists.

To create a grid that links to a watchlist, use the <caplin.watchlist.watchlist-grid-data-provider> element in the XML definition of the grid’s row model, quoting the ID of the watchlist in the watchlistId attribute.

The example grid definition below uses a fictional base template app.grid.definition that you should replace with a grid definition from your own application.

var ServiceRegistry = require('caplin/core/ServiceRegistry');
var layoutService = ServiceRegistry.getService('caplin.layout-service');
var layout = layoutService.getSelected();

var xml = '<grid baseTemplate="app.grid.definition">'
    + '<gridRowModel>'
    + '<caplin.watchlist.watchlist-grid-data-provider watchlistId="' + watchlist_id + '" />'
    + '</gridRowModel>'
    + '</grid>';
var watchlistGrid = caplin.component.ComponentFactory.createComponent(xml);
layout.insertComponent(watchlistGrid);

Adding UI functionality for adding and removing watchlist subjects

Please see the documentation for the Grid component for more information on extending the UI functionality of a grid. Useful features to consider adding to your grid include:

  • An interface for selecting a financial instrument to add to the grid

  • An interface to drag and drop financial instruments between grids (see grid decorators)

  • An interface to remove financial instruments from a grid

For UI components with extended functionality for FX, consider FX Motif 2.

See also: