Table

Method summary

Members

EditorType - { string }

Enum for the table editor types that are supported.

Properties:

Name	Type	Default	Description
CHECKBOX	string	checkbox
TEXT	string	text
SELECT	string	select

dataTable - { jQuery }

A reference to the underlying DataTable object.

Methods

addRows ( data, redraw ) → {Array.<number>}

Add new row to the table using specified data.

Parameters:

Name	Type	Argument	Default	Description
data	Array			The new row data
redraw	boolean	optional	true	Whether to redraw the table after adding the rows

Returns:

Type	Description
Array.<number>	Array of row indexes that have been added to aoData

Back to Top

destroy ( )

Destroy the Table instance. This will destroy the underlying DataTable and remove the table DOM elements.

Back to Top

draw ( )

Draw the table.

Back to Top

getRows ( row, col ) → {Object|string}

Get row or cell data.

Parameters:

Name	Type	Argument	Description
row	jQuery | number		TR row node, TD/TH cell node or the row index
col	number	optional	Column index. If not given then the function will return the entire row

Returns:

Type	Description
Object | string	Either data for entire row or, if col is specified, data for the specified cell

Back to Top

isLocked ( ) → {boolean}

Check if the table is locked.

Returns:

Type	Description
boolean	Whether the table is locked or not

Back to Top

lock ( overlayMessage )

Lock the table from being able to perform edit actions.

Parameters:

Name	Type	Argument	Description
overlayMessage	string	optional	Provide a custom overlay message. Otherwise uses a default message.

Back to Top

numRows ( ) → {number}

Count number of rows in a table.

Returns:

Type	Description
number	The number of rows present

Back to Top

removeRow ( row, redraw ) → {Array.<*>}

Remove a specified row from the table.

Parameters:

Name	Type	Argument	Default	Description
row	number			The row number to delete
redraw	boolean	optional	true	Whether to redraw the table after adding the rows

Returns:

Type	Description
Array.<*>	Data of the row that was deleted

Back to Top

setEditing ( enabled )

Set edit mode on or off.

Parameters:

Name	Type	Description
enabled	boolean	Whether edit mode should be enabled

Back to Top

unlock ( )

Unlock the table so that editing can resume.

Back to Top

updateRow ( row, col, data, redraw ) → {number}

Update a specified row or cell with new data.

Parameters:

Name	Type	Argument	Default	Description
row	number
col	number
data	Array			The new row data
redraw	boolean	optional	true	Whether to redraw the table after adding the rows

Returns:

Type	Description
number	0 on success, 1 on error

Back to Top

Type Definitions

Cell - { object }

Properties:

Name	Type	Description
displayPosition	Table#DisplayPosition	The display position of this cell
rowData	Array.<PrimitiveType>	The row data
value	PrimitiveType	The cell value
element	Element	The cell DOM Element.

DisplayPosition - { object }

Properties:

Name	Type	Description
row	number	row index
column	number	column index

ColumnOptions - { Object }

Data structure passed to Table. Data structure passed to Table.

Properties:

Name	Type	Argument	Default	Description
name	string			The title to be displayed for this column.
width	string	optional		The column width. Takes any valid css value for defining width.
type	insight.enums.DataType			The data type this column. Can only be one of the primitive types from Xpress Insight. This is used to determine sorting semantics.
displayType	insight.enums.DataType	optional		The display data type for this column. Can only be one of the primitive types from Xpress Insight. This is used for display styling. If not specified then the 'type' property will be used.
visible	boolean	optional	true	Show or hide the column. Defaults to visible.
cellType	string	optional	'td'	Specify the type of cell to use for this column. Either 'th' or 'td'.
style	string	optional		A class name to be applied to all cells in this column.
render	Table~RenderCallback	optional		A function to render each cell in this column.
editable	boolean	optional	false	Whether cells in this column are editable or not.
editorType	Table.EditorType	optional		The editor type to use, in edit mode, for cells in this column. If not specified then it will be autodetected based on column data type and additional column options provided.
checkedValue	*	optional		The value to set the cell data to if input type is checkbox and it is checked. Required if input type of checkbox is specified.
uncheckedValue	*	optional		The value to set the cell data to if input type is checkbox and it is not checked. Required if input type of checkbox is specified.
editorSelectOptions	Table~EditorOptionsCallback | Array.<PrimitiveType> | Object.<{string, PrimitiveType}> | Array.<{key: string, value: PrimitiveType}>	optional		Select input options as: editor options callback to generate the options on demand, plain array (values used for both title and value), key-value object (key as title, value as select value), array of objects (key property as title, value property as select value)
editorValidate	Table~EditorValidateCallback	optional		A callback to validate each cell edit in this column.
editorSave	Table~EditorSaveCallback	optional		Called after a cell has been edited and passes validation. Can be used to perform a save action for example.

Coordinate - { Object }

Properties:

Name	Type	Description
row	number	The row index
column	number	The column index

CoordinateTranslator ( coordinate ) → {Table~Coordinate}

Parameters:

Name	Type	Description
coordinate	Table~Coordinate	The visual coordinate

Returns:

Type	Description
Table~Coordinate

Back to Top

EditorOptionsCallback ( value, row ) → {Array.<PrimitiveType>|Object.<*, string>|Array.<{key: string, value: PrimitiveType}>}

Returns a list of editor options to display. Either an array of values to display and set or an object of keys to display values.

Parameters:

Name	Type	Description
value	PrimitiveType	Current value of the cell
row	Array.<PrimitiveType>	Current value for all cells in the row

Returns:

Type	Description
Array.<PrimitiveType> | Object.<*, string> | Array.<{key: string, value: PrimitiveType}>	The editor options

Example

function (value, row) {
    var list = [
        {key: '-1', value: 'None'},
        {key: '1', value: 'One'},
    ];

    // Show extended list of options if column 2 it true
    if (row[1]) {
        list = list.concat([
            {key: '2', value: 'Two'},
            {key: '3', value: 'Three'}
        ]);
    }

    return list;
},

Back to Top

EditorSaveCallback ( data, row, cell ) → {Promise}

Callback function triggered after a cell has been edited and validated successfully.

Parameters:

Name	Type	Description
data	PrimitiveType	The new value from the cell edit.
row	Array.<PrimitiveType>	An array of the underlying data from the row. This will include the original value for the cell that was edited.
cell	Element	The cell DOM Element.

Returns:

Type	Description
Promise	The save callback is treated as asynchronous as so should return a Promise that resolves on success or is rejected on failure.

Example

function save(columnName, data, row, cell) {
    // Get the index for the modified row
    var index = row.slice(0, 2);
    // Save to the server and wait for a success or failure response
    return new Promise(resolve, reject) {
        $.post('https://myhost', {
            column: columnName,
            value: data,
            index: index
        }).then(resolve, reject);
    });
}

var table = new insight.components.Table({
     id: 'table-1',
     columns: [
         {name: 'Index1'},
         {name: 'Index2'},
         {name: 'Column1', editable: true, editorSave: save.bind(table, 'Column1')},
         {name: 'Column2', editable: true, editorSave: save.bind(table, 'Column2')},
     ],
     data: [...]
 });

Back to Top

EditorValidateCallback ( data, row, cell ) → {Insight.validation.Result}

Callback function for cell validation.

Parameters:

Name	Type	Description
data	PrimitiveType	The new value from the edit.
row	Array.<PrimitiveType>	An array of the underlying data from the row.
cell	Element	The cell DOM Element.

Returns:

Type	Description
Insight.validation.Result	The validation result as a validation object.

Example

function column1Validation(value, row, cell) {
    var column2value = row[1];
    var result = new insight.validation.Result(true);
    if(value < 100 && column2value === 'STRICT') {
        result.isValid = false;
        result.errorMessage = 'Must be less that 100 if corresponding Column2 is set to STRICT';
    }
    // Build up a insight.validation.Result object with the validation outcome
    return result;
}

var table = new insight.components.Table({
     id: 'table-1',
     columns: [
         {name: 'Column1', editorValidate: column1Validation},
         {name: 'Column2'},
     ],
     data: [...]
 });

Back to Top

PasteHandler ( cellContent, topLeft ) → {undefined}

Parameters:

Name	Type	Description
cellContent	Array.<Array.<string>>	The string values to set, each element is a row
topLeft	Table~Coordinate	coordinates of start point in which to paste

Returns:

Type	Description
undefined

Back to Top

RenderCallback ( data, type, row ) → {string}

Callback function for custom rendering each cell in a Table column.

Parameters:

Name	Type	Description
data	array | object	The data for the cell (based on DataTables columns.dataDT)
type	string	The type call data requested - this will be 'filter', 'display', 'type' or 'sort'.
row	array | object	The full data source for the row (not based on DataTables columns.dataDT)

Returns:

Type	Description
string	A string containing the custom text and/or HTML markup for this item.

Example

function currencyCellFormatter(data, type, row) {
    // Format as US currency. Note it is up to you to html escape the display data returned when using the column render option.
    switch (type) {
        case 'display':
            return htmlEscape(insight.Formatter.formatNumber(data, '$#,##0.00'));
        case 'filter':
            return htmlEscape(insight.Formatter.formatNumber(data, '$0.00'));
    }
    return data;
}

var table = new insight.components.Table({
     id: 'table-1',
     columns: [
         {name: 'Index1'},
         {name: 'Column1', render: currencyCellFormatter},
         {name: 'Column2', render: currencyCellFormatter},
     ],
     data: [...]
 });

Back to Top

RowKeyGenerator ( data, rowPosition ) → {string}

Callback to generate a key for a row. This is used to find the current active row when a table is redrawn.

You will probably only want to include the fixed index cells of a row in the key and join them with a string token.

AutoTable will automatically generate a row key based on the non-filtered indices. Table, by default, will generate a row key based on all cells in the row.

Parameters:

Name	Type	Description
data	Array.<PrimitiveType>	Contents of each cell in the row
rowPosition	number	The row display position

Returns:

Type	Description
string	The generated key for the row

Example

// If the first 2 columns in the table are fixed, index values
function generateRowKey(data, position) {
  return JSON.stringify(data.slice(0, 1));
}

Back to Top

Events

selection-changed

Selection changed event. Triggered whenever the selection is changed, e.g. when user creates new selection. This event is triggered on the table element. Event handler also receives context of the selection, which includes selection cell list, active cell and selection type.

• Type:
• object

Properties:

Name	Type	Description
selection	Array.<Table#Cell>	an array of table cells representing selection
activeCell	Table#Cell	currently active table cell
selectionType	string	selection type

Example

$('#table-id').on('selection-changed', function (event, context) {
  console.log(context.activeCell);
});

Back to Top

selection-removed

Selection removed event. Triggered whenever the selection is destroyed, e.g. when sorting and filtering. This event is triggered on the table element.

Example

$('#table-id').on('selection-removed', function (event) {
  console.log(event.type);
});

Back to Top