User Editing Data
Overview
Tabulator allows for users to edit the data contained in each cell of the table.
Columns of the table can be set as editable using the editor property in the column definition. (see Define Columns for more details).
When a user clicks on an editable column the will be able to edit the value for that cell.
By default Tabulator will use an editor that matches the current formatter for that cell. if you wish to specify a specific editor, you can set them per column using the editor option in the column definition. Passing a value of true to this option will result in Tabulator applying the editor that best matches the columns formatter, if present.
You can pass an optional additional parameter with the editor, editorParams that should contain an object with additional information for configuring the editor.
{title:"Rating", field:"rating", editor:"star", editorParams:{stars:4}}
Params Lookup Function
If you want to dynamically generate the editorParams at the time the editor is called you can pass a function into the property that should return the params object.
//define lookup function
function paramLookup(cell){
//cell - the cell component
//do some processing and return the param object
return {param1:"green"};
}
//column definition
{title:"Rating", field:"rating", editor:"star", editorParams:paramLookup}
Editors
Built In Editors
Tabulator comes with a number of built-in editors including:
Note: For a guide to adding your own editors to this list, have a look at the Extending Tabulator section.
Input
The input editor allows entering of a single line of plain text
{title:"Example", field:"example", editor:"input", editorParams:{
search:true,
mask:"AAA-999",
elementAttributes:{
maxlength:"10", //set the maximum character length of the input element to 10 characters
}
}}
The editor has optional properties for the editorParams object:
- search - use search type input element with clear button
- mask - apply a mask to the input to allow characters to be entered only in a certain order (see Text Input Masking for more information
- elementAttributes - set attributes directly on the input element
Text Area
The textarea editor allows entering of multiple lines of plain text
{title:"Example", field:"example", editor:"textarea", editorParams:{
elementAttributes:{
maxlength:"10", //set the maximum character length of the textarea element to 10 characters
},
mask:"AAA-999",
verticalNavigation:"editor", //navigate cursor around text area without leaving the cell
}}
The editor has optional properties for the editorParams object:
- elementAttributes - set attributes directly on the textarea element
- mask - apply a mask to the input to allow characters to be entered only in a certain order (see Text Input Masking for more information
-
verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
- hybrid - the arrow keys move the cursor around the text area, when the cursor reaches the start or end of the contents of the text area it navigates to the next row of the table (default)
- editor - the arrow keys move the cursor around the textarea contents but do not navigate round the table
- table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
Numeric
The number editor allows for numeric entry with a number type input element with increment and decrement buttons.
{title:"Example", field:"example", editor:"number", editorParams:{
min:0,
max:100,
step:10,
elementAttributes:{
maxlength:"10", //set the maximum character length of the input element to 10 characters
},
mask:"AAA-999",
verticalNavigation:"table", //up and down arrow keys navigate away from cell without changing value
}}
The editor has optional properties for the editorParams object:
- max - the maximum allowed value
- min - the minimum allowed value
- step - the step size when incrementing/decrementing the value (default 1)
- elementAttributes - set attributes directly on the input element
- mask - apply a mask to the input to allow characters to be entered only in a certain order (see Text Input Masking for more information
-
verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take two different types of value:
- editor - the arrow keys increase/decrease the value in the editor and do not navigate the table(default)
- table - the arrow keys will navigate to the prev/next row and will not affect the cell value
Range
The range editor allows for numeric entry with a range type input element.
{title:"Example", field:"example", editor:"range", editorParams:{
min:0,
max:100,
step:10,
elementAttributes:{
maxlength:"10", //set the maximum character length of the input element to 10 characters
}
}}
The editor has optional properties for the editorParams object:
- max - the maximum allowed value
- min - the minimum allowed value
- step - the step size when incrementing/decrementing the value (default 1)
- elementAttributes - set attributes directly on the input element
Checkbox
The tickCross editor allows for boolean values using a checkbox type input element.
{title:"Example", field:"example", editor:"tickCross", editorParams:{
tristate:true,
indeterminateValue:"n/a",
elementAttributes:{
maxlength:"10", //set the maximum character length of the input element to 10 characters
}
}}
The editor has optional properties for the editorParams object:
- tristate - allow tristate tickbox (default false)
- indeterminateValue - when using tristate tickbox what value should the third indeterminate state have (default null)
- elementAttributes - set attributes directly on the input element
Star Rating
The star editor allows entering of numeric value using a star rating indicator.
This editor will automatically detect the correct number of stars to use if it is used on the same column as the star formatter.
Users can use left/right arrow keys and enter for selection as well as the mouse.
{title:"Example", field:"example", editor:"star", editorParams:{
elementAttributes:{
maxlength:"10", //set the maximum character length of the input element to 10 characters
}
}}
The editor has optional properties for the editorParams object:
- elementAttributes - set attributes directly on the star holder element
Select
The select editor creates a dropdown select box to allow the user to select from some predefined options passed into the values property of the editorParams option.
{title:"Example", field:"example", editor:"select", editorParams:{
listItemFormatter:function(value, title){ //prefix all titles with the work "Mr"
return "Mr " + title;
},
values:true, //create list of values from all values contained in this column
sortValuesList:"asc", //if creating a list of values from values:true then choose how it should be sorted
defaultValue:"Steve Johnson", //set the value that should be selected by default if the cells value is undefined
elementAttributes:{
maxlength:"10", //set the maximum character length of the input element to 10 characters
},
verticalNavigation:"hybrid", //navigate to new row when at the top or bottom of the selection list
multiselect:true, //allow multiple entries to be selected
}}
The editor has one optional property for the editorParams object:
- listItemFormatter - a function that should return the HTML contents for each item in the value list
- sortValuesList - if values property is set to true this option can be used to set how the generated list should be sorted. if omitted the list will be in the order of rows in the table, when used it can have a value of "asc" or "desc".
- defaultValue - set the value that should be selected by default if the cells value is undefined
- elementAttributes - set attributes directly on the input element
-
verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
- editor - value selection up and down the list, will not navigate round the table (default)
- table - the arrow keys will navigate to the prev/next row and will not change the selected value in the list
- hybrid - the arrow keys move the value selection up and down the list, when it reaches the end of the list it moves on to the adjacent row
-
multiselect - allow the user to choose multiple values. With this option enabled the editor will accept and return an array of values. This option can take two different values:
- true - a boolean value of true will allow the user to select as many item from the list as they like
- number - if you set an integer for this option that will set the maximum number of items the user can select, if they try and select more than this, earlier selected items will be deselected
The editor has one mandatory property for the editorParams object:
- values - a list of values to be displayed to the user
There are six ways you can define the values list depending on your needs.
If you pass the boolean value of true to the values property, Tabulator will automatically build the values list out of all unique values in this cells column.
{title:"Example", field:"example", editor:"select", editorParams:{values:true}}
You can pass a string representing the field of another column in the table to the values property, Tabulator will automatically build the values list out of all unique values in cells in the specified column.
{title:"Example", field:"example", editor:"select", editorParams:{values:"color"}}
You can pass in an array of value:
{title:"Example", field:"example", editor:"select", editorParams:{values:["red", "green", "blue", "orange"]}}
If you want to show a different label to the value you want to store, you can pass in an object, where the key of each property is the value that will be stored if it is selected, and the value of each property will be the label displayed for it in the list.
{title:"Name", field:"name", editor:"select", editorParams:{
values:{
"steve":"Steve Boberson",
"bob":"Bob Jimmerson",
"jim":"Jim Stevenson",
}
}}
For more complex option lists you can use an array of objects, that allows you to define option groups, and disabled options. In the complex structure you can also use the elementAttributes property to define attributes directly on the list item element
{title:"Name", field:"name", editor:"select", editorParams:{
values:[
{ //option group
label:"Men",
options:[ //options in option group
{
label:"Steve Boberson",
value:"steve",
elementAttributes:{
class:"primary-name",
}
},
{
label:"Bob Jimmerson",
value:"bob",
},
]
},
{ //option group
label:"Women",
options:[ //options in option group
{
label:"Jenny Jillerson",
value:"jenny",
},
{
label:"Jill Betterson",
value:"jill",
},
]
},
{//ungrouped option
label:"Other",
value:"other",
},
]
}}
If you want to generate the options when the select editor is triggered, then you can pass a function into the editorParams, that must return the option list in one of the two formats outlined above
{title:"Name", field:"name", editor:"select", editorParams:function(cell){
//create a options list of all values from another column in the table
var rows = table.getRows();
var values = {};
rows.forEach(function(row){
var data = row.getData();
values[data.fullname] = data.fullname;
});
return {values:values};
}
Autocomplete
The autocomplete editor allows users to search a list of predefined options passed into the values property of the editorParams option.
{title:"Example", field:"example", editor:"autocomplete", editorParams:{
showListOnEmpty:true, //show all values when the list is empty,
freetext:true, //allow the user to set the value of the cell to a free text entry
allowEmpty:true, //allow empty string values
searchFunc:function(term, values){ //search for exact matches
var matches = [];
values.forEach(function(value){
//value - one of the values from the value property
if(value === term){
matches.push(value);
}
});
return matches;
},
searchingPlaceholder:"Filtering ...", //set the search placeholder
emptyPlaceholder:"(no matching results found)", //set the empty list placeholder
listItemFormatter:function(value, title){ //prefix all titles with the work "Mr"
return "Mr " + title;
},
values:true, //create list of values from all values contained in this column
sortValuesList:"asc", //if creating a list of values from values:true then choose how it should be sorted
defaultValue:"Steve Johnson", //set the value that should be selected by default if the cells value is undefined
elementAttributes:{
maxlength:"10", //set the maximum character length of the input element to 10 characters
},
mask:"AAA-999",
verticalNavigation:"hybrid", //navigate to new row when at the top or bottom of the selection list
}}
The editor has optional properties for the editorParams object:
- showListOnEmpty - show all values in the list when the input element is empty (default false)
- freetext - allow the user to press enter to save a value to the cell that is not in the list (default false)
- allowEmpty - allow the user to save an empty value to the cell (default false)
- searchFunc - function to search through array of value objects and return those that match the search term (by default this does a loose string comparison between values) This function is passed in the value list from the values property and should either return a valid values list or a promise that resolves a valid values list
- searchingPlaceholder - placeholder shown when the searchFunc returns a promise
- emptyPlaceholder - placeholder shown when no values match the search and the list is empty
- listItemFormatter - a function that should return the HTML contents for each item in the value list
- sortValuesList - if values property is set to true this option can be used to set how the generated list should be sorted. if omitted the list will be in the order of rows in the table, when used it can have a value of "asc" or "desc".
- defaultValue - set the value that should be selected by default if the cells value is undefined
- elementAttributes - set attributes directly on the input element
- mask - apply a mask to the input to allow characters to be entered only in a certain order (see Text Input Masking for more information
-
verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take two different types of value:
- editor - value selection up and down the list, will not navigate round the table (default)
- table - the arrow keys will navigate to the prev/next row and will not change the selected value in the list
- hybrid - the arrow keys move the value selection up and down the list, when it reaches the end of the list it moves on to the adjacent row
The editor has one mandatory property for the editorParams object:
- values - a list of values to be displayed to the user
There are four ways you can define the values list depending on your needs.
If you pass the boolean value of true to the values property, Tabulator will automatically build the values list out of all unique values in this cells column.
{title:"Example", field:"example", editor:"autocomplete", editorParams:{values:true}}
You can pass a string representing the field of another column in the table to the values property, Tabulator will automatically build the values list out of all unique values in cells in the specified column.
{title:"Example", field:"example", editor:"autocomplete", editorParams:{values:"color"}}
You can pass in an array of value:
{title:"Example", field:"example", editor:"autocomplete", editorParams:{values:["red", "green", "blue", "orange"]}}
If you want to show a different label to the value you want to store, you can pass in an object, where the key of each property is the value that will be stored if it is selected, and the value of each property will be the label displayed for it in the list.
{title:"Name", field:"name", editor:"autocomplete", editorParams:{
values:{
"steve":"Steve Boberson",
"bob":"Bob Jimmerson",
"jim":"Jim Stevenson",
}
}}
You can also pass in an array of objects, that allows you to define option in order.
{title:"Name", field:"name", editor:"select", editorParams:{
values:[
{
label:"Steve Boberson",
value:"steve",
},
{
label:"Bob Jimmerson",
value:"bob",
},
{
label:"Jenny Jillerson",
value:"jenny",
},
{
label:"Jill Betterson",
value:"jill",
},
]
}}
Custom Editors
If you need a different type of editor, you can pass a custom editor function to the editor option. This function should take five arguments, a CellComponent for the cell being edited, a function to call when the cell has ben rendered, which can be used to set focus or tidy up the display after the element has become visible, a function to call to pass back the new value, when the user hassuccessfully entered new data in the cell, a function to call if the user aborts the edit and parameters passed in from the editorParams column definition property.
The Custom editor function should return a DOM Node for the editor that will be inserted into the cell. or a value of false to abort the edit.
var dateEditor = function(cell, onRendered, success, cancel, editorParams){
//cell - the cell component for the editable cell
//onRendered - function to call when the editor has been rendered
//success - function to call to pass thesuccessfully updated value to Tabulator
//cancel - function to call to abort the edit and return to a normal cell
//editorParams - params object passed into the editorParams column definition property
//create and style editor
var editor = document.createElement("input");
editor.setAttribute("type", "date");
//create and style input
editor.style.padding = "3px";
editor.style.width = "100%";
editor.style.boxSizing = "border-box";
//Set value of editor to the current value of the cell
editor.value = moment(cell.getValue(), "DD/MM/YYYY").format("YYYY-MM-DD")
//set focus on the select box when the editor is selected (timeout allows for editor to be added to DOM)
onRendered(function(){
editor.focus();
editor.style.css = "100%";
});
//when the value has been set, trigger the cell to update
function successFunc(){
success(moment(editor.value, "YYYY-MM-DD").format("DD/MM/YYYY"));
}
editor.addEventListener("change", successFunc);
editor.addEventListener("blur", successFunc);
//return the editor element
return editor;
};
//in your column definition for the column
{title:"Birthday", field:"dob", editor:dateEditor}}
Blur Event
It is important to note that a custom editor must specify how to handle a blur event on its element by either calling the success or cancel functions. This is because when a user clicks or tabs out of a cell, the blur event will be fired and must be handled to move on to the next cell. As a fallback Tabulator will cancel the edit if an editor is blured and the event has not been correctly handled.
Optional Editing
There are some circumstances where you may want to block editability of a cell for one reason or another. To meet this need you can use the editable option. This lets you set a callback that is executed before the editor is built, if this callback returns true the editor is added, if it returns false the edit is aborted and the cell remains a non editable cell. The function is passed one parameter, the CellComponent of the cell about to be edited. You can also pass a boolean value instead of a function to this property.
var editCheck = function(cell){
//cell - the cell component for the editable cell
//get row data
var data = cell.getRow().getData();
return data.age > 18; // only allow the name cell to be edited if the age is over 18
}
//in your column definition for the column
{title:"Name", field:"name", editor:"input", editable:editCheck}
Data Mutation
if you have defined any mutator functions in your column definition array, these will be applied to your edited value as it is being parsed into the table. (see Mutators for more details)
Text Input Masking
Built in editors based on input elements such as the input, number, textarea and autocomplete editors have the ability to mask the users input to restrict it to match a given pattern.
This can be set by passing a string to the the mask option in the columns editorParams
{title:"Name", field:"name", editor:"input", editorParams:{mask:"AAA-999"}}
Each character in the string passed to the mask option defines what type of character can be entered in that position in the editor.
- A - Only a letter is valid in this position
- 9 - Only a number is valid in this position
- * - Any character is valid in this position
- Any other character - The character in this position must be the same as the mask
For example, a mask string of "AAA-999" would require the user to enter three letters followed by a hyphen followed by three numbers
Autofill Fixed Characters
If you are using fixed characters in your mask (any character other that A, 9 or *), then you can get the mask to automatically fill in these characters for you as you type by setting the maskAutoFill option in the editorParams to true
{title:"Name", field:"name", editor:"input", editorParams:{
mask:"AAA-999",
maskAutoFill:true,
}}
Custom Pattern Characters
If you want to use the characters A, 9 or * as fixed characters then it is possible to change the characters looked for in the mask by using the maskLetterChar, maskNumberChar and maskWildcardChar options in the editorParams
{title:"Name", field:"name", editor:"input", editorParams:{
mask:"A!!-9BBB$",
maskLetterChar:"B",
maskNumberChar:"!",
maskWildcardChar:"$",
}}
In the example the above the input would be masked with the first character being "A" followed by two numbers, followed by a hyphen, followed by the number "9", followed by three numbers, followed by any character
Edit History
Whenever a cell is edited a flag is set to mark that cell as edited
List Edited Cells
You can get a list of all edited cells in the table using the getEditedCells function. this will return an array of Cell Components for each cell that has been edited.
var editedCells = table.getEditedCells()
Tabulator will continue to add cells to this list until the table in the data is replaced by the setData function or the edited list is cleared.
Check if Cell Has Been Edited
You can call the isEdited function on any Cell Component to see if it has been edited. it will return true if it has been edited or false if it has not.
var edited = cell.isEdited()
Clear Edited Cells
You can clear the edited flag on a cell to prevent ir from coming up in edited lists in future
The clearEdited can be called on a Cell Component to clear the edited flag used by the isEdited function and mark the cell as unedited.
cell.clearEdited();
Alternativly, the clearCellEdited can be called on the table to clear the edited flag on all cells in the table
table.clearCellEdited();
Or optionally you can pass in a Cell Component or an array of Cell Components to the clearCellEdited function to clear the edited flag on specific cells
table.clearCellEdited([cell1, cell2]);
Callbacks
A range of callbacks are available for tracking progress of data manipulation. See the Data Callbacks section for more information.