Mutators & Accessors

• Overview
• Mutators
  • Mutation Types
  • Linked Mutators
• Accessors
  • Accessor Types
  • Built In Accessors

Overview

Mutators (setters) and Accessors (getters) allow you to manipulate the table data as it enters and leaves your Tabulator, allowing you to convert values for use in your table and then change them again as they leave.

Mutators

Mutators are used to alter data as it is parsed into Tabulator. For example if you wanted to convert a numeric column into a boolean based on its value, before the data is used to build the table.

You can set mutators on a per column basis using the mutator option in the column definition object.

You can pass an optional additional parameter with mutator, mutatorParams that should contain an object with additional information for configuring the mutator.

//define custom mutator
var customMutator = function(value, data, type, params, component){
    //value - original value of the cell
    //data - the data for the row
    //type - the type of mutation occurring  (data|edit)
    //params - the mutatorParams object from the column definition
    //component - when the "type" argument is "edit", this contains the cell component for the edited cell, otherwise it is the column component for the column

    return value > mutatorParams.threshold; //return the new value for the cell data.
}

//column definition
{title:"Has Too Many Cars", field:"cars", mutator:customMutator, mutatorParams:{threshold:5}}

Field Required
For a mutator to work the column definition must have a field property specified, otherwise the muator will not know which field to act on. If you are using the mutator to generate a field that does not exist in the initial data, that is fine but the field must still be specified in the column definition.

Params Lookup Function

If you want to dynamically generate the mutator params at the time the mutator is called you can pass a function into the property that should return the params object.

//define lookup function
function paramLookup(value, data, type, component){
    //value - original value of the cell
    //data - the data for the row
    //type - the type of mutation occurring  (data|edit)
    //component - when the "type" argument is "edit", this contains the cell component for the edited cell, otherwise it is the column component for the column

    //do some processing and return the param object
    return {param1:"green"};
}

//column definition
{title:"Has Too Many Cars", field:"cars", mutator:customMutator, mutatorParams:paramLookup}

Mutation Types

Data can be mutated whenever it enters the table, either through a command or through a user editing the table. To allow you to have more control over how your data is mutated, there are a variety of different mutation options you can pass your callback to instead of just the mutator callback.

There are four options for mutator callbacks

• mutatorData - only called when data is loaded via a command {eg. setData).
• mutatorEdit - only called when data is changed via a user editing a cell.
• mutatorClipboard - only called when data is pasted into the table.
• mutatorImport - only called when data is imported into the table from the import file picker.
• mutator - called if the matching mutator from the above list is not set.

Each mutator function has its own matching params option, for example mutatorData has mutatorDataParams.

The example below will use the mutatorEdit function if a cell edit is performed otherwise it will use the mutator function .

var ageMutator = function(value, data, type, params, component){
    //change age value into boolean, true if over the provided legal age
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", mutator:ageMutator, mutatorParams:{legalAge:16}, mutatorEdit:ageMutator, mutatorEditParams:{legalAge:18} }

Mutators vs Formatters
An important difference between a mutator and a formatter is that a mutator will alter the data contained in the table, which will then be visible in the data retrieved using the getData function, a formatter will only alter how data is displayed in cells but will not affect the data itself. (see Formatting for more details)

Linked Mutators

You may want to make a column that calculates its value based on the value of other columns, for example:

[
    {title:"a", field:"a"},
    {title:"b", field:"b"},
    {title:"c", field:"c", mutator:function(value, data){
        return data.a + data.b;
    }},
]

In this case it is likely that you would want the value in column c to be updated when the user changes the value in columns a or b. But this wont happen by default. Mutators are only run when the data is initially loaded into the table, and when the value of a specific cell is changed.

o keep processing to a minimum, Tabulator will only run mutators on cells with changed values, not all cells in a row.

You can use the mutateLink option on a column definition to tell it to trigger the mutation of another column when its value has changed. You can pass in a string of the field name of the column to be mutated, or an array of field name strings if you want more than one mutator triggered.

[
    {title:"a", field:"a", editor:"number", mutateLink:"c"}, //trigger "c" column mutator when edited
    {title:"b", field:"b", editor:"number", mutateLink:"c"}, //trigger "c" column mutator when edited
    {title:"c", field:"c", mutator:function(value, data){
        return data.a + data.b;
    }},
]

Accessors

Accessors are used to alter data as it is extracted from the table, through commands, the clipboard, or download.

You can set accessors on a per column basis using the accessor option in the column definition object.

You can pass an optional additional parameter with accessor, accessorParams that should contain an object with additional information for configuring the accessor.

The example below shows a usage case that ensures float values in a column are rounded down to integers before you retrieved the data.

//define custom accessor
var customAccessor = function(value, data, type, params, column, row){
    //value - original value of the cell
    //data - the data for the row
    //type - the type of access occurring  (data|download|clipboard)
    //params - the accessorParams object passed from the column definition
    //column - column component for the column this accessor is bound to
    //row - row component for the row

    return Math.floor(value); //return the new value for the cell data.
}

//column definition
{title:"Tax Owed (£)", field:"tax", accessorParams:{}, accessor:customAccessor}

Field Required
For a accessor to work the column definition must have a field property specified, otherwise the muator will not know which field to act on.

Params Lookup Function

If you want to dynamically generate the accessor params at the time the accessor is called you can pass a function into the property that should return the params object.

//define lookup function
function paramLookup(value, data, type, component, row){
    //value - original value of the cell
    //data - the data for the row
    //type - the type of access occurring  (data|download|clipboard)
    //column - column component for the column this accessor is bound to
    //row - row component for the row

    //do some processing and return the param object
    return {param1:"green"};
}

//column definition
{title:"Tax Owed (£)", field:"tax", accessor:customAccessor, accessorParams:paramLookup}

Accessor Types

Data can be altered whenever it enters the table, either through a command or through a clipboard copy event or through a download of the table. To allow you to have more control over how your data is altered, there are a variety of different accessor options you can pass your callback to instead of just the accessor callback.

There are four options for accessor callbacks

• accessorData - only called when data is extracted via a command {eg. getData).
• accessorDownload - only called when data is being converted into a downloadable file.
• accessorClipboard - only called when data is being copied into the clipboard.
• accessorPrint - only called when data is being printed.
• accessorHtmlOutput - only called when data is being turned into a HTML table for the getHtml function.
• accessor - called if the matching accessor from the above list is not set.

Each accessor function has its own matching params option, for example accessorDownload has accessorDownloadParams.

The example below will use the accessorDownload function if a data is downloaded to a file accessor function .

var ageAccessor = function(value, data, type, params, column, row){
    return value >= params.legalAge;
}

{title:"Under Age", field:"age", accessor:ageAccessor, accessorParams:{legalAge:16}, accessorDownload:ageAccessor, accessorDownloadParams:{legalAge:18} }

Built In Accessors

Tabulator comes with preconfigured accessors which are outlined below.

Row Number

The rownum accessor is an accompaniment to the rownum formatter to allow row numbers to be included in exported table data. In order for this to work you will need to make sure that you have set a field for the row number to be read from.

{title:"Example", formatter:"rownum", field:"rownum", accessor:"rownum"}