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> element of your <grid> definition.

<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

<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> element, and whether or not a column is mandatory is specified in the XML, as a Boolean attribute of the <column> tag that defines it.

ColumnReorderingDecorator

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

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

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

ColumnResizingDecorator allows the user to resize columns, by using a mouse to drag a column-border to the left or right.

ColumnSortDecorator

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

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

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

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

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

A grid with a 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 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

<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:

<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> tag, row-grouping will be applied, based on whichever column is being used to sort the grid contents at the time.

The <column> 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

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

HoverDecorator highlights the grid row that the user’s mouse is currently hovering over.

LoadingDataDecorator

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

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

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

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

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

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.

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

ResetColumnsDecorator

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

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

<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

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

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

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

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.