# 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,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_grid_GridDataProvider) interface to link a [Grid](../../3/grid/index.md) component to a Transformer-managed watchlist.

## Prerequisites

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

## Linking a watchlist to a grid component

The Watchlist API provides a [WatchlistGridDataProvider,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_sljs_WatchlistGridDataProvider) class to link a [grid](../../3/grid/index.md) to a watchlist. The [WatchlistGridDataProvider,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_sljs_WatchlistGridDataProvider) performs the following operations for you:

* Reads the XML grid definition and retrieves the pertinent [Watchlist,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) object from the Watchlist Service by passing the ID of the watchlist to [WatchlistService.getById,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_WatchlistService#getById). See below for the original source of the watchlist’s ID.
* Manages the lifecycle of a [WatchlistContentsManager,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_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](../../../caplin-platform/transformer/index.md) 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](../../../caplin-platform/liberator/index.md).

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,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/4/module-caplin_watchlist_Watchlist) 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](watchlists-creating-and-deleting-watchlists.md).

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.

```js
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](../../3/grid/index.md) 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](../grid/grid-available-decorators.md))
* An interface to remove financial instruments from a grid

For UI components with extended functionality for FX, consider [FX Motif 2](../../../fx-professional/index.md).

---

**See also**:

* How can I ... [Create, delete and rename watchlists](watchlists-creating-and-deleting-watchlists.md)
* How can I ... [Add and remove watchlist subjects](watchlists-working-with-watchlists.md)
* [Grid component](../../3/grid/index.md)
* [FX Motif](../../../fx-professional/index.md)