Formatting The Table

• Overview
• Cell Formatters
  • Built In Formatters
  • Custom Formatters
  • Variable Height Formatters
  • Column Header Formatting
• Icon/Button Columns
• Row Formatting
• Tooltips

Overview Demo

Tabulator allows you to format your data in a wide variety of ways, so your tables can display information in a more graphical and clear layout.

Cell Formatters

You can set cell formatters on a per column basis using the formatter option in the column definition object.

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

{title:"Name", field:"name", formatter:"star", formatterParams:{stars:6}}

Params Lookup Function

If you want to dynamically generate the formatterParams at the time the formatter 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:"Name", field:"name", formatter:"star", formatterParams:paramLookup}

Built In Formatters

Tabulator comes with a number of preconfigured formatters including:

• plaintext - This is the default formatter for all cells, and simply displays the value of the cell as text.
• textarea - shows text with carriage returns intact (great for multiline text), this formatter will also adjust the height of rows to fit the cells contents when columns are resized
• html - displays un-sanitized html
• money - formats a number into currency notation (eg. 1234567.8901 -> 1,234,567.89)
• optional formatterParams:
• decimal - Symbol to represent the decimal point (default ".")
• thousand - Symbol to represent the thousands separator (default ",")
• symbol - currency symbol (no default)
• symbolAfter - position the symbol after the number (default false)
• precision - the number of decimals to display (default is 2), setting this value to false will display however many decimals are provided with the number
• image - creates an img element wirh the src set as the value. (triggers the normalizeHeight function on the row on image load)
  • optional formatterParams:
  • height - a CSS value for the height of the image
  • width - a CSS value for the width of the image
• link - renders data as an anchor with a link to the given value (by default the value will be used as both the url and the label of the tag)
  • optional formatterParams:
  • labelField - the field in the row data that should be used for the link label
  • label - a string representing the label, or a function which must return the string for the label, the function is passed the Cell Component as its first argument
  • urlPrefix - a prefix to put before the url value (eg. to turn a emaill address into a clickable mailto link you should set this to "mailto:")
  • urlField - the field in the row data that should be used for the link url
  • url - a string representing the url, or a function which must return the string for the url, the function is passed the Cell Component as its first argument
  • target - a string representing the value of the anchor tags target artibute (eg. set to "_blank" to open link in new tab)
• datetime - transforms on format of date or time into another
  • You will need to include the moment.js library to use this formatter
  • optional sorterParams:
    • inputFormat - the format of the date/time in the row data(default: YYYY-MM-DD hh:mm:ss)
    • outputFormat - the format of the date/time to be displayed (default: DD/MM/YYYY hh:mm:ss)
    • invalidPlaceholder - the value to be displayed if an invalid input date/time is provided (default:""), this can take three different types of value:
      • true - a boolean of true will display the cells original value
      • function - a function passed into this will be called with the original value of the cell passed into its first argument
      • string/number - a string on number will be displayed instead of the cells value
• datetimediff - show difference between two datetimes
  • You will need to include the moment.js library to use this formatter
  • optional sorterParams:
    • inputFormat - the format of the date/time in the row data(default: YYYY-MM-DD hh:mm:ss)
    • date - a moment object of the data to compare against (defaults to the current date time)
    • humanize - if set to true diff will be displayed in a human readable fashion (eg "10 days") (default: false)
    • unit - the time using for the difference (years, months, weeks, days, hours, minutes, seconds). This property will be ignored if humanize is used (default:seconds)
    • suffix - if humanize is used setting this to true will make times relative (eg "10 days ago"). if humanize is not used the string passed to this will be appended after the difference value (default:false)
    • date - a moment object of the data to compare against (defaults to the current date time)
    • invalidPlaceholder - the value to be displayed if an invalid input date/time is provided (default:""), this can take three different types of value:
      • true - a boolean of true will display the cells original value
      • function - a function passed into this will be called with the original value of the cell passed into its first argument
      • string/number - a string on number will be displayed instead of the cells value
• tick - displays a green tick if the value is (true|'true'|'True'|1) and an empty cell if not
• tickCross - displays a green tick if the value is (true|'true'|'True'|1) and a red cross if not
  • optional formatterParams:
  • allowEmpty - set to true to cause empty values (undefined, null, "") to display an empty cell instead of a cross (default false)
  • allowTruthy - set to ture to allow any truthy value to show a tick (default false)
• color - sets the background colour of the cell to the value. Can be any valid CSS color eg. #ff0000, #f00, rgb(255,0,0), red, rgba(255,0,0,0), hsl(0, 100%, 50%)
• star - displays a graphical star rating based on integer values
  • optional formatterParams:
  • stars - maximum number of stars to be displayed (default 5)
• progress - displays a progress bar that fills the cell from left to right, using values 0-100 as a percentage of width
  • optional formatterParams:
  • min - minimum value for progress bar (default 0)
  • max - minimum value for progress bar (default 100)
  • color - colour of progress bar (default #2DC214), this can be:
  • string - any valid css color string (eg "#fff000")
  • array of strings - an array of color strings, that will divide the background colour across the min-max range of values(eg ["green", "orange", "red"])
  • function - a callback that is passed the value of the cell and must return the bar color (eg function(value){return "red"})
  • legend - a text value to display over the progress bar, this can be:
  • string - any string
  • true - if set to true this will show the value of the cell
  • function - a callback that is passed the value of the cell and must return the legend contents (eg function(value){return value + "%"})
  • legendColor - the text colour for the legend, has the same range of value options as the color property
  • legendAlign - the text alignment for the legend, this can be:
    • center - center align text (default)
    • left - left align text
    • right - right align text
    • justify - stretch out text to fit line
• lookup - looks up the value to display from a object passed into the formatterParams property, if not present it displays the current cell value
  • pass an object to formatterParams where the initial value of the cell is the property key and the value to be displayed is the property value (eg {"blue":"black", "red":"green"}, would change the value "blue" to "black", and the value "red" to "green")
• buttonTick - displays a tick icon on each row (for use as a button)
• buttonCross - displays a cross icon on each row (for use as a button)
• rownum - shows an incrementing row number for each row.
• handle - fills the cell with hamburger bars, to be used as a row handle

Note: To guard against code injection, any formatters that are meant to display text (plaintext, textarea, money, email, link) have the data sanitized first to escape any potentially harmful HTML or JavaScript from making into the table, this causes any such data to be displayed as its plain text alternative. If you want the HTML to be displayed correctly use the html formatter, but be aware if your data can be user edited this could allow for malicious script injection.

Note: For a guide to adding your own formatters to this list, have a look at the Extending Tabulator section.

Custom Formatters

As well as the built-in formatters you can define a formatter using a custom formatter function.

The formatter function accepts two arguments, the CellComponent for the cell being formatted and the formatterParams option from the column definition.

The function must return the contents of the cell, either the text value of the cell, valid HTML or a DOM node.

{title:"Name", field:"name", formatter:function(cell, formatterParams, onRendered){
    //cell - the cell component
    //formatterParams - parameters set for the column
    //onRendered - function to call when the formatter has been rendered

    return "Mr" + cell.getValue(); //return the contents of the cell;
},
}

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

Triggering Actions After the Formatter Has Been Displayed

The formatter code is run before the element is added to the DOM, on the whole this is not a problem, but some other libraries require the element they are attached to to be visible before they are run. To do this Tabulator provides the onRendered callback function.

To use this function you need to pass a callback that runs any of your required code as the only argument. The example below uses the jQuery sparkline widget to format data into a chart

var sparklineFormatter = function(cell, formatterParams, onRendered){
    onRendered(function(){
    $(cell.getElement()).sparkline(cell.getValue(), {width:"100%", type:"bar"});
});
};

Variable Height Formatters

By default formatters will keep their contents within the height of the current row, hiding any overflow. The only exception to this is the textarea formatter which will automatically vary its height when the column is resized so its contents does not overflow.

If you would like this functionally to appear in another type of formatter you can set the variableHeight property to true in the column definition and it will will behave in a similar way to the textarea formatter:

{title:"Name", field:"name", formatter:myCustomFormatter, variableHeight:true}

Column Header Title Formatters

You can use formatters to layout your column titles using the titleFormatter and titleFormatterParams options in a column's defintition object:

//column definition in the columns array
{title:5, field:"rating", titleFormatter:"star", titleFormatterParams:{stars:5}},

Params Lookup Function

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

//define lookup function
    function paramLookup(){
    //do some processing and return the param object
    return {param1:"green"};
}

//column definition
{title:5, field:"rating", titleFormatter:"star", titleFormatterParams:paramLookup}

Icon/Button Columns

You can create icon/button columns, by not specifying the field option in the column definition object and creating a custom formatter for the column contents. In the example below we have created a print button on the left of each row.

//custom formatter definition
    var printIcon = function(cell, formatterParams, onRendered){ //plain text value
    return "<i class='fa fa-print'></i>";
};

//column definition in the columns array
{formatter:printIcon, width:40, align:"center", cellClick:function(e, cell){alert("Printing row data for: " + cell.getRow().getData().name)}},

Row Formatting Demo

Tabulator also allows you to define a row level formatter using the rowFormatter option. this lets you alter each row of the table based on the data it contains.

The function accepts one argument, the RowComponent for the row being formatted.

The example below changes the background colour of a row to blue if the col value for that row is "blue".

var table = new Tabulator("#example-table", {
    rowFormatter:function(row){
    //row - row component

    var data = row.getData();

    if(data.col == "blue"){
        row.getElement().style.backgroundColor = "#1e3b20"; //apply css change to row element
    }
},
});

Re-Format Row

If you want to re-format a row once it has been rendered to re-trigger the cell formatters and the rowFormatter callback, Call the reformat function on its Row Component.

row.reformat();

ToolTips

You can set tooltips to be displayed when the cursor hovers over cells. By default, tooltips are not displayed.

Tooltips can either be set globally using the tooltips options parameter:

var table = new Tabulator("#example-table", {
    tooltips:true,
});

Or on a per column basis in the column definition array:

//column definition in the columns array
{formatter:printIcon, width:40, align:"center", tooltip:true},

The tooltip parameter can take three different types of value

• boolean - a value of false disables the tooltip, a value of true sets the tooltip of the cell to its value
• string - a string that will be displayed for all cells in the matching column/table.
• function - a callback function that returns the string for the cell. see below:

The function accepts one argument, the CellComponent for the cell the tooltip is being generated for.

var table = new Tabulator("#example-table", {
    tooltips:function(cell){
    //cell - cell component

    //function should return a string for the tooltip of false to hide the tooltip
    return  cell.getColumn().getField() + " - " + cell.getValue(); //return cells "field - value";
},
});

Note: setting a tooltip value on a column will override the global setting.

Tooltip Generation Mode

By default Tabulator regenerates tooltips whenever data in a cell changes, however if you use a tooltip generation function that is dependent on values outside the cell this may mean the tooltip does not update as expected.

To get round this, you can use the tooltipGenerationMode parameter to make tooltips regenerate whenever the users mouse enters the cell. The parameter can have one of two values

• load - Generate tooltip when value is loaded into cell (default behaviour)
• hover - Generate tooltip when users mouse enters the cell

var table = new Tabulator("#example-table", {
    tooltipGenerationMode:"hover", //regenerate tooltip as users mouse enters the cell;
});

Column Header ToolTips

It is also possible to set tooltips to display on the column headers. This is particularly useful when your columns are too narrow to display full header names.

Header tooltips can either be set globally using the tooltipsHeader options parameter:

var table = new Tabulator("#example-table", {
    tooltipsHeader:true, //enable header tooltips
});

Or on a per column basis in the column definition array:

//column definition in the columns array
{title:"name", field:"name", width:40, align:"center", headerTooltip:true},

The tooltip headerTooltip can take three different types of value

• boolean - a value of false disables the tooltip, a value of true sets the tooltip of the column header to its title value.
• string - a string that will be displayed for the tooltip.
• function - a callback function that returns the string for the column header. see below:

The function accepts one argument, the ColumnComponent for the column the tooltip is being generated for.

var table = new Tabulator("#example-table", {
    tooltips:function(column){
    //column - column component

    //function should return a string for the header tooltip of false to hide the tooltip
    return  column.getDefinition().title;
},
});

Note: setting a headerTooltip value on a column will override the global setting.