Namespace: caplin/grid/expandable

Provides a standard data provider implementation that enhances the grid by adding the ability to toggle grid rows open or closed. When rows are toggled open they will push child row data into the grid. Closing them will remove the rows from the grid.

Like normal grids these grids can be defined with an XML definition. The only difference between a normal grid and an expandable one is the use of the ExpandableGridDataProvider as the row model data provider. An example of the XML is displayed below using aliasing:

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

Expandable grids are used to display data from multiple data provider. The majority of the time users will not want to see child row data and therefore it's not included in the underlying data provider's row data. There are times when the user may find it helpful to see data that is not in the used data provider and that is where the expandable grid data provider can be used.

The architecture of the expandable data provider requires that the user configures two sources of data. One is the parent data source which provides the data that is displayed when the user first loads up a grid and there are no child rows displayed. This data provider is configured with the 'container' attribute. The other is the data source for the child rows which is configured using the 'config' attribute. There is an interface caplin.grid.expandable.ContainerChildRowConfig that should be implemented to provide a class to the config attribute. This will then be used to determine which container will be used for each parent row's child rows.

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

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

ExpandableRowHandler.prototype.onclick = function(event, renderer, attributes) {
	renderer.raiseEvent('rowToggle', event);
};

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.

Caplin provide an expand row handler caplin.grid.expandable.util.ExpandRowButtonHandler which handles expanding row events. So for example a renderer set up like 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>