Renderers
- Overview
- Buiding A Custom Renderers
- Vertical Renderer Interface
- Horizontal Renderer Interface
- Helper Functions
- Reserved Function Names
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