Mutators & Accessors

• Overview
• Mutators
• 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.
• 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)

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