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. (the index defaults to the "id" parameter, this can be set using the index option in the tabulator constructor). 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. If you only want to access the currently filtered/sorted elements, you can pass a value of true to the first argument of the function.
var data = table.getData(true); //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();
If you only want to count the currently filtered/sorted elements, you can pass a value of true to the first argument of the function
var activeRowCount = table.getDataCount(true);
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 Row Component's held in the Tabulator. If you only want to access the currently filtered/sorted elements, you can pass a value of true to the first argument of the function.
var rows = table.getRows(true); //return currently filtered data
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. By default this will return the position of the row in all data, including data currently filtered out of the table.
The first argument is the row you are looking for, it will take any of the standard row component look up options. If you want to get the position of the row in the currently filtered/sorted data, you can pass a value of true to the optional second argument of the function.
var position = table.getRowPosition(row, true); //return the position of the row in the filtered/sorted data
NoteIf the row is not found, a value of -1 will be returned, row positions start at 0
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.
If you want to get a row based on its position in the currently filtered/sorted data, you can pass a value of true to the optional second argument of the function.
var row = table.getRowFromPosition(5, true); //return 6th 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 table = table.getHtml();
This will return a HTML encoded string of the table data.
By default getHtml will return a table containing all the data held in the Tabulator. If you only want to access the currently filtered/sorted elements, you can pass a value of true to the first argument of the function.
var table = table.getHtml(true); //build table from filtered data only
You can hide a column from the HTML output by setting the hideInHtml property to true on its column definition.
{title:"Name", field:"name", hideInHtml:true}
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);
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 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.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
});