User Editing Data

• Overview
• Editors
  • Built In Editors
  • Custom Editors
• Optional Editing
• Callbacks

Overview Demo

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:

• input - editor for plain text.
• textarea - editor for multi-line text, allows the row to vertically resize to fit the text as it is entered.
• number - editor for numbers with increment and decrement buttons.
  • optional editorParams:
    • max - the maximum allowed value
    • min - the minimum allowed value
    • step - the step size when incrementing/decrementing the value (default 1)
• range - range slider editor for numbers.
  • optional editorParams:
    • max - the maximum allowed value (default 0)
    • min - the minimum allowed value (default 10)
    • step - the step size when incrementing/decrementing the value (default 1)
• tick - editor for tick and tickCross columns.
• star - editor for star columns (can use left/right arrow keys and enter for selection as well as mouse).
• progress - editor for progress bar columns (can use left/right arrow keys and enter for selection as well as mouse)
• select - a select box for picking from a set of options. (details of how to use this can be seen below)

Select Editor

The select editor creates a dropdown select box to allow the user to select from some predefinedoptions, you define the list of options in the editorParams property. There are three ways you can define the options list depending on your needs.

The simplest way to define the list is by passing in an object where the property keys represent the value of the option and their value represents the label of the option.

{title:"Name", field:"name", editor:"select", editorParams:{
    "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:[
    //option group
    {
        label:"Men",

        //options in option group
        options:[
            {
                label:"Steve Boberson",
                value:"steve",
            },
            {
                label:"Bob Jimmerson",
                value:"bob",
            },
        ]
    },

    //option group
    {
        label:"Women",

        //options in option group
        options:[
            {
                label:"Jenny Jillerson",
                value:"jenny",
            },
            {
                label:"Jill Betterson",
                value:"jill",
            },
        ]
    },

    //ungrouped option
    {
        label:"Other",
        value:"other",
    },

    //disabled option
    {
        label:"Disabled",
        value:"disabled",
        disabled:true,
    }
]}

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 names currently in the table

    var rows = table.getRows();
    var options = {};

    rows.forEach(function(row){
        var data = row.getData();

        options[data.name] = data.name;
    });

    return options;
}

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 four parameters, 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, and a function to call if the user aborts 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.