TurboGrid

Methods Data Options Events Lifecycle

turbogrid


                            // global
                            var TG = window.turbogrid;
                            var { Grid, Util } = window.turbogrid;
                            // cjs
                            var TG = require("turbogrid");
                            var { Grid, Util } = require("turbogrid");
                            // esm
                            import TG from "turbogrid";
                            import { Grid, Util } from "turbogrid";

Grid(container)

Grid constructor, creates a new grid instance with container.


                            //selector
                            var grid = new Grid(".container");
                            //or element
                            var container = document.querySelector(".container");
                            var grid = new Grid(container);
                            //or options with container
                            var grid = Grid({
                                container,
                                ... other options
                            });

Methods

setData(data)

For Detailed data structure, check data structure


                            grid.setData({
                                columns: [],
                                rows: []
                            });

getData()

Returns current data.


                            var data = grid.getData();

setOption(options)

For Detailed options, check default options


                            //set multiple options
                            grid.setOption({
                                optionKey1: optionValue1,
                                optionKey2: optionValue2
                            });
                            //set single option
                            grid.setOption(optionKey, optionValue);

getOption([name])

Returns current options by name or all options.


                            //get all options
                            var options = grid.getOption();
                            //get single option
                            var optionValue = grid.getOption(optionKey);

setFormatter(formatters)

Set or customize Grid formatters.


                            //set multiple formatters
                            grid.setFormatter({
                                string: function(value, rowItem, columnItem, cellNode) {
                                    return value;
                                }
                            });

                            //set single formatter
                            grid.setFormatter("string", formatterHandler);

default cell formatter: string, number, date, icon, blank, checkbox, tree, null

default header formatter: header

Formatter arguments:


                            function(value, rowItem, columnItem, cellNode) { 
                                // value is formatted by null formatter
                                // get original value:
                                var originalValue = rowItem[columnItem.id];
                                var rowIndex = rowItem.tg_index;
                                var columnIndex = columnItem.tg_index;
                                // using default formatter returns:
                                var defaultFormatter = this.getDefaultFormatter("[formatter-name]");
                                return defaultFormatter(value + " new text", rowItem, columnItem, cellNode)
                            }

Demo Formatter

getFormatter(type)

Returns type specified formatter(Function).


                            var stringFormatter = grid.getFormatter("string");

getDefaultFormatter([type])

Returns type specified default formatter(Function).


                            var treeFormatter = grid.getDefaultFormatter("tree");

bind(eventType, handler)

Attach a handler to an event for Grid. See all event types.


                            grid.bind("onUpdated", function(e, d){
                                //console.log(d);
                            });

Demo Events

once(eventType, handler)

Attach a handler to an event. The handler is executed at most once per event type. It will be removed once it triggers for the first time.


                            grid.once("onUpdated", function(e, eventData){
                                //console.log(eventData);
                            });

unbind([eventType][, handler])

Remove a previously-attached event handler from Grid.


                            grid.unbind();
                            grid.unbind("onUpdated");
                            grid.unbind("onUpdated", handler);

trigger(eventType, eventData)

Execute all handlers attached to Grid for an event.


                            this.trigger(eventType, eventData);

getAllEvents()

Returns all event types.


                            var allEventTypes = grid.getAllEvents();

Demo Events

render()


                            grid.render();

resize([w, [h]])


                            grid.resize();
                            grid.resize(600, 400);

Demo Resize

destroy()


                            grid.destroy();

getColumnItem(columnIndex) getRowItem(rowIndex)

Different data types of the rowIndex/columnIndex parameter are supported :

If parameter type is Number, grid will search the row/column item by index. (recommend, highest performance)
If parameter type is String, grid will iterates all items to match the row/column id.
If parameter type is Object, grid will look at the object properties:

If there is a tg_index property inside the object, grid will search the row/column item by index. (higher priority)
if there is an id property (type of string), grid will iterates all items to match the row/column id.


                            var columnItem = grid.getColumnItem(columnIndex);
                            var rowItem = grid.getRowItem(rowIndex);
                            var rowItem = grid.getRowItem(123);
                            var rowItem = grid.getRowItem("id_123");
                            var rowItem = grid.getRowItem({
                                tg_index: 123
                            });
                            var rowItem = grid.getRowItem({
                                id: "id_123"
                            });

showLoading() hideLoading() setLoading(loading)


                            grid.showLoading();
                            grid.hideLoading();
                            grid.setLoading("Loading ...");
                            grid.setLoading(function(container) {
                                return document.createElement("div");
                            });

Demo Show/Hide Loading

expandAllRows() collapseAllRows() toggleAllRows()


                            grid.expandAllRows();
                            grid.collapseAllRows();
                            grid.toggleAllRows();

Demo Row Collapse/Expand

expandRow(rowIndex) collapseRow(rowIndex) toggleRow(rowIndex)


                            grid.expandRow(rowIndex);
                            grid.collapseRow(rowIndex);
                            grid.toggleRow(rowIndex);

Demo Row Collapse/Expand

expandRowLevel(level)


                            grid.expandRowLevel(level);

Demo Row Collapse/Expand

exportData([keysSettings])

Returns all columns and rows data without private properties or by keysSettings.


                            var exportedData = grid.exportData();
                            var exportedData = grid.exportData({
                                the_key_need: true,
                                key_key_no_need: false
                            });

Demo Export

setRowHeight(rowIndex, height)

Dynamic set row(s) height


                            grid.setRowHeight(rowIndex, height);
                            grid.setRowHeight([rowIndex1, rowIndex2], height);
                            grid.setRowHeight([rowIndex1, rowIndex2], [height1, height2]);

Demo Row Height and Infinite Scroll

setRowSubs(rowIndex, subs)


                            var subs = [{name:"row1"},{name:"row2"}];
                            grid.setRowSubs(rowIndex, subs);

Demo Dynamic Load Subs

setRows(rowList)


                            var rows = [{name:"row1"},{name:"row2"}];
                            grid.setRows(rows);

Demo Dynamic Set Rows

addRow(rowInfo[, parent, position, scrollTo = true]) deleteRow(rowIndex)


                            grid.addRow({
                                id: "id1",
                                name: "row item"
                            });
                            grid.addRow(["Row 1", "Row 2"]);
                            grid.addRow(["Row 1", "Row 2"], parentIndex);
                            grid.addRow("Row Before","level_0", 0);
                            grid.deleteRow(2);
                            grid.deleteRow([1, 2]);

Demo Row Add/Delete

moveRowsToTop(rowList) moveRowsUp(rowList) moveRowsDown(rowList) moveRowsToBottom(rowList) moveSelectedRowsToTop() moveSelectedRowsUp() moveSelectedRowsDown() moveSelectedRowsToBottom() moveRows(rowList, offset)

offset: if < 0 move up; if > 0 move down


                            grid.moveRowsToTop(["row_id1", "row_id2"]);
                            grid.moveRowsUp(["row_id1", "row_id2"]);
                            grid.moveRowsDown(["row_id1", "row_id2"]);
                            grid.moveRowsToBottom(["row_id1", "row_id2"]);
    
                            grid.moveSelectedRowsToTop();
                            grid.moveSelectedRowsUp();
                            grid.moveSelectedRowsDown();
                            grid.moveSelectedRowsToBottom();

                            grid.moveRows(["row_id"], -1);
                            grid.moveRows(["row_id"], -2);
                            grid.moveRows("row_id", 1);

Demo Row Move

selectAll()


                            grid.selectAll();
                            grid.selectAll(false);

Demo Row Select

setRowSelected(rowIndex)


                            grid.setRowSelected(rowIndex);
                            grid.setRowSelected(rowIndex, false);
                            grid.setRowSelected();

Demo Row Select

getSelectedRow() getSelectedRows()

Returns a list for multiple selection


                            var selectedRow = grid.getSelectedRow();
                            var selectedRows = grid.getSelectedRows();

Demo Row Select

setRowHover(rowIndex, hover)

hover: true or false


                            grid.setRowHover(rowIndex, true);
                            grid.setRowHover(rowIndex, false);

Demo Frozen Middle

setSortColumn(sortColumn) removeSortColumn()

Remove sort state if data changed


                            grid.setSortColumn(sortColumn);
                            grid.removeSortColumn();

Demo Row Sort

setColumnWidth(columnIndex, width)

Dynamic set column width, minWidth/maxWidth could be updated


                            grid.setColumnWidth(columnIndex, width);

Demo Column Width Resize

showColumn(columnIndex) hideColumn(columnIndex)


                            grid.showColumn(columnIndex);
                            grid.hideColumn(columnIndex);
                            grid.showColumn([1, 3]);
                            grid.hideColumn([1, 3]);

Demo Show/Hide Column

addColumn(columnInfo[, parent, position, scrollTo = true]) deleteColumn(columnIndex)


                            grid.addColumn({
                                id: "id1",
                                name: "column item"
                            });
                            grid.addColumn(["Column 1", "Column 2"]);
                            grid.addColumn(["Column 1", "Column 2"], parentIndex);
                            grid.addColumn("Column Before","level_0",0);
                            grid.deleteColumn(2);
                            grid.deleteColumn([1, 2]);

Demo Column Add/Delete

scrollToRow(rowIndex) scrollToFirstRow() scrollToLastRow() scrollToColumn(columnIndex) scrollToFirstColumn() scrollToLastColumn(end) scrollToCell(rowIndex, columnIndex)


                            grid.scrollToRow(rowIndex);
                            grid.scrollToColumn(columnIndex);
                            grid.scrollToCell(rowIndex, columnIndex);

Demo Scroll

scrollRowIntoView(rowIndex) scrollColumnIntoView(columnIndex) scrollCellIntoView(rowIndex, columnIndex)


                            grid.scrollRowIntoView(rowIndex);
                            grid.scrollColumnIntoView(columnIndex);
                            grid.scrollCellIntoView(rowIndex, columnIndex);

Demo Scroll

setScrollTop(top) setScrollLeft(left) getScrollTop() getScrollLeft()


                            grid.setScrollTop(200);
                            grid.setScrollLeft(200);
                            var st = grid.getScrollTop();
                            var sl = grid.getScrollLeft();

Demo Scroll

updateRow(rowIndex[, rowData]) updateCell(rowIndex, columnIndex[, cellValue])


                            grid.updateRow(rowIndex);
                            grid.updateRow(rowIndex, rowData);
                            grid.updateCell(rowIndex, columnIndex);
                            grid.updateCell(rowIndex, columnIndex, cellValue);

Demo Flush

getScrollbarWidth()

Returns 0 or scrollbarSize if has vertical scrollbar (hasVScroll)

getScrollbarHeight()

Returns 0 or scrollbarSize if has horizontal scrollbar (hasHScroll)


                            var sbw = grid.getScrollbarWidth();
                            var sbh = grid.getScrollbarHeight();

getScrollViewWidth() getScrollViewHeight()

Scroll View size = Scroll Pane size - Scrollbar size


                            var svw = grid.getScrollViewWidth();
                            var svh = grid.getScrollViewHeight();

getScrollPaneWidth() getScrollPaneHeight()

Scroll Pane size = Scroll View size + Scrollbar size


                            var spw = grid.getScrollPaneWidth();
                            var sph = grid.getScrollPaneHeight();

getRowsLength(total)

Total rows length. default total is false; total is true means including collapsed/filtered rows;


                            var len = grid.getRowsLength();
                            var totalLen = grid.getRowsLength(true);

getRowsHeight()

Total rows height


                            var totalHeight = grid.getRowsHeight();

getRowHeight(rowIndex)


                            var rowHeight = grid.getRowHeight(rowIndex);

getViewport()

Returns current the index list of visible rows and columns.


                            var viewport = grid.getViewport();
                            // { rows, columns }

find(selector)


                            var nodes = grid.find(".selector-name");

getCellNode(rowIndex, columnIndex)


                            var cellNode = grid.getCellNode(rowIndex, columnIndex);

getHeaderItemNode(columnIndex)


                            var headerItemNode = grid.getHeaderItemNode(columnIndex);

getColumnHeaderNode(columnIndex)


                            var columnHeaderNode = grid.getColumnHeaderNode(columnIndex);

forEachColumn(callback) forEachRow(callback)

Executing a function for each column/row.


                            grid.forEachColumn(function(column, index, parent) {
                                //
                            });
                            grid.forEachRow(function(row, index, parent) {
                                //
                            });

isRowSelectable(rowItem)


                            var rowItem = grid.getRowItem(rowIndex);
                            if (grid.isRowSelectable(rowItem)) {
                                console.log("selectable");
                            }

isRowLeaf(rowItem)

Returns true or false.

onNextUpdated(handler)

Attach a handler to onUpdated event and the handler is executed at most once.


                            grid.onNextUpdated(function(e, eventData){
                                //console.log(eventData);
                            });

Data

Both columns and rows are same data structure (JSON/Tree-like):


                                    [{
                                        name: "item 1",
                                        subs: [{
                                            name : "item 2",
                                            subs: [{
                                                name : "item 3",
                                                subs: [{
                                                    ...
                                                }]
                                            }, ...]
                                        }, ...]
                                    }, ...]


                            var data = {
                                columns : [...],
                                rows : [...]
                            };
                            grid.setData(data);

columns

See column available properties: columnProps


                            var columns = [{
                                id:"c1",
                                type : "string",
                                name:"Column Name 1"
                            }, {
                                id : "c2",
                                type : "number",
                                name : "Column Name 2"
                            }, {
                                id: "c3",
                                name: "Column Name 3",
                                subs: [{
                                    id: "c3_s1",
                                    name: "Column Name 3-1"
                                }, {
                                    id: "c3_s2",
                                    name: "Column Name 3-2"
                                }]
                            }];

rows

See row available properties: rowProps


                            var rows = [{
                                id : "r1",
                                name : "Row Name 1",
                                c1 : "string value 1",
                                c2 : 1,
                                c3_s1 : "value 3 - 1",
                                c3_s2 : "value 1 - 2"
                            }, {
                                id : "r2",
                                type : "group",
                                name : "Row Name 2",
                                c1 : "string value 2",
                                c2 : "value 2",
                                c3_s1 : "value 3 - 1",
                                c3_s2 : "value 1 - 2",
                                subs : [{
                                    id : "r3",
                                    type : "holding",
                                    name : "Row Name 3",
                                    c1 : "string value 3",
                                    c2 : 3,
                                    c3_s1 : "value 3 - 1",
                                    c3_s2 : "value 1 - 2"
                                }]
                            }];

options

Sets options from data (The priority is higher than "setOption")


                            var data = {
                                options : {
                                    sortField : "name"
                                },
                                columns : columns,
                                rows : rows
                            };
                            grid.setData(data);

rowsLength

Dynamic load rows data. No rows data but require total length of rows.


                                var data = {
                                    columns: columns,
                                    rowsLength: 50000
                                };
                                grid.setData(data);

Demo Dynamic Load Rows

Options

className = "tg-turbogrid"

Customize className (CSS namespace).


                        grid.setOption({
                            className: "my-grid-class-name"
                        });

theme = "[theme-name]"

Sets theme name: (default), lightblue, dark

Demo Theme

rowHeight = 23

Demo Row Height

rowCacheLength = 0 columnCacheLength = 0

Demo Row/Column Cache

autoHeight = false

Demo Auto Height

headerVisible = true

Demo Show/Hide Header

collapseAllVisible = true collapseAllOnInit = null

Demo Row Collapse/Expand

selectVisible = false selectAllVisible = true selectAllOnInit = null

true: select all, false: unselect all, or do nothing

selectMultiple = true

Demo Row Select

rowNumberVisible = false

false: no number, true: show number column

Demo Row Number

rowNotFound = ''

empty; string; element; or function

Demo Row Not Found

rowDragCrossLevel = true

boolean or a handler function, returns a specified drop list

Demo Row Drag

rowMoveCrossLevel = true

true: multi-level move, false: single level move

Demo Row Move

sortField = ""

Field for value compare

sortAsc = true

true: for ascending sort, false: for descending sort

sortBlankValueBottom = true

Configuration for sort blank value logic

true: rows with blank values should always be at the bottom of the grid

false: rows with blank values sort at the bottom for descending sort and at the top for ascending sort

sortOnInit = false

Sets true will sort by sortField on initialized

sortIndicator = "h"

"h" or "v" style

sortComparers = {defaultSortComparers}

Customize own sort comparers

Demo Row Sort

rowFilter

Demo Row Filter

rowProps =


                                {

                                    //selected: Boolean
                                    //collapsed: Boolean
                                
                                    //selectable : true
                                    //exportable: true
                                
                                    //sortFixed: [Boolean, String "top"]
                                
                                    // customize row style
                                    //classMap : [String, Array, Object]
                                    //styleMap : [String, Array, Object]
                                    //[columnId]ClassMap: [String, Array, Object]
                                    //[columnId]StyleMap: [String, Array, Object]
                                
                                    // row type for class name: group
                                    //type: String
                                
                                    //formatter: [String, Function]
                                
                                    //height: Number
                                
                                    //subs: Array
                                }

columnProps =


                                {

                                    // require for showing header
                                    name: '',

                                    // for getting row value
                                    //id: String

                                    // expect to be a string, for example: "string", "number", "date" etc.
                                    //type: String

                                    // formatter expect to be a function, but also can be a string like type
                                    // priority is higher than type
                                    // be used for cell formatting
                                    //formatter: [String, Function]
                                    //headerFormatter: [String, Function]

                                    // comparer function when sort function(a, b, options)
                                    //comparer: [String, Function]

                                    // left (default) | center | right
                                    //align: String

                                    // customize column style
                                    //classMap: [String, Array, Object]
                                    //styleMap: [String, Array, Object]
                                    //headerClassMap: [String, Array, Object]
                                    //headerStyleMap: [String, Array, Object]

                                    //sortable: true
                                    //resizable: true
                                    //exportable: true

                                    //private: false

                                    // require for column resize
                                    minWidth: 81,
                                    maxWidth: 300

                                    //width: Number
                                    //height: Number

                                    //subs: Array
                                    
                                }

frozenColumn = -1 frozenRow = -1 frozenBottom = false frozenColumnMax = 10 frozenRowMax = 10 frozenRowHoverable = false

Boolean, Allow hovering on frozen row

Demo Frozen

scrollbarSize = 12

Sets scrollbar size

scrollbarRound = false

Sets scrollbar round style

scrollbarFade = false

Sets scrollbar fade

scrollbarFadeTimeout = 1000

Sets scrollbar fade timeout

scrollbarType = "auto"

Sets scrollbar type: auto, mobile (fade = true and size = 6)

scrollPaneMinWidth = 30

Sets scroll pane min width

Demo Scrollbar

textSelectable = false

Boolean, Allow select text

bindWindowResize = false

Boolean, Bind window resize and call resize API

bindContainerResize = false

Boolean, Bind container resize and call resize API (require API ResizeObserver)

Demo Resize

Events

Event Type	Event Data	Example
onUpdated onFirstUpdated	`Object: viewport`	Demo Events
onHeaderUpdated	`Object: { node: headerNode }`	Demo Events
onSort	`Object: { e, columnItem, node: headerItemNode }`	Demo Sort
onColumnAdded onColumnRemoved	`Array: [columnItem ...]`	Demo Column Add/Delete
onColumnWidthChanged	`Object: columnItem`	Demo Events
onRowAdded onRowRemoved	`Array: [rowItem ...]`	Demo Row Add/Delete
onRowExpanded onRowCollapsed	`Object: rowItem`	Demo Events
onRowSubsRequest	`Object: rowItem`	Demo Dynamic Load Subs
onRowDragged	`Object: { e, rowItem }`	Demo Row Drag
onRowDropped	`Object: { rowItem, dragFrom, dragIndex, dropInto, dropIndex }`	Demo Row Drag
onRowMoved	`Array: [rowItem ...]`	Demo Row Move
onRowMouseEnter onRowMouseLeave	`Object: { e, rowItem }`	Demo Events
onSelectChanged	`Array [rowItem ...]`	Demo Row Select
onCellUpdated	`Object: { value, rowItem, columnItem, node: cellNode }`	Demo Events
onCellMouseEnter onCellMouseLeave	`Object: { e, rowItem, columnItem, rowNode, cellNode }`	Demo Events
onClick onDblClick onContextMenu onMouseOver onMouseOut	`//on header Object: { e, columnItem, headerNode } //on body Object: { e, rowItem, columnItem, rowNode, cellNode }`	Demo Events
onTouchStart onTouchMove onTouchEnd	`//on header Object: { e, columnItem?, headerNode? } //on body Object: { e, rowItem?, columnItem?, rowNode?, cellNode? }`	Demo Touch
onScroll	`Object: { scrollLeft, scrollTop }`	Demo Scroll
onScrollStateChanged	`Object: { hasHScroll, hasVScroll }`	Demo Events
onMouseWheel	`Object: { e, deltaX, deltaY }`	Demo Scroll
onResize	`Object: { previous: Object, width: Number, height: Number }`	Demo Resize
onLayout	`Object: { previous: Object, headerWidth: Number, headerHeight: Number, bodyWidth: Number, bodyHeight: Number }`	Demo Resize
onKeyDown	`Object: { e }`	Demo Events
onDestroy	N/A	Demo Flush

Lifecycle

Phases	Sub Phases		Payload	Capacity
create	create style and html in the container set data set options set formatters add events		low	loading APIs	`var grid = new Grid(container); grid.setData(data); grid.setOption(options); grid.setFormatter(formatters); grid.bind("[event type]", handler);`
render	init options		low	all APIs	`grid.render(); grid.rerender();`
	render header		middle
	render body	render rows	middle
	render body	render cells	high
update	update body update row(s) update cell(s)				`grid.update(); grid.updateRow(rowIndex, rowData); grid.updateCell(rowIndex, columnIndex, cellValue);`
destroy	remove all		low	none	`grid.destroy();`

The "tg" is Grid prefix or namespace.

CSS className:


                            .tg-pane {}
                            .tg-body{}
                            .tg-row{}
                            .tg-cell{}

Private property:


                            //rowItem.tg_index
                            //rowItem.tg_level
                            //rowItem.tg_group

The private properties will be removed when exportData()