Old Documentation

You are browsing documentation for an old version of Tabulator. Consider upgrading your project to Tabulator 6.3

Updating Data

Overview
Altering Data
Retrieving Data
Row Manipulation

Overview

Once you have loaded data into your table, Tabulator provides a wide variety of methods for updating and manipulating that data.

The replaceData function lets you silently replace all data in the table without updating scroll position, sort or filtering, and without triggering the ajax loading popup. This is great if you have a table you want to periodically update with new/updated information without alerting the user to a change.

It takes the same arguments as the setData function, and behaves in the same way when loading data (ie, it can make ajax requests, parse JSON etc)

table.replaceData([{id:1, name:"bob", gender:"male"}, {id:2, name:"Jenny", gender:"female"}]) //load data array

table.replaceData("/data.php") //load data from data/php via ajax request

table.replaceData() //trigger reload of ajax data from ajaxURL property

Returned Promise

The replaceData method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.replaceData(tableData)
.then(function(){
    //run code after table has been successfully updated
})
.catch(function(error){
    //handle error loading data
});

Note The replaceData function will only maintain scroll position when the Vitrual DOM has been enabled by setting a height on the table.

Updating Existing Data

If you want to update an existing set of data in the table, without completely replacing the data as the setData method would do, you can use the updateData method.

This function takes an array of row objects and will update each row based on its index value. Options without an index will be ignored, as will items with an index that is not already in the table data. The addRow function should be used to add new data to the table.

table.updateData([{id:1, name:"bob", gender:"male"}, {id:2, name:"Jenny", gender:"female"}]);

The function will not replace the rows with the provided data, it will only update any of the provided parameters.

//data before update {id:1, name:"Steve", gender:"male", age:20}

table.updateData([{id:1, name:"bob"}]); //update data

//data after update  = {id:1, name:"bob", gender:"male", age:20}

Returned Promise

The updateData method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.updateData([{id:1, name:"bob"}])
.then(function(){
    //run code after data has been updated
})
.catch(function(error){
    //handle error updating data
});

Adding Data

You can add a data to the existing table data using the addData function.

The first argument should be an array of row data objects. If you do not pass data for a column, it will be left empty.

The second argument is optional and determines whether the data is added to the top or bottom of the table. A value of true will add the data to the top of the table, a value of false will add the data to the bottom of the table. If the parameter is not set the data will be placed according to the addRowPos global option.

table.addData([{id:1, name:"bob", gender:"male"}, {id:2, name:"Jenny", gender:"female"}], true);

By default any new rows will be added to the bottom of the table, to change this to the top set the addRowPos option to "top";

If you want to insert the data next to an existing row you can pass an optional third argument to the function that will position the new rows next to the specified row (above or below based on the value of the second argument). This argument will take any of the standard row component look up options:

table.addData([{id:6, name:"bob", gender:"male"}, {id:7, name:"Jenny", gender:"female"}], true, 3); //add new data above existing row with index of 3

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to the new data before the data is added. (see Mutators for more details)

Returned Promise

The addData method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.addData([{id:1, name:"bob", gender:"male"}, {id:2, name:"Jenny", gender:"female"}], true)
.then(function(rows){
    //rows - array of the row components for the rows updated or added

    //run code after data has been updated
})
.catch(function(error){
    //handle error updating data
});

Update or Add Data

If the data you are passing to the table contains a mix of existing rows to be updated and new rows to be added then you can call the updateOrAddData function. This will check each row object provided and update the existing row if available, or else create a new row with the data.

table.updateOrAddData([{id:1, name:"bob"}, {id:3, name:"steve"}]);

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to the new data before the table is updated. (see Mutators for more details)

Returned Promise

The updateOrAddData method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.updateOrAddData([{id:1, name:"bob"}, {id:3, name:"steve"}])
.then(function(rows){
    //rows - array of the row components for the rows updated or added

    //run code after data has been updated
})
.catch(function(error){
    //handle error updating data
});

Emptying the Table

You can remove all data from the table using the clearData function:

table.clearData();

Retrieving Data

Row Data

Retrieve All Data

You can retrieve the data stored in the table using the getData function.

var data = table.getData();

This will return an array containing the data objects for each row in the table.

By default getData will return an array containing all the data held in the Tabulator. You can restrict the data returned by passing a Row Range Lookup value into the function:

var data = table.getData("active"); //return currently filtered data

Retrieve Count of Number of Rows

You can retrieve the a count of the number of rows stored in the table using the getDataCount function.

var rowCount = table.getDataCount();

By default getDataCount will count all rows held in the Tabulator. You can restrict this by passing a Row Range Lookup value into the function:

var rowCount = table.getDataCount("active"); //count only rows that pass the currently filtered data

Retrieve Row Data

To retrieve the data of a specific row, you can retrieve the Row Component with the getRow function, then use the getData function on the component. The first argument is the row you are looking for, it will take any of the standard row component look up options.

var row = table.getRow(1); //return row component with index of 1
var rowData = row.getData();

Data Accessors
If you have defined any accessors on your columns, then these will be applied to the data before the data is returned from any of the above functions. (see Accessors for more details)

Retrieving Row Components

You can retrieve all the row components in the table using the getRows function.

var rows = table.getRows();

This will return an array containing the Row Component for each row in the table.

By default getRows will return an array containing all the data held in the Tabulator. You can restrict the data returned by passing a Row Range Lookup value into the function:

var rows = table.getRows("active"); //return currently filtered rows

Search Data

Search functions allow you to retrieve data using filters, exactly like those used by the setFilter function, any matching data or row components are then returned.

Search for Row Components

The searchRows function allows you to retrieve an array of row components that match any filters you pass in. it accepts the same arguments as the setFilter function.

var rows = table.searchRows("age", ">", 12);//get row components for all rows with an age greater than 12

Search for Row Data

The searchData function allows you to retrieve an array of table row data that match any filters you pass in. it accepts the same arguments as the setFilter function.

var data = table.searchData("age", ">", 12);//get row data for all rows with an age greater than 12

Row Position

Find Row Position In Table

Use the getRowPosition function to retrieve the numerical position of a row in the table. This position number is the same as the value shown in the rownum formatter and starts at 1

The first argument is the row you are looking for, it will take any of the standard row component look up options.

var position = table.getRowPosition(row); //return the position of the row in the filtered/sorted data

This function will only return the position of a row currently displayed in the table. if the row is currently filtered out or is part of a collapsed group or data tree, this will return a value of false

Get Row From Position In Table

You can retrieve the Row Component of a row at a given position in the table using getRowFromPosition function. By default this will return the row based in its position in all table data, including data currently filtered out of the table.

var row = table.getRowFromPosition(5); //return 5th row in the visible table data

Retrieve data as HTML Table

HTML Export functionality is provided by the Export Module

You can retrieve the table data as a simple HTML table using the getHtml function.

var htmlTable = table.getHtml();

This will return a HTML encoded string of the table data.

Table Contents

By default the output of the getHtml will contain column header groups, row groups, data trees and column calculations.

You can choose to remove any of the components from the output globally by setting the values in the htmlOutputConfig option in the table definition:

var table = new Tabulator("#example-table", {
    htmlOutputConfig:{
        columnHeaders:false, //do not include column headers in HTML table
        columnGroups:false, //do not include column groups in column headers for HTML table
        rowHeaders:false, //do not include row headers in HTML table
        rowGroups:false, //do not include row groups in HTML table
        columnCalcs:false, //do not include column calcs in HTML table
        dataTree:false, //do not include data tree in HTML table
        formatCells:false, //show raw cell values without formatter
    },
});

Field Data
It is worth noting that only columns with a field set in their definitions will be included in the output, this is because exports are generated from table data, and if a column has no field it has no data.

Function Arguments

By default, the getHtml function used to return a table containing all the active rows in the table (matching filters and sorts).

There are three arguments that can be passed into the function to configure the output. The first argument is Row Range Lookup value that determines which rows are included in the HTML table, by default this is "active".

The second argument is a boolean that determines if the output of the function should be styled to match the table (true) or be a blank html table (false), by default this is false

The third argument takes an object that can be used to override the object set on the htmlOutputConfig property

var htmlTable = table.getHtml("visible", true, {columnGroups:false}); //get styled html for visible rows of table that copies the table style without grouped column headers

Change Column Title in HTML Output

You can add a custom column title to be used in the HTML data instead of the usual title by setting the HtmlOutput property in the column definition object:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Name", field:"name", HtmlOutput:"Full Name"} //change column title to "Full Name" in html output
    ]
});

Accessors

You can use the accessorHtmlOutput and accessorHtmlOutputParams options on a column definition to alter the value of data in a column before the html is generated.

The example below will transform all ages into a boolean, showing if they are over 18 or not. The accessorHtmlOutputParams is used to pass the age limit to the accessor so the same accessor function can be used on multiple columns with different age limits:

var ageAccessor = function(value, data, type, params, column){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", accessorHtmlOutput:ageAccessor, accessorHtmlOutputParams:{legalAge:18} }

Full details of how accessors work can be found in the Accessors Documentation.

Cell Formatters

When the getHtml function is called you may want to apply a different formatter from the one usualy used to format the cell, you can do this using the formatterHtmlOutput column definition option.

You can use the formatterHtmlOutputParams to pass in any additional params to the formatter

These properties take the same inputs as the standard formatter property

//define html formatter
function htmlFormatter(cell, formatterParams, onRendered){
    return cell.getValue() ? "YES" : "NO";
}

//column definition
{title:"Driver", field:"driver", formatter:"tickCross", formatterHtmlOutput:htmlFormatter} //show "YES"/"NO" in the cell when the getHtml function is called

Passing a value of false into the formatter will cause the value to be shown as plain text without a formatter

Row Formatter

When the getHtml function is called you may want to apply a different formatter may want to apply a different formatter from the one usualy used to format the row. You can now do this using the rowFormatterHtmlOutput table option, which takes the same inputs as the standard rowFormatter property.

var table = new Tabulator("#example-table", {
    rowFormatter:function(row){
        //row - row component

        var data = row.getData();

        if(data.col == "blue"){
            row.getElement().style.backgroundColor = "#1e3b20";
        }
    },
    rowFormatterHtmlOutput:function(row){
        //row - row component

        var data = row.getData();

        if(data.col == "blue"){
            row.getElement().style.backgroundColor = "#0000ff"; //use a different shade of blue background when the getHtml function is called
        }
    },
});

Passing a value of false into the formatter prevent the default row formatter from being run ont the output table

Group Header

When the getHtml function is called you may want to apply a different group header from the one usualy used in the table. You can now do this using the groupHeaderHtmlOutput table option, which takes the same inputs as the standard groupHeader property.

var table = new Tabulator("#example-table", {
    groupHeader: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
    },
    groupHeaderHtmlOutput: function(value, count, data, group){
        return value + "<span style='color:#d00; margin-left:10px;'></span>";
    },
});

Passing a value of false into groupHeaderHtmlOutput will cause the header to show the groups key as plain text

Column Visibility

If you don't want to show a particular column in the HTML output you can set the htmlOutput property in its column definition object to false:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Hidden Column", field:"secret", htmlOutput:false} //hide data in HTML
    ]
});

You can also force a hidden column to be visibile in the HTML output by setting the htmlOutput property in its column definition object to true:

var table = new Tabulator("#example-table", {
    columns:[
        {title:"Hidden Column", field:"secret", visible:false, htmlOutput:true} //show hidden column in HTML
    ]
});

For more complex usage cases you can pass a callback function to the htmlOutput option, this will be called just before the html output is generated. The function will be passed the Column Component of its column as the first argument and should return a boolean indicating the columns visibility.

var table = new Tabulator("#example-table", {
    columns:[
        {title:"id", field:"id", htmlOutput:function(column){
            //column - column component for current column

            return true; //make column visible in html output
        }} 
    ]
});

Row Manipulation

There are a number of ways to manipulate individual rows in the table without affecting any other currently rendered rows.

Add Row

You can add a row to the table using the addRow function.

The first argument should be a row data object. If you do not pass data for a column, it will be left empty. To create a blank row (ie for a user to fill in), pass an empty object to the function.

The second argument is optional and determines whether the row is added to the top or bottom of the table. A value of true will add the row to the top of the table, a value of false will add the row to the bottom of the table. If the parameter is not set the row will be placed according to the addRowPos global option.

table.addRow({name:"Billy Bob", age:"12", gender:"male", height:1}, true);

By default any new rows will be added to the bottom of the table, to change this to the top set the addRowPos option to "top";

If you want to add the row next to an existing row you can pass an optional third argument to the function that will position the new row next to the specified row (above or below based on the value of the second argument). This argument will take any of the standard row component look up options:

table.addRow({name:"Billy Bob", age:"12"}, true, 3); //add new row above existing row with index of 3

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to the new data before the row is added. (see Mutators for more details)

Returned Promise

The addRow method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.addRow({name:"Billy Bob", age:"12"})
.then(function(row){
    //row - the row component for the row updated or added

    //run code after data has been updated
})
.catch(function(error){
    //handle error updating data
});

Update Row

You can update any row in the table using the updateRow function.

The first argument is the row you want to update, it will take any of the standard row component look up options.

The second argument should be the updated data object for the row. As with the updateData function, this will not replace the existing row data object, it will only update any of the provided parameters.

table.updateRow(1, {id:1, name:"bob", gender:"male"});

Once complete, this function will trigger the rowUpdated and dataEdited events.

This function will return true if the update was successful or false if the requested row could not be found. If the new data matches the existing row data, no update will be performed.

If you already have the RowComponent for the row you wish to update, you can call the update function directly on the component:

row.update({"name":"steve"}); //update the row data for field "name"

Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to the new data before the row is updated. (see Mutators for more details)

Returned Promise

The updateRow and row.updatemethods return a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.updateRow(1, {id:1, name:"bob", gender:"male"})
.then(function(){
    //run code after data has been updated
})
.catch(function(error){
    //handle error updating data
});

row.update({name:"steve"})
.then(function(){
    //run code after data has been updated
})
.catch(function(error){
    //handle error updating data
});

Update or Add Row

If you don't know whether a row already exists you can use the updateOrAddRow function. This will check if a row with a matching index exists, if it does it will update it, if not it will add a new row with that data. This takes the same arguments as the updateRow function.

table.updateOrAddRow(3, {id:3, name:"steve", gender:"male"});

Returned Promise

The updateOrAddRow method returns a promise, this can be used to run any other commands that have to be run after the data has been loaded into the table. By running them in the promise you ensure they are only run after the table has loaded the data.

table.updateOrAddRow(3, {id:3, name:"steve", gender:"male"})
.then(function(row){
    //row - the row component for the row updated or added

    //run code after data has been updated
})
.catch(function(error){
    //handle error updating data
});

Get Row Element

To retrieve the DOM Node of a specific row, you can retrieve the RowComponent with the getRow function, then use the getElement function on the component. The first argument is the row you are looking for, it will take any of the standard row component look up options.

var row = table.getRow(1); //return row component with index of 1
var rowElement = row.getElement();

Delete Row

You can delete any row in the table using the deleteRow function. The first argument is the row you want to delete, it will take any of the standard row component look up options.

table.deleteRow(15); //delete row with an id of 15

You can delete multiple rows at once by passing an array of row component look up options to the deteleRow function

table.deleteRow([15,7, 9]); //delete rows with ids of 15, 7 and 9

If you already have the RowComponent for the row you wish to delete, you can call the delete function directly on the component:

row.delete();

Returned Promise

The deleteRow and row.deletemethods return a promise, this can be used to run any other commands that have to be run after the data rows have been deleted from the table. By running them in the promise you ensure they are only run after the table has been fully updated

table.deleteRow(15)
.then(function(){
    //run code after row has been deleted
})
.catch(function(error){
    //handle error deleting row
});

row.delete()
.then(function(){
    //run code after row has been deleted
})
.catch(function(error){
    //handle error deleting row
});

Version 6.3 Released!

Updating Data

Returned Promise

Returned Promise

Returned Promise

Update or Add Data

Returned Promise

Retrieve All Data

Retrieve Count of Number of Rows

Retrieve Row Data

Retrieving Row Components

Search for Row Components

Search for Row Data

Find Row Position In Table

Get Row From Position In Table

Table Contents

Function Arguments

Change Column Title in HTML Output

Accessors

Cell Formatters

Row Formatter

Group Header

Column Visibility

Returned Promise

Update Row

Returned Promise

Update or Add Row

Returned Promise

Get Row Element

Delete Row

Returned Promise