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

Renderers

Overview

Tabulator uses renderers to take the internal component objects and lay them out in the table grid.

All renderers extend the base Renderer class that provides a standard interface for the Tabulator core to trigger the various functions needed to correctly display the table.

The renderer class implements functions for both vertical rendering (laying out rows) and horizontal rendering (laying out columns).

Buiding A Custom Renderers

You can build out a custom renderer by importing and extending the Renderer class

import {Tabulator, Renderer} from 'tabulator-tables';

//define renderer
class CustomRenderer extends Renderer{
  //build out your renderer
}

You can then pass your class into either the renderVerticalrenderHorizontal options

//define table
var table = new Tabulator("#example-table", {
    renderVertical:CustomRenderer,
});

Initialization

When a render is first instantiated the table is still in the process of being setup, so while it is safe to setup an internal variables for the renderer inside its constructor function, it is not safe to access any other parts of the table.

If you are going to implement a constructor in your class then you must take the table passed into the first argument of the constructor and pass it to the super function to ensure that the renderer is correctly setup.

When the table is ready, the initialize function will then be called, this is where you can then setup anything based on table options

class CustomRenderer extends Renderer{
    constructor(table){
        super(table);
    }

    initialize(){
        this.buffer = this.options("renderVerticalBuffer"); //set internal variable from table setup options when the table is ready
    }
}

Renderer Interface

A renderer can implement vertical render functions only, horizontal render functions only, or both horizontal and vertical functions depending on how you want it to handle layout tasks.

All built-in Tabulator renderers currently only implment one or the other set of functions.

The sections below will take you through the functions you need to implement to build a functional renderer.

Vertical Renderer Interface

If this is your first time building a vertical renderer then it would be worth taking a look at the source code for the basic renderer first to get an idea for how it all fits together. This can be found in the /src/js/core/renderers/BasicVertical.js file.

If you choose to create a vertical renderer then it must implement all of the following functions in order to work correctly

Clear Rows

When the clearRows function is called, the renderer should clear down all rows on the table

clearRows(){
    while(this.tableElement.firstChild) this.tableElement.removeChild(this.tableElement.firstChild);
}

Render Rows

The renderRows function is called when the table should be cleared down of all data and have a new set of rows drawn.

renderRows(){
    //render rows
}

Re-Render Rows

The rerenderRows function is called when the table should be rerendered in the same scroll position as it currently is. so all data should be removed and replaced but it should maintain its previous scroll position. It is passed one argument, a optional callback that should be triggered after the render is complete

rerenderRows(callback){
    //re-render rows

    if(callback){
        callback();
    }
}

Table Resize

The resize function is called whenever the size of the table changes, in case you need to make any changes to your layout

resize(){
    //hanlde resize of table display area
}

Visible Rows

When called, the visibleRows function should return an array of internal row components for all currently visible rows. It is passed on optional argument, a boolean, when true you should return all visible rows, plus any not visible buffer rows you may be using

visibleRows(includingBufer){
    if(includingBufer){
        //return currently visible rows and any in the display buffer (if you are using one)
    }else{
        //return only currently visible rows
    }
}

Scroll Rows

The scrollRows function is called whenever the user vertically scrolls the table. It is passed two arguments, the first is the distance scrolled in pixels, the second is a boolean representing the direction, a value of true means the table is scrolling up, otherwise it is down

scrollRows(distance, up){
    //hanlde table scroll
}

Scroll To Row

The scrollToRow function is called whenever a user requests to scroll to a particular row. It is passed one argument, the component for the row to be scrolled to. It should then scroll that row into view on the table

scrollToRow(row){
    //scroll to the provided row
}

Scroll To Row Nearest Top

The scrollToRowNearestTop function is called to find out if a particular row is nearest the top or bottom of the table. It is passed one argument, the component for the row. and it should return a boolean, with true meaning the row is nearest the top and false meaning it is nearest the bottom

scrollToRowNearestTop(row){
    return isNearestTop ? true : false;
}

Horizontal Renderer Interface

If this is your first time building a horizontal renderer then it would be worth taking a look at the source code for the basic renderer first to get an idea for how it all fits together. This can be found in the /src/js/core/renderers/BasicHorizontal.js file.

If you choose to create a horizontal renderer then it must implement all of the following functions in order to work correctly

Work In Progress
This renderer is a work in progress, as such the functions are likely to change over the course of this release.

Render Columns

The renderColumns function is called when the table should be cleared down of columns and a new set drawn.

renderColumns(){
    //render columns
}

Re-Render Columns

The rerenderColumns function is called when the table should be rerendered in the same scroll position as it currently is. so all data should be removed and replaced but it should maintain its previous scroll position. It is passed two arguments, the first argument is a boolean that should be true if the table columns have been updated, the second argument is a boolean that should be true if the column layout should not be redrawn

rerenderColumns(update, blockRedraw){
    //re-render columns
}

Reinitialize Column Widths

The reinitializeColumnWidths function is called to reset the widths of each column to fit its data. it is passed in an array of the columns to be resized.

    reinitializeColumnWidths(columns){
    //render columns
}

Render Cells In Row

The renderRowCells function is called a newly initialized row is ready to be populated by cells and should fill the rows element with the appropriate cells. It is passed in the row to be initialized

    renderRowCells(row){
    //render columns
}

Rerender Cells In Row

The rerenderRowCells function is called to rerender a rows cells if they have not yet been initialized. Its first argument is the row to be initialized. The second is a boolean that indicates if the reinitialization should be foreced if the row is already initialized.

rerenderRowCells(row, force){
    //render columns
}

Scroll Columns

The scrollColumns function is called whenever the user horizontally scrolls the table. It is passed two arguments, the first is the distance scrolled in pixels, the second is a boolean representing the direction, a value of true means the table is scrolling left, otherwise it is right

scrollColumns(distance, up){
    //hanlde table scroll
}

Helper Functions

The Renderer class also comes with a number of built in helper functions to make integrating it with the table easier.

Element Props

There are three properties set on a renderer that point to the key DOM elements used for laying out the table

Row Holder Element

The elementVertical property is the containing element for all table rows, it holds the overflow scrollbar for vertical movement

this.elementVertical

Table Element

The tableElement property is the DOM element that holds the table data inside the row holder element

this.tableElement

Column Header Holder Element

The elementHorizontal property is the containing element for all column header5s, it holds the overflow scrollbar for horizontal movement

this.elementHorizontal

Display Rows

If you are implementing a vertical renderer it will need to be able to access the vertical rows to be displayed on the table. These are accessible through the rows function. This will return an array of internal row components to display on the table.

var rows = this.rows()

Row Styling

In order to display the odd/event row styling on row elements, a vertical renderer needs to apply styles to the row. To simplify this process the styleRow function can be called, being passed in the internal row component and its position in the table, and it will apply the classes to the rows element for you

this.styleRow(row, 12); //style the 12th row in the table

Table Options

Renderers can access table options in the same way as modules, for full details on how to use this functionality, checkout the Module Building Documentation

Interal Events

Renderers can dispatch internal events in the same way as modules, for full details on how to use this functionality, checkout the Module Building Documentation

External Events

Renderers can dispatch external events in the same way as modules, for full details on how to use this functionality, checkout the Module Building Documentation

Reserved Function Names

In addition to the functionality outlined above the Renderer class also implements several peices of core functionality that it is not advisable to override unless you have a detailed understanding of the inner workings of Tabulator.

For this reason, it is recommended that you do not override the following functions on the Renderer class:

  • clear
  • render
  • rerender
  • scrollToRowPosition

Donate