Quickstart Guide
Overview
This section will provide you with a quick guide to get your table up and running along with a brief introduction to some of Tabulators more advanced features.
Once you have finished this guide, have a look through the rest of the documentation and the examples page to get a better understanding of the power of Tabulator.
Install Sources
There are a number of ways you can include the Tabulator source in your project.
Package Managers
Tabulator is available to pull from a range of popular package managers:
Yarn
To get Tabulator via the yarn package manager, open a terminal in your project directory and run the following command:
yarn add tabulator-tables
NPM
To get Tabulator via the NPM package manager, open a terminal in your project directory and run the following command:
npm install tabulator-tables --save
Bower
To get Tabulator via the Bower package manager, open a terminal in your project directory and run the following command:
bower install tabulator --save
Git Clone
If you use the Git CVS you can clone the repository directly to your computer with the following terminal command:
git clone https://github.com/olifolkerd/tabulator.git
Download
You can download the source as a zip file from here.
CDN - UNPKG
To access Tabulator directly from the UNPKG CDN servers, include the following two lines at the start of your project, instead of the locally hosted versions:
<link href="https://unpkg.com/tabulator-tables@5.0.10/dist/css/tabulator.min.css" rel="stylesheet"> <script type="text/javascript" src="https://unpkg.com/tabulator-tables@5.0.10/dist/js/tabulator.min.js"></script>
Latest Version Tracking
If you want your code to track the latest version of Tabulator, then use the following lines of code, when a new version of Tabulator is released it will automatically be available on these links:
<link href="https://unpkg.com/tabulator-tables/dist/css/tabulator.min.css" rel="stylesheet"> <script type="text/javascript" src="https://unpkg.com/tabulator-tables/dist/js/tabulator.min.js"></script>
Include Library
Once you have pulled the source into your project it is time to include the Tabulator library in your code
Importing
If you are using Tabulator in an environment that supports JavaScript Importing importing then you should use the import statement. Tabulator has a range of import options, for full details checkout the Install Guide
import {TabulatorFull as Tabulator} from 'tabulator-tables';
In this case you will also need to import the the appropriate stylesheets into your project, for an SCSS project this would be:
@import "~/tabulator-tables/dist/css/tabulator.min.css";
Dist Files
If you are working in a browser environment where you want to load the files directly in browser then you will need to pull in both the tabulator.js and tabulator.css files. These come in both minified and unminified variants
Minified
<link href="dist/css/tabulator.min.css" rel="stylesheet"> <script type="text/javascript" src="dist/js/tabulator.min.js"></script>
Unminified
<link href="dist/css/tabulator.css" rel="stylesheet"> <script type="text/javascript" src="dist/js/tabulator.js"></script>
CDN ESM Import
If your browser environment supports ESM module importing then you can also import the module directly from the CDN
import {Tabulator} from 'https://unpkg.com/tabulator-tables@5.0.10/dist/js/tabulator_esm.min.js';
The Virtual DOM and Table Rendering
Before you build your first table, it might be useful to know a bit about how Tabulator works.
Virtual DOM
Tabulator uses a virtual DOM to enable it to process 100,000's of rows without a performance overhead.
The virtual DOM works by only building the rows that are visible on the screen. As you scroll through the table, rows are created and destroyed as they enter/leave the of the visible area of the table.
This also means that it is a bad idea to try to use code outside of Tabulator to directly alter or bind events to DOM elements inside the table, because there is a good chance that the element you are trying to manipulate will be destroyed on the next scroll. Tabulator has a wide range of callbacks, formatters and other functions that allow you to manipulate the table contents in a way that is safe and wont be affected by the rows being recreated.
In order for the virtual DOM to work, Tabulator needs to know how big the table is. This means that you must set a height for the table element to engage the virtual DOM, this can be in the CSS, an inline style, or using the height property in the table constructor.
If there is no height set on the table the Tabulator cannot use the virtual DOM, and the table will be rendered with no scroll bar, taking up as much space as is needed to show all rows at once. In this mode it will be very slow to render large numbers of rows.
Table Visibility
Because Tabulator builds its elements on the fly, it needs to be visible when it is populated with data to be able to make the calculations required to layout the table correctly, because hidden elements have no dimension in the DOM.
If you initialise a table or call the setData function while the table is hidden you may find graphical errors in the table when you next make it visible.
To get round this issue you can call the redraw function on the table when you make it visible, which will force Tabulator to recalculate the layout of all the cells in the table.
Example Setup
This section outlines the process of setting up for your first table in four easy steps.
A demo of basic table setup on a boilerplate HTML page can be found here.
Examples showing how to set up a wide variety of Tabulators features can be found in the Documentation Section.
1 Create your DOM element
<div id="example-table"></div>
2 Define some data for the table
//define some sample data
var tabledata = [
{id:1, name:"Oli Bob", age:"12", col:"red", dob:""},
{id:2, name:"Mary May", age:"1", col:"blue", dob:"14/05/1982"},
{id:3, name:"Christine Lobowski", age:"42", col:"green", dob:"22/05/1982"},
{id:4, name:"Brendon Philips", age:"125", col:"orange", dob:"01/08/1980"},
{id:5, name:"Margret Marmajuke", age:"16", col:"yellow", dob:"31/01/1999"},
];
3 Turn element into a Tabulator by passing a constructor object to the tabulator jQuery widget
//create Tabulator on DOM element with id "example-table"
var table = new Tabulator("#example-table", {
height:205, // set height of table (in CSS or here), this enables the Virtual DOM and improves render speed dramatically (can be any valid css height value)
data:tabledata, //assign data to table
layout:"fitColumns", //fit columns to width of table (optional)
columns:[ //Define Table Columns
{title:"Name", field:"name", width:150},
{title:"Age", field:"age", hozAlign:"left", formatter:"progress"},
{title:"Favourite Color", field:"col"},
{title:"Date Of Birth", field:"dob", sorter:"date", hozAlign:"center"},
],
});
//trigger an alert message when the row is clicked
table.on("rowClick", function(e, row){
alert("Row " + row.getData().id + " Clicked!!!!");
});
4 SMILE - You are all setup and ready to go!