# Available decorators

**Decorators** are an easy way of adding styling and added functionality to a grid. There is a separate decorator class for each piece of functionality, and to include them, you need to add two pieces of code into the XML **grid definitions** file. This tutorial shows you how.

## XML Grid Definitions File

Adding a decorator to your gid is easy, you can add some or all of them by including an empty decorator alias tag inside the `[<decorators>](https://docs.caplin.com/developer/xml/grid/latest/decorators.html)` element of your `[<grid>](https://docs.caplin.com/developer/xml/grid/latest/grid.html)` definition.

```xml
<grid id="myGrid">

    <decorators>
        <myAliasDecorator1 />
        <myAliasDecorator3 />
    </decorators>

<grid/>
```

You don’t have to include all decorators in the grid tag, but only the ones included here will be applied to the displayed grid.

## How Decorators Work

The way decorators apply formatting is by setting classes on certain HTML elements in particular circumstances (user-driven mouse events, changes to the values of displayed data, certain components rendered, etc...). The style information applicable to those classes is contained in a CSS file that is specific to the decorator concerned, and which will be included in the shipped theme.

## ColumnHeaderMenuDecorator

```xml
<decorators>
    <caplin.column-header-menu-decorator/>
</decorators>
```

`ColumnHeaderMenuDecorator` adds a pop-up menu to each column in a grid, which allows the user to sort, add or remove columns as required. The columns that can be added to a grid are included in the XML `[<columnDefinitions>](https://docs.caplin.com/developer/xml/grid/latest/columnDefinitions.html)` element, and whether or not a column is _mandatory_ is specified in the XML, as a Boolean attribute of the `[<column>](https://docs.caplin.com/developer/xml/grid/latest/column.html)` tag that defines it.

## ColumnReorderingDecorator

```xml
<decorators>
    <caplin.column-reordering-decorator/>
</decorators>
```

`[ColumnReorderingDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.columnreorderingdecorator)` gives users the ability to change the order of columns by clicking on the column header and dragging it to a different position in the grid.

## ColumnResizingDecorator

```xml
<decorators>
    <caplin.column-resizing-decorator/>
</decorators>
```

`[ColumnResizingDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.columnresizingdecorator)` allows the user to resize columns, by using a mouse to drag a column-border to the left or right.

## ColumnSortDecorator

```xml
<decorators>
    <caplin.column-sort-decorator/>
</decorators>
```

`[ColumnSortDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.columnsortdecorator)` allows users to modify the sort behaviour on a grid column by clicking on the column header. With each click, the column’s sort behaviour changes; going from _none_ to _ascending_ to _descending_, in that order.

## DragDecorator

```xml
<decorators>
    <caplin.grid-drag-decoratorr ddGroup="fxInstruments"/>
</decorators>
```

`[DragDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.dragdecorator)` allows instruments within a grid to be dragged, and then dropped into other display components configured with a drop decorator with the same `ddGroup` value.

### Attributes

| Attribute | Value | Description |
| --- | --- | --- |
| `ddGroup` | Drag & drop group ID | Allows instruments to be dragged and dropped between components with the same `ddGroup` value. |

## DropDecorator

```xml
<decorators>
    <caplin.grid-drop-decorator ddGroup="fxInstruments" />
</decorators>
```

A grid with a [`DropDecorator`,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/#caplin.grid.decorator.dropdecorator) allows instruments that are being dragged from another display component to be dropped into it, as long as the `DropDecorator` on the target grid has a `ddGroup` attribute that matches the one in the [`DragDecorator`,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/#caplin.grid.decorator.dropdecorator) element of the component it’s being dragged from.

### Attributes

| Attribute | Value | Description |
| --- | --- | --- |
| `ddGroup` | Drag & drop group ID | Allows instruments to be dragged and dropped between components with the same `ddGroup` value. |

## GroupHeaderDecorator

```xml
<decorators>
       <caplin.grid-group-header-decorator headerTextField="SubHeaderText" />
</decorators>
```

`GroupHeaderDecorator` is used to format the sub-header rows when grid results are grouped by a particular field. Note that the `GroupHeaderDecorator` tag doesn’t actually control the grouping or the creation of the sub-heading rows; only the formatting of it.

It relates to the grouping function itself as follows:

```xml
<grid id="anyGrid" displayedColumns="description, bidprice, askprice">

   <gridRowModel groupBy="groupBy">
<sortRule field="Description" type="text" />
   </gridRowModel>

   <columnDefinitions>
       <column id="description" fields="Description, SubHeaderText" />
    <column ... />
    <column ... />
   </columnDefinitions>

   <decorators>
       <groupHeaderDecorator headerTextField="SubHeaderText" />
   </decorators>

</grid>
```

If the `groupBy` attribute is present in the `[<gridRowModel>](https://docs.caplin.com/developer/xml/grid/latest/gridRowModel.html)` tag, row-grouping will be applied, based on whichever column is being used to sort the grid contents at the time.

The `[<column>](https://docs.caplin.com/developer/xml/grid/latest/column.html)` tag that defines the Description column has two values in its `fields` attribute: the field name (`Description`) and `SubHeaderText`. The value of `SubHeaderText` is provided by the server.

### Attributes

| Attribute | Value | Description |
| --- | --- | --- |
| `headerTextField` | "SubHeaderText" | Optional. This attribute can be omitted, as it is the default setting in any case. |

## HoverDecorator

```xml
<decorators>
    <caplin.grid-hover-decorator/>
</decorators>
```

`[HoverDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.hoverdecorator)` highlights the grid row that the user’s mouse is currently hovering over.

## LoadingDataDecorator

```xml
<decorators>
    <caplin.grid-data-loading-decorator showInitialLoad="true"/>
</decorators>
```

`[LoadingDataDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.loadingdatadecorator)` renders a rotating icon whenever the grid is waiting for data to arrive, to allow the user to see that the grid data are currently loading.

### Attributes

| Attribute | Value | Description |
| --- | --- | --- |
| `showInitialLoad` | Boolean (true or false) Default: true | Determines whether or not the icon will be displayed the first time the grid is loaded. |

## NoDataFoundBubbleMessageDecorator

```xml
<decorators>
    <caplin.grid-data-not-found-decorator headerText="data_unavailable" bodyText="no_data_received" 
                    ConnectionLostHeaderText="data_unavailable" connectionLostBodyText="no_data_received"/>
</decorators>
```

`[NoDataFoundBubbleMessageDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.nodatafoundbubblemessagedecorator)` renders a bubble containing an explanatory message with separate heading and body text, over any grid that currently has no data to display. The attributes provide the text that will be used in different parts of the message bubble, and can either be plain text, or (preferably) can be the name of a value in a properties file. If using properties file values, you can also include internationalization tokens to support local language versions of the message.

### Attributes

| Attribute | Value | Description |
| --- | --- | --- |
| `headerText` | Name of a variable in the properties file (I18n tags can be used) | The text that populates the "No data found" bubble’s header section. |
| `bodyText` | Name of a variable in the properties file (I18n tags can be used) | The text that populates the "No data found" bubble’s standard body text. |
| `connectionLostBodyText` | Name of a variable in the properties file (I18n tags can be used) | The text that populates the "No data found" bubble’s body text if the lack of data is due to connection loss. |

## RemoveRowDecorator

```xml
<decorators>
    <caplin.row-removal-decorator/>
</decorators>
```

`[RemoveRowDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.removerowdecorator)` provides immediate visual feedback of rows that are pending removal, until the server round-trip has completed, and the row is actually removed from the view.

**📌 NOTE**\
This does not affect the user’s ability to delete rows, it only modifies the display until a pending removal takes effect.

## ResetColumnsDecorator

```xml
<decorators>
    <caplin.column-reset-decorator clearImgUrl="gif_image.gif"/>
</decorators>
```

`[ResetColumnsDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.resetcolumnsdecorator)` provides a single button that users can use to remove any column filters they may have applied, and/or to reset the column sort order to original state.

### Attributes

| Attribute | Value | Description |
| --- | --- | --- |
| `clearImgUrl` | Location and name of an image file | Specifies the image to use for the reset button. |

## RowLoadingDecorator

```xml
<decorators>
    <caplin.row-loading-decorator imagePath="loading-row.gif" />
</decorators>
```

`RowLoadingDecorator` renders an image on individual rows, while they are waiting to be populated by data.

### Attributes

| Attribute | Value | Description |
| --- | --- | --- |
| `imagePath` | Location and name of an image file | Specifies the image to use for the row loading indicator. |

## ScrollTipDecorator

```xml
<decorators>
    <caplin.grid-scroll-tip-decorator />
</decorators>
```

`[ScrollTipDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.scrolltipdecorator)` causes a tooltip to be displayed during scrolling, showing the row number of the top row currently displayed, and the total number of rows in the grid.

## SelectionDecorator

```xml
<decorators>
    <caplin.grid-selection-decorator persistSelection="false" singleSelection="true"/>
</decorators>
```

`[SelectionDecorator,opts="nofollow"](https://docs.caplin.com/developer/api/caplin_trader/3/caplin.grid.decorator.selectiondecorator)` allows the user to select rows. The tag’s attributes specify whether they are able to select multiple rows (`singleSelection`) or if the selection will persist when another row is selected (`persistSelection`).

### Attributes

| Attribute | Value | Description |
| --- | --- | --- |
| `persistSelection` | Boolean (true or false) Default: false | Controls whether or not a row will remain selected when another row is selected. |
| `singleSelection` | Boolean (true or false) Default: false | Controls whether or not more than one row can be selected simultaneously. |