Define an expandable grid

Expandable grids enable you toggle grid rows open or closed by clicking on the row. You can expand the row to view the child row data and close the expanded rows to remove them from the grid.

The below sections take you through the process of configuring expandable functionality on grids. You should be already familiar with creating a grid component and adding a grid to a Webcentric layout.

Add definition to XML

As with regular grids, expandable grids are defined with an XML definition. The XML definition for expandable grids use ExpandableGridDataProvider as the row model data provider.

An example of the XML using ExpandableGridDataProvider with an alias of caplin.expandable-row-grid-data-provider is displayed below:

<grid displayedColumns="description, rate">
   <gridRowModel>
      <caplin.expandable-row-grid-data-provider container="/CONTAINER/FX/Major" config="caplinx.fxtrader.grid.ContainerChildRowConfig"/>
   </gridRowModel>
   <columnDefinitions>
      <column id="description"/>
      <column id="rate"/>
      <column id="size"/>
   </columnDefinitions>
   <decorators>
      <dragDecorator/>
   </decorators>
</grid>

Configure Data

To utilise expandable grids, you will need to configure the data source for the initial row data (parent rows) and create a mechanism that allows the container subject for child row data to be determined from any parent row subject.

The parent container subject is configured with the 'container' attribute as is the case for regular grids.

The child rows data source is configured by referencing a grid specific class from the 'config' attribute. The referenced class must implement the following methods in the ContainerChildRowConfig interface:

String getChildContainerName(String subject) - This provides the expandable grid with the child container subject for a specified parent row subject. It returns: {String} the child container subject to request.

Object getChildRowFieldMappings() - Thisprovides the expandable grid with a set of field mappings for child rows. This is useful in two cases: (a) when you require a given field to be displayed in one column for parent rows, and another column for child rows and (b) when you require a given column to display one field for parent rows, and another field for child rows. It returns: {Object} a map of child field names to the field names that they should be mapped to.

If any transformations are applied to the grid (filtering/sorting/etc.), these will only affect the parent rows.

Add Expansion Trigger

The trigger for an expansion is raising a renderer event called 'rowToggle' which can be achieved via a cell renderer handler as demonstrated below.

caplinx.element.handler.ExpandableRowHandler.prototype.onclick = function(oEvent, oRenderer, mAttributes){
   oRenderer.raiseEvent('rowToggle', oEvent);
};

Some of the processing that occurs before the data is passed onto the GridView involves adding useful information to the child row data. This data can be used by stylers or click handlers to style child rows and opened parent rows or handle click actions differently from normal rows.

Key Value

RowType

The type of row. Can have the following values:

  • expandable (a row that can be expanded)

  • expanding (an expandable row that has been expanded, and is currently waiting for its child row data)

  • expanded (an expandable row that has been expanded, and is currently showing its child rows)

  • child (a child row of an expanded row)

  • lastChild (the last child row of any given parent)

ErrorMessage

An error message that is provided when a row was unable to expand correctly. If the row is not in error, this will be set to an empty string.
You can export the parent rows of an expandable grid to a CSV file. Exporting of child rows within an expandable grid is not currently supported.

Add Row Handlers

Caplin provide an expand row handler caplin.grid.expandable.util.ExpandRowButtonHandler which handles expanding row events. Therefore, a renderer set up like the example below can be used to style rows differently depending on what type of row they are.

<renderer name="fx-blotter-expandable">
   <control name="caplin.control.basic.ImageControl">
   <![CDATA[<div style='position:relative;overflow:hidden;width:8px;height:8px;top:4px;left:4px;'><div class='gridexpandbutton'></div></div>]]>
      <top-mouseout>0</top-mouseout>
      <top-mouseover>8</top-mouseover>
      <top-mousedown>16</top-mousedown>
      <top-disabled>24</top-disabled>
      <handler name="caplin.grid.expandable.util.ExpandRowButtonHandler"/>
   </control>
   <downstream>
      <transform name="caplin.element.formatter.NullValueFormatter">
         <attribute name="nullValue" value=""/>
      </transform>
      <transform name="caplinx.element.styler.FxBlotterExpandableRowStyler" include="RowType,ErrorMessage">
         <attribute name="errorMessage" value="${ErrorMessage}"/>
         <attribute name="rowType" value="${RowType}"/>
      </transform>
   </downstream>
</renderer>