Updating Data
Overview
Once you have loaded data into your table, Tabulator provides a wide variety of methods for updating and manipulating that data.
Altering Data
Replacing 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
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 });