Table

Method summary

Members

members

EditorType - {

type

string }

Enum for the table editor types that are supported.

details

Properties:

properties

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

members

dataTable - {

type

jQuery }

A reference to the underlying DataTable object.

details

Methods

method

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

Add new row to the table using specified data.

Parameters:

params

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

details

Returns:

returns table

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

Back to Top

method

destroy ( )

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

details

Back to Top

method

draw ( )

Draw the table.

details

Back to Top

method

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

Get row or cell data.

Parameters:

params

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

details

Returns:

returns table

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

Back to Top

method

isLocked ( ) → {boolean}

Check if the table is locked.

details

Returns:

returns table

Type	Description
type boolean	Whether the table is locked or not

Back to Top

method

lock ( overlayMessage )

Lock the table from being able to perform edit actions.

Parameters:

params

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

details

Back to Top

method

numRows ( ) → {number}

Count number of rows in a table.

details

Returns:

returns table

Type	Description
type number	The number of rows present

Back to Top

method

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

Remove a specified row from the table.

Parameters:

params

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

details

Returns:

returns table

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

Back to Top

method

setEditing ( enabled )

Set edit mode on or off.

Parameters:

params

Name	Type	Description
enabled	type boolean	Whether edit mode should be enabled

details

Back to Top

method

unlock ( )

Unlock the table so that editing can resume.

details

Back to Top

method

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

Update a specified row or cell with new data.

Parameters:

params

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

details

Returns:

returns table

Type	Description
type number	0 on success, 1 on error

Back to Top

Type Definitions

members

Cell - {

type

object }

details

Properties:

properties

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

members

DisplayPosition - {

type

object }

details

Properties:

properties

Name	Type	Description
row	type number	row index
column	type number	column index

members

ColumnOptions - {

type

Object }

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

details

Properties:

properties

Name	Type	Argument	Default	Description
name	type string			The title to be displayed for this column.
width	type string	optional		The column width. Takes any valid css value for defining width.
type	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	type 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	type boolean	optional	true	Show or hide the column. Defaults to visible.
cellType	type string	optional	'td'	Specify the type of cell to use for this column. Either 'th' or 'td'.
style	type string	optional		A class name to be applied to all cells in this column.
render	type Table~RenderCallback	optional		A function to render each cell in this column.
editable	type boolean	optional	false	Whether cells in this column are editable or not.
editorType	type 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	type *	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	type *	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	type 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	type Table~EditorValidateCallback	optional		A callback to validate each cell edit in this column.
editorSave	type Table~EditorSaveCallback	optional		Called after a cell has been edited and passes validation. Can be used to perform a save action for example.

members

Coordinate - {

type

Object }

details

Properties:

properties

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

method

CoordinateTranslator ( coordinate ) → {Table~Coordinate}

Parameters:

params

Name	Type	Description
coordinate	type Table~Coordinate	The visual coordinate

details

Returns:

returns table

Type	Description
type Table~Coordinate

Back to Top

method

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:

params

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

details

Returns:

returns table

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

Example

examples

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

method

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

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

Parameters:

params

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

details

Returns:

returns table

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

Example

examples

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

method

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

Callback function for cell validation.

Parameters:

params

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

details

Returns:

returns table

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

Example

examples

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

method

PasteHandler ( cellContent, topLeft ) → {undefined}

Parameters:

params

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

details

Returns:

returns table

Type	Description
type undefined

Back to Top

method

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

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

Parameters:

params

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

details

Returns:

returns table

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

Example

examples

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

method

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:

params

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

details

Returns:

returns table

Type	Description
type string	The generated key for the row

Example

examples

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

method

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:
• type
  object

details

Properties:

properties

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

Example

examples

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

Back to Top

method

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.

details

Example

examples

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

Back to Top