User Editing Data
- Overview
- Built In Editors
- Custom Editors
- Optional Editing
- Trigger Event
- Text Input Masking
- Empty Values
- Edit History
- Events
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}
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", selectContents:true, 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
- selectContents - when the editor is loaded select its text content
- 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", selectContents:true, verticalNavigation:"editor", //navigate cursor around text area without leaving the cell shiftEnterSubmit:true, //submit cell value on shift enter }}
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
- selectContents - when the editor is loaded select its text content
-
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
- shiftEnterSubmit - submit the cell value when the shift and enter keys are pressed
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:"999", selectContents:true, 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
- selectContents - when the editor is loaded select its text content
-
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:{ trueValue:"car", falseValue:"bike", 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:
- trueValue - The value returned from the editor when the checkbox is ticked (leave undefined for standard boolean values)
- falseValue - The value returned from the editor when the checkbox is unticked (leave undefined for standard boolean values)
- 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
Progress Bar
The progress editor allows adjusting a numeric value formatted using the progress formatter.
This editor will automatically detect maximum and minimum values of the progress bar from the formatter, or they can be manually overriden in the editorParams.
{title:"Example", field:"example", editor:"progress", editorParams:{ min:7, // the minimum value of the progress bar max:46, // the maximum value of the progress bar elementAttributes:{ title:"slide bar to choose option" // custom tooltip } }}
The editor has optional properties for the editorParams object:
- min - the minimum value for the progress bar
- max - the maximum value for the progress bar
- elementAttributes - set attributes directly on the progress holder element
Date
The date editor allows for editing of a date using a standard date type input field.
{title:"Example", field:"example", editor:"date", editorParams:{ min:"01/01/2020", // the minimum allowed value for the date picker max:"02/12/2022", // the maximum allowed value for the date picker format:"dd/MM/yyyy", // the format of the date value stored in the cell verticalNavigation:"table", //navigate cursor around table without changing the value elementAttributes:{ title:"slide bar to choose option" // custom tooltip } }}
The editor has optional properties for the editorParams object:
- min - the earliest day available for the date picker, the default format is yyyy-mm-dd, if the format param is used then it will expect the date in that format instead
- max - the latest day available for the date picker, the default is yyyy-mm-dd, if the format param is used then it will expect the date in that format instead
- format - the format for the date to be stored in the table. This accepts any valid Luxon format string, or the value "iso" which accept any ISO formatted data. If the input value is a luxon DateTime object then you should set this option to true. If this value param is ignored then the data should be in the format YYYY-MM-DD(this will not affect the format the user has to enter the data into the table, that is determined by the browser)
-
verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
- editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
- table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
- elementAttributes - set attributes directly on the progress holder element
Browser Styling
Because this editor uses the default date type input element, it is up to each browser to choose how the date picker will function and be styled, which may lead to an inconsistent look and feel. If you need consistent functionality across browsers then it recomended that you make a custom editor using an external date picker library.
Advanced Functionality
This intended as a simple date picker, if you are looking for advanced functionality then it is recomended that you build a custom editor using an external date picker library.
Time
The time editor allows for editing of a time using a standard time type input field.
{title:"Example", field:"example", editor:"time", editorParams:{ format:"hh:mm:ss", // the format of the time value stored in the cell verticalNavigation:"table", //navigate cursor around table without changing the value elementAttributes:{ title:"slide bar to choose option" // custom tooltip } }}
The editor has optional properties for the editorParams object:
- format - the format for the time to be stored in the table. This accepts any valid Luxon format string, or the value "iso" which accept any ISO formatted data. If the input value is a luxon DateTime object then you should set this option to true. If this value param is ignored then the data should be in the format hh:mm(this will not affect the format the user has to enter the data into the table, that is determined by the browser)
-
verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
- editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
- table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
- elementAttributes - set attributes directly on the progress holder element
Because this editor uses the default time type input element, it is up to each browser to choose how the time picker will function and be styled, which may lead to an inconsistent look and feel. If you need consistent functionality across browsers then it recomended that you make a custom editor using an external time picker library.
Advanced Functionality
This intended as a simple time picker, if you are looking for advanced functionality then it is recomended that you build a custom editor using an external time picker library.
Date Time
The datetime editor allows for editing of a date and time using a standard datetime type input field.
{title:"Example", field:"example", editor:"datetime", editorParams:{ format:"dd/MM/yyyy hh:mm", // the format of the date value stored in the cell verticalNavigation:"table", //navigate cursor around table without changing the value elementAttributes:{ title:"slide bar to choose option" // custom tooltip } }}
The editor has optional properties for the editorParams object:
- format - the format for the date-time to be stored in the table. This accepts any valid Luxon format string, or the value "iso" which accept any ISO formatted data. If the input value is a luxon DateTime object then you should set this option to true. If this value param is ignored then the data should be in the format YYYY-MM-DDThh:mm(this will not affect the format the user has to enter the data into the table, that is determined by the browser)
-
verticalNavigation - determine how use of the up/down arrow keys will affect the editor, this can take three different types of value:
- editor - the arrow keys increment/decrement the selected value but will not navigate round the table (default)
- table - the arrow keys will navigate to the prev/next row and will not move the cursor in the editor
- elementAttributes - set attributes directly on the progress holder element
Because this editor uses the default datetime-local type input element, it is up to each browser to choose how the date-time picker will function and be styled, which may lead to an inconsistent look and feel. If you need consistent functionality across browsers then it recomended that you make a custom editor using an external date-time picker library.
Advanced Functionality
This intended as a simple date-time picker, if you are looking for advanced functionality then it is recomended that you build a custom editor using an external date-time picker library.
List (Select/Autocomplete)
The list editor creates a dropdown list to allow the user to select from some predefined options, by default it functions as a select list type element but can also be configured to function as an autocomplete.
{title:"Example", field:"example", editor:"list", editorParams:{ //Value Options (You should use ONE of these per editor) values:["red", "green", "blue", "orange"], //an array of values or value/label objects valuesURL: "http://myvalues.com", //a url to load the values from valuesLookup:"active", //get the values from the currently active rows in this column //Value Lookup Configuration (use these with valuesLookup Option) valuesLookupField:"color", //the field to lookup values from //General Options clearable:true, //show clear "x" button on editpr itemFormatter:function(label, value, item, element){ //label - the text lable for the item //value - the value for the item //item - the original value object for the item //element - the DOM element for the item return "<strong>" + label + " </strong><br/><div>" + item.subtitle + "</div>"; }, elementAttributes:{ //set attributes on input element 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 sort:"asc", //sort direction for the values list defaultValue:"Steve Johnson", //the value that should be selected by default if the cells value is undefined emptyValue:null, //the value that should be asigned to the cell if the editor is left with an empty value maxWidth:true, //prevent width of list item from exceeding width of cell placeholderLoading:"Loading List...", //set custom placeholder when loading list values placeholderEmpty:"No Results Found", set custom placeholder when list is empty //Select Options (only available when autocomplete:false) multiselect:true, //allow selection of multiple items from the list //Autocomplete Options (only available when autocomplete:true) autocomplete:true, //enable autocomplete mode, filterFunc:function(term, label, value, item){ //replace built in filter function with custom //term - the string being searched for //label - the text lable for the item //value - the value for the item //item - the original value object for the item return label === term; }, filterRemote:true, //pass filter term to remote server in request instead of filtering filterDelay:100, //delay in milliseconds after typing before filter begins allowEmpty:true, //allow the user to leave the cell empty listOnEmpty:true, //show all values in the list if the input is empty mask:"AAA-999", //apply input mask to text entry freetext:true, //allow the user to set the value of the cell to a free text entry }}
The editor has many optional properties for the editorParams object:
- values - either an array of values, or value objects (this is explained in more detail in the next section)
- valuesURL - the url to load the values for the list from
- valuesLookup - lookup the values for the list from a column in the table, this option sets which range of data should be loaded, or provides a function to dynamically set the data
- valuesLookupField - the field the values for this list should be looked up from
- clearable - adds a clear button to the right of the editor to allow the user to empty the current value
- itemFormatter - change how the items in the list are displayed
- 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
- sort - sort the items in the list, either asc or desc or a custom sorter function
- defaultValue - set the value that should be selected by default if the cells value is undefined
- emptyValue - set the value that will be set on the cell if the user leave the input empty
- maxWidth - the list will by default expand to fit the contents of the list, if you wish to constrain the width of the list, you can either pass an integer for the maximum width of the list in pixels, or the value true which will fit the list to the width of the current cell
- placeholderLoading - set custom placeholder when loading list values, this can either be a text string, a valid HTML string a DOM Element, or a function, that will be called and passed in the cell component and the current list element and should return one of the above valid placeholder values.
- placeholderEmpty - set custom placeholder when list is empty, this can either be a text string, a valid HTML string a DOM Element, or a function, that will be called and passed in the cell component and the current list element and should return one of the above valid placeholder values.
- multiselect - set this to true to allow the user to choose multiple values. With this option enabled the editor will accept and return an array of values. (this option is only available when the autocomplete option is disabled)
- autocomplete - set this to true to allow the user to filter the options list by typing in the input.
- filterFunc - a custom filter function to define how an autocomplete should filter its row values. (this option is only available when the autocomplete option is enabled)
- filterRemote - When using a remote data source like Ajax, this tells hte auto complete to submit the search term as part of the request instead of triggering a local filter function. (this option is only available when the autocomplete option is enabled)
- filterDelay - The delay in milliseconds between a person typing a letter and the filter begginging, used to delay filtering until the user has finished typing. (default value 300 - this option is only available when the autocomplete option is enabled)
- allowEmpty - allow the user to save an empty value to the cell. (this option is only available when the autocomplete option is enabled)
- listOnEmpty - show the whole list of values when the cell is empty. (this option is only available when the autocomplete option is enabled)
- mask - apply a mask to the input to allow characters to be entered only in a certain order (this option is only available when the autocomplete option is enabled) (see Text Input Masking for more information)
- freetext - allow the user to press enter to save a value to the cell that is not in the list (this option is only available when the autocomplete option is enabled)
Values
There are multiple ways you can define the values in list depending on your needs, the sections below outline each detail
Values - Array / Object
You can pass in an array of values to the vaulues param:
{title:"Example", field:"example", editor:"list", editorParams:{values:["red", "green", "blue", "orange"]}}
In this mode, the value will also be used as the label for the list item.
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:"list", editorParams:{ values:{ "steve":"Steve Boberson", "bob":"Bob Jimmerson", "jim":"Jim Stevenson", } }}
You can alternativly pass an array of value objects, each with a value and label object, if you would like to specify a different label for each value and their order. You can also add custom properties to each of the objects that will be accessible in the sort, filter and layout functions if you want to use other data in your list
With an aray of value objects, you can also create groups of options using the options property on an item and passing an array of value objects to the prop.
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:[ { label:"Steve Boberson", value:"steve", keywords:"red, green, blue, orange", // custom field description:"Likes to drive a car", // custom field }, { //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", }, ] }}
Values - Lookup From Column
Using the valuesLookup option cause the editor to lookup the unique values from a column on the table.
When using the valuesLookup option, it is used to specify the range of rows that shoul be used for the lookup, and takes any of the standardRow Range Lookup.
It should be used in conjunction with the valuesLookupField option in which you can set the field name for the column you want to lookup the data from.
{title:"Name", field:"name", editor:"list", editorParams:{ valuesLookup:true, //lookup all unique values valuesLookupField:"people", //lookup all unique values from the people column }}
If you leave out the valuesLookupField option it will lookup the values from the current column:
{title:"Name", field:"name", editor:"list", editorParams:{ valuesLookup:"active", //lookup filtered unique values in this column }}
Alternativly if you want to generate the content in a different way, you can pass a callback to the valuesLookup option that should return a value array or object. The callback is passed in the Cell Component for the cell being edited, and the currenty value of the input in case you are using the filterRemote option.
{title:"Name", field:"name", editor:"list", editorParams:{ valuesLookup:function(cell, filterTerm){ //cell - the cell component for the current cell //filterTerm - the current value of the input element return [ { label:"Steve Boberson", value:"steve", }, { label:"Bob Jimmerson", value:"bob", }, { label:"Jenny Jillerson", value:"jenny", }, { label:"Jill Betterson", value:"jill", }, ]; } }}
If you want to carry out an asynchronous function in this callback, like a custom ajax request, then you can return a promise from this function that should resolve with the value array / object.
Values - Remote Ajax Source
If you want to lookup data from a remote ajax source, you can get the table to make a simple AJAX get request to a url by passing it to the valuesURL option.
If you are also using filterRemote then the current value of the input element will aslo be passed in the request as the term parameter.
The request should respond with a JSON encoded values array/object.
{title:"Name", field:"name", editor:"list", editorParams:{ valuesURL:"http://getdata.fromhere.com", //get value list from URL }}
The valuesURL option is only intended for a simple GET ajax request. If you need to make a different/more complex request, then you should use the valuesLookup option and make the ajax request yourself.
While making the request, a placeholder element will be displayed to the user, the contents of this placeholder can be set using the placeholderLoading option. This can either be a text string, valid HTML, a DOM node or a callback function that will return one of those options. If you use a callback function, the first argument will be the Cell Component for the cell being edited.
{title:"Name", field:"name", editor:"list", editorParams:{ valuesURL:"http://getdata.fromhere.com", //get value list from URL placeholderLoading:"Loading Remote Data...", //set a custom placeholder text }}
Formatting List
By default, Tabulator will render the values list as a simple list of text values. You can choose to format the list in any way you like, using the itemFormatter option.
This option takes a callback that will be called for each item in the list, it will be passed in the value of the item the first argument, the label for the item as the second argument, the original value object for the component as its third argument, complete with any custom properties that may have been set and the containing element for the list item as the fourth argument incase you wish to directly manipulate it by applying classes etc.
The callback return a text string, valid HTML, or a DOM node for the contents of the item.
{title:"Name", field:"name", editor:"list", editorParams:{ itemFormatter:function(label, value, item, element){ //label - the text lable for the item //value - the value for the item //item - the original value object for the item //element - the DOM element for the item //return the initial label as a bold line and then second line in regular font weight containing the value of the custom "subtitle" prop set on the value item object. return "<strong>" + label + " </strong><br/><div>" + item.subtitle + "</div>"; }, }}
Sorting List
By default no sort will be applied to the values list. it will appear in the order the items were defined. You can sort the list using the sort option, this can take the string value of asc to sort the list in ascending order by label, or the string value of desc to sort the list in descending order by label.
{title:"Name", field:"name", editor:"list", editorParams:{ sort:"asc", //sort list in ascending order }}
By default, Tabulator uses an alphanumeric sort on list values. If you would like to apply a custom sort to the list, then you can also pass a callback function into this option. This callback will function in the same way as the comparison function passed to the standard JavaScript sort function, it should return -1 if value "a" is less than value "b", 1 if it is greater than, and 0 if they are equal.
The function is passed in several arguments:
{title:"Name", field:"name", editor:"list", editorParams:{ sort:(aLabel, bLabel, aValue, bValue, aItem, bItem){ //aLabel - the text lable for item a //bLabel - the text lable for item b //aValue - the value for item a //bValue - the value for item b //aItem - the original value object for item a //bItem - the original value object for item b //sort by numeric values return aValue < bValue ? -1 : (aValue == bValue ? 0 : 1); }, }}
Filtering List
When using the editor with autocomplete enabled, the list will be filtered every time the user types in the input. By default this is accomplished using a case-insensitive string comparison between the value of the input element and the label of the list item.
If you wish to filter in a different way, you can pass a callback to the filterFunc option. This option is passed four aguments, the term being searched for, the label of the item, the value of the item, and the item object. It should return true if the item matches the term and false if it does not
{title:"Name", field:"name", editor:"list", editorParams:{ filterFunc:(term, label, value, item){ //term - the string value from the input element //label - the text lable for the item //value - the value for the item //item - the original value object for the item //filter strictly against the value of the item return term === value; }, }}
If you are retreiving your data from a remote source using either the valueURL option, or a promise return from a callback on the valuesLookup option, then you can choose to filter your data remotely instead and bypass the local filter.
This can be accomplished using the filterRemote option. With this enabled, the local filter will not be run, instead the remote request will be retriggered with the current search term pass as an argument.
{title:"Name", field:"name", editor:"list", editorParams:{ valuesURL:"http://getdata.fromhere.com", //get value list from URL filterRemote:true, }}
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 = luxon.DateTime.fromFormat(cell.getValue(), "dd/MM/yyyy").toFormat("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(luxon.DateTime.fromFormat(cell.getValue(), "yyyy-MM-dd").toFormat("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)
Trigger Event
The editTriggerEvent option lets you choose which type of interaction event will trigger an edit on a cell.
var table = new Tabulator("#example-table", { editTriggerEvent:"dblclick", //trigger edit on double click });
This option can take one of three values:
- focus - trigger edit when the cell has focus (default)
- click - trigger edit on single click on cell
- dblclick - trigger edit on double click on cell
This option does not affect navigation behavior, cells edits will still be triggered when they are navigated to through arrow keys or tabs.
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
Empty Values
When editing a cell, if a user clears the value of the cell and then leaves focus the value of the cell is often set to an empty string "" or other similarly empty value. This is not always a desierable option, you may want to ensure that empty cells always have the same value, for example a value of undefined.
For this reason the editorEmptyValue option lets you set what value should be assigned to a cell when it is edited and the value is empty.
Tabulator considers an edit to be empty when the value is either:
- An empty string
- null
- undefined
The editorEmptyValue option can either be set on the table as a whole to affect all columns.
var table = new Tabulator("#example-table", { editorEmptyValue:undefined, //set empty cell values to undefined after edit });
Or on a column definition alongside an editor:
{title:"Name", field:"name", editor:"input", editorEmptyValue:undefined}
If neither of these options are set, then the empty cell will be asigned the value returned from the editor.
Empty Value Classification
As mentioned above, Tabulator will consider a very specific list of values to be empty, you can customise this behaviour using the editorEmptyValueFunc option, that lets you define custom callback logic to determine what is classed as empty.
You should pass a callback to this option that takes the edited value as its first argument, it should return a value of true if the value should be considered empty:
var table = new Tabulator("#example-table", { editorEmptyValue:undefined, //set empty cell values to undefined after edit editorEmptyValueFunc:(value) =>{ return value === ""; //only consider empty strings as empty }, });
This can also be set on a column by column basis in the column definition:
{title:"Name", field:"name", editor:"input", editorEmptyValue:undefined, editorEmptyValueFunc:(value) =>{ return value === ""; //only consider empty strings as empty }}
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]);
Events
A range of events are available for table editing. See the Edit Events section for more information.