Version 6.3 Released!

Click to checkout the new features

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

User Editing Data

Overview

Tabulator allows for users to edit the data contained in each cell of the table.

Loading Example...
Source Code

HTML

<div id="example-table"></div>

JavaScript

//Create Date Editor
var dateEditor = function(cell, onRendered, success, cancel){
    //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

    //create and style input
    var cellValue = moment(cell.getValue(), "DD/MM/YYYY").format("YYYY-MM-DD"),
    input = document.createElement("input");

    input.setAttribute("type", "date");

    input.style.padding = "4px";
    input.style.width = "100%";
    input.style.boxSizing = "border-box";

    input.value = cellValue;

    onRendered(function(){
        input.focus();
        input.style.height = "100%";
    });

    function onChange(){
        if(input.value != cellValue){
            success(moment(input.value, "YYYY-MM-DD").format("DD/MM/YYYY"));
        }else{
            cancel();
        }
    }

    //submit new value on blur or change
    input.addEventListener("blur", onChange);

    //submit new value on enter
    input.addEventListener("keydown", function(e){
        if(e.keyCode == 13){
            onChange();
        }

        if(e.keyCode == 27){
            cancel();
        }
    });

    return input;
};


//Build Tabulator
var table = new Tabulator("#example-table", {
    height:"311px",
    columns:[
        {title:"Name", field:"name", width:150, editor:"input"},
        {title:"Location", field:"location", width:130, editor:"autocomplete", editorParams:{allowEmpty:true, showListOnEmpty:true, values:true}},
        {title:"Progress", field:"progress", sorter:"number", align:"left", formatter:"progress", width:140, editor:true},
        {title:"Gender", field:"gender", editor:"select", editorParams:{values:{"male":"Male", "female":"Female", "unknown":"Unknown"}}},
        {title:"Rating", field:"rating",  formatter:"star", align:"center", width:100, editor:true},
        {title:"Date Of Birth", field:"dob", align:"center", sorter:"date", width:140, editor:dateEditor},
        {title:"Driver", field:"car", align:"center", editor:true, formatter:"tickCross"},
    ],
});

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,
}}

The editor has optional properties for the editorParams object:

  • search - use search type input element with clear button

Text Area

The textarea editor allows entering of multiple lines of plain text

{title:"Example", field:"example", editor:"textarea"}

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,
}}

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)

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,
}}

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)

Checkbox

The tick editor allows for boolean values using a checkbox type input element.

{title:"Example", field:"example", editor:"tick", editorParams:{
    tristate:true,
    indeterminateValue:"n/a",
}}

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)

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"}

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
}}

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".

The editor has one mandatory property for the editorParams object:

  • values - a list of values to be displayed to the user

There are five 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 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.

{title:"Name", field:"name", editor:"select", editorParams:{
    values:[
        { //option group
            label:"Men",
            options:[ //options in option group
                {
                    label:"Steve Boberson",
                    value:"steve",
                },
                {
                    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(item){
            if(item.value === term){
                matches.push(item);
            }
        });

        return matches;
    },
    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
}}

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)
  • 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".

The editor has one mandatory property for the editorParams object:

  • values - a list of values to be displayed to the user

There are three 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 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",
    }
}}

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)

Callbacks

A range of callbacks are available for tracking progress of data manipulation. See the Data Callbacks section for more information.

Donate