# Class: FixedColumns

FixedColumns v2.0.1 documentation

new FixedColumns( oDT:object, [oInit:object] )

  When making use of DataTables' x-axis scrolling feature, you may wish to fix the left most column in place. This plug-in for DataTables provides exactly this option (note for non-scrolling tables, please use the FixedHeader plug-in, which can fix headers, footers and columns). Key features include:

  - Freezes the left or right most columns to the side of the table
  - Option to freeze two or more columns
  - Full integration with DataTables' scrolling options
  - Speed - FixedColumns is fast in its operation

  ### Constructor

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | oDT | object |  |  | DataTables instance
  2 | oInit | object | Optional | {} | Configuration object for FixedColumns. Options are defined by FixedColumns.defaults

  ##### Example:

       	var oTable = $('#example').dataTable( {
       		"sScrollX": "100%"
       	} );
       	new FixedColumns( oTable );

### Requires

- jQuery 1.3+
- DataTables 1.8.0.dev+

## Summary

### Namespaces

defaults
  FixedColumns default settings for initialisation
dom
  DOM elements used by the class instance
s
  Settings object which contains customisable information for FixedColumns instance

### Methods

fnRecalculateHeight( nTr:Node ):void
  Mark a row such that it's height should be recalculated when using 'semiauto' row height matching. This function will have no effect when 'none' or 'auto' row height matching is used.
fnRedrawLayout( ):void
  Recalculate the resizes of the 3x3 grid that FixedColumns uses for display of the table. This is useful if you update the width of the table container. Note that FixedColumns will perform this function automatically when the window.resize event is fired.
fnSetRowHeight( nTarget:Node, iHeight:int ):void
  Set the height of a given row - provides cross browser compatibility
fnUpdate( ):void
  Update the fixed columns - including headers and footers. Note that FixedColumns will automatically update the display whenever the host DataTable redraws.
<private> _fnClone( oClone:Object, oGrid:Object, aiColumns:Array, bAll:Boolean ):void
  Clone the DataTable nodes and place them in the DOM (sized correctly)
<private> _fnCloneLeft( bAll:Boolean ):void
  Clone the left columns
<private> _fnCloneRight( bAll:Boolean ):void
  Clone the right columns
<private> _fnConstruct( oInit:Object ):void
  Initialisation for FixedColumns
<private> _fnCopyLayout( aoOriginal:Object, aiColumns:Object ):Array
  Make a copy of the layout object for a header or footer element from DataTables. Note that this method will clone the nodes in the layout object.
<private> _fnDraw( bAll:Boolean ):void
  Clone and position the fixed columns
<private> _fnEqualiseHeights( nodeName:String, original:Node, clone:Node ):void
  Equalise the heights of the rows in a given table node in a cross browser way
<private> _fnGetTrNodes( nIn:Node ):Array
  From a given table node (THEAD etc), get a list of TR direct child elements
<private> _fnGridHeight( ):void
  Recalculate and set the height of the grid components used for positioning of the FixedColumn display grid.
<private> _fnGridLayout( ):void
  Style and position the grid used for the FixedColumns layout based on the instance settings. Specifically sLeftWidth ('fixed' or 'absolute'), iLeftWidth (px if fixed, % if absolute) and there 'right' counterparts.
<private> _fnGridSetup( ):void
  Set up the DOM for the fixed column. The way the layout works is to create a 1x3 grid for the left column, the DataTable (for which we just reuse the scrolling element DataTable puts into the DOM) and the right column. In each of he two fixed column elements there is a grouping wrapper element and then a head, body and footer wrapper. In each of these we then place the cloned header, body or footer tables. This effectively gives as 3x3 grid structure.

### Events

draw
  Event fired whenever FixedColumns redraws the fixed columns (i.e. clones the table elements from the main DataTable). This will occur whenever the DataTable that the FixedColumns instance is attached does its own draw.

## Details

### Methods

fnRecalculateHeight( nTr:Node ):void

  Mark a row such that it's height should be recalculated when using 'semiauto' row height matching. This function will have no effect when 'none' or 'auto' row height matching is used.

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | nTr | Node |  |  | TR element that should have it's height recalculated

  ##### Example:

       	var oTable = $('#example').dataTable( {
       		"sScrollX": "100%"
       	} );
       	var oFC = new FixedColumns( oTable );

       	// manipulate the table - mark the row as needing an update then update the table
       	// this allows the redraw performed by DataTables fnUpdate to recalculate the row
       	// height
       	oFC.fnRecalculateHeight();
       	oTable.fnUpdate( $('#example tbody tr:eq(0)')[0], ["insert date", 1, 2, 3 ... ]);

fnRedrawLayout( ):void

  Recalculate the resizes of the 3x3 grid that FixedColumns uses for display of the table. This is useful if you update the width of the table container. Note that FixedColumns will perform this function automatically when the window.resize event is fired.

  ##### Example:

       	var oTable = $('#example').dataTable( {
       		"sScrollX": "100%"
       	} );
       	var oFC = new FixedColumns( oTable );

       	// Resize the table container and then have FixedColumns adjust its layout....
           $('#content').width( 1200 );
       	oFC.fnRedrawLayout();

fnSetRowHeight( nTarget:Node, iHeight:int ):void

  Set the height of a given row - provides cross browser compatibility

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | nTarget | Node |  |  | TR element that should have it's height recalculated
  2 | iHeight | int |  |  | Height in pixels to set

  ##### Example:

       	var oTable = $('#example').dataTable( {
       		"sScrollX": "100%"
       	} );
       	var oFC = new FixedColumns( oTable );

       	// You may want to do this after manipulating a row in the fixed column
       	oFC.fnSetRowHeight( $('#example tbody tr:eq(0)')[0], 50 );

fnUpdate( ):void

  Update the fixed columns - including headers and footers. Note that FixedColumns will automatically update the display whenever the host DataTable redraws.

  ##### Example:

       	var oTable = $('#example').dataTable( {
       		"sScrollX": "100%"
       	} );
       	var oFC = new FixedColumns( oTable );

       	// at some later point when the table has been manipulated....
       	oFC.fnUpdate();

<private> _fnClone( oClone:Object, oGrid:Object, aiColumns:Array, bAll:Boolean ):void

  Clone the DataTable nodes and place them in the DOM (sized correctly)

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | oClone | Object |  |  | Object containing the header, footer and body cloned DOM elements
  2 | oGrid | Object |  |  | Grid object containing the display grid elements for the cloned column (left or right)
  3 | aiColumns | Array |  |  | Column indexes which should be operated on from the DataTable
  4 | bAll | Boolean |  |  | Indicate if the header and footer should be updated as well (true)

<private> _fnCloneLeft( bAll:Boolean ):void

  Clone the left columns

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | bAll | Boolean |  |  | Indicate if the header and footer should be updated as well (true)

<private> _fnCloneRight( bAll:Boolean ):void

  Clone the right columns

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | bAll | Boolean |  |  | Indicate if the header and footer should be updated as well (true)

<private> _fnConstruct( oInit:Object ):void

  Initialisation for FixedColumns

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | oInit | Object |  |  | User settings for initialisation

<private> _fnCopyLayout( aoOriginal:Object, aiColumns:Object ):Array

  Make a copy of the layout object for a header or footer element from DataTables. Note that this method will clone the nodes in the layout object.

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | aoOriginal | Object |  |  | Layout array from DataTables (aoHeader or aoFooter)
  2 | aiColumns | Object |  |  | Columns to copy

  ##### Returns:

  Copy of the layout array

<private> _fnDraw( bAll:Boolean ):void

  Clone and position the fixed columns

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | bAll | Boolean |  |  | Indicate if the header and footer should be updated as well (true)

<private> _fnEqualiseHeights( nodeName:String, original:Node, clone:Node ):void

  Equalise the heights of the rows in a given table node in a cross browser way

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | nodeName | String |  |  | Node type - thead, tbody or tfoot
  2 | original | Node |  |  | Original node to take the heights from
  3 | clone | Node |  |  | Copy the heights to

<private> _fnGetTrNodes( nIn:Node ):Array

  From a given table node (THEAD etc), get a list of TR direct child elements

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | nIn | Node |  |  | Table element to search for TR elements (THEAD, TBODY or TFOOT element)

  ##### Returns:

  List of TR elements found

<private> _fnGridHeight( ):void

  Recalculate and set the height of the grid components used for positioning of the FixedColumn display grid.

<private> _fnGridLayout( ):void

  Style and position the grid used for the FixedColumns layout based on the instance settings. Specifically sLeftWidth ('fixed' or 'absolute'), iLeftWidth (px if fixed, % if absolute) and there 'right' counterparts.

<private> _fnGridSetup( ):void

  Set up the DOM for the fixed column. The way the layout works is to create a 1x3 grid for the left column, the DataTable (for which we just reuse the scrolling element DataTable puts into the DOM) and the right column. In each of he two fixed column elements there is a grouping wrapper element and then a head, body and footer wrapper. In each of these we then place the cloned header, body or footer tables. This effectively gives as 3x3 grid structure.

### Events

draw

  Event fired whenever FixedColumns redraws the fixed columns (i.e. clones the table elements from the main DataTable). This will occur whenever the DataTable that the FixedColumns instance is attached does its own draw.

  ##### Parameters:

  | Name | Type | Attributes | Default | Description
  --- | --- | --- | --- | --- | ---
  1 | e | event |  |  | jQuery event object
  2 | o | object |  |  | Event parameters from FixedColumns
  | o.leftClone | object |  |  | Instance's object dom.clone.left for easy reference. This object contains references to the left fixed clumn column's nodes
  | o.rightClone | object |  |  | Instance's object dom.clone.right for easy reference. This object contains references to the right fixed clumn column's nodes