topCalc New - the column calculation to be displayed at the top of this column(see Column Calculations for more details)

bottomCalc New - the column calculation to be displayed at the bottom of this column(see Column Calculations for more details)

topCalcParams New - additional parameters you can pass to the topCalc calculation function(see Column Calculations for more details)

bottomCalcParams New - additional parameters you can pass to the bottomCalc calculation function(see Column Calculations for more details)

Cell Events

cellClick - callback for when user clicks on a cell in this column (see Callbacks for more details)

cellDblClick - callback for when user double clicks on a cell in this column (see Callbacks for more details)

cellContext - callback for when user right clicks on a cell in this column (see Callbacks for more details)

cellTap New - callback for when user taps on a cell in this column, triggered in touch displays. (see Callbacks for more details)

cellDblTap New - callback for when user double taps on a cell in this column, triggered in touch displays when a user taps the same cell twice in under 300ms. (see Callbacks for more details)

cellTapHold New - callback for when user taps and holds on a cell in this column, triggered in touch displays when a user taps and holds the same cell for 1 second. (see Callbacks for more details)

Column Headers

headerSort - user can sort by clicking on the header (see Sorting Data for more details)

headerClick - callback for when user clicks on the header for this column (see Callbacks for more details)

headerDblClick - callback for when user double clicks on the header for this column (see Callbacks for more details)

headerContext - callback for when user right clicks on the header for this column (see Callbacks for more details)

headerTap New - callback for when user taps on a header for this column, triggered in touch displays. (see Callbacks for more details)

headerDblTap New - callback for when user double taps on a header for this column, triggered in touch displays when a user taps the same header twice in under 300ms. (see Callbacks for more details)

headerTapHold New - callback for when user taps and holds on a header for this column, triggered in touch displays when a user taps and holds the same header for 1 second. (see Callbacks for more details)

tooltipHeader - sets the on hover tooltip for the column header (see Formatting Data for more details)

Available Options

As well as the required title and columns options, the following options can also be set on a column group:

headerClick - callback for when user clicks on the header for this column group (see Callbacks for more details)

headerDblClick - callback for when user double clicks on the header for this column group (see Callbacks for more details)

headerContext - callback for when user right clicks on the header for this column group (see Callbacks for more details)

Note: any of the click callbacks on the group header will also be triggered by clicking on any of the column headers in the group. To prevent this from happening put a matching binding on the column header and use the e.stopPropagation() function to prevent the group binding from being triggered.

Set Table Data

Tabulator row data is defined as an array of objects, that can either be passed as an array or retrieved as a JSON formatted string via AJAX from a URL.

The data can contain more columns that are defined in the columns options, these will be stored with the rest of the data, but not rendered to screen.

Data Mutation

Note: if you have defined any mutator functions in your column definition array, these will be applied to your data as it is being parsed into the table. (see Mutators for more details)

Row Index

A unique index value should be present for each row of data if you want to be able to programatically alter that data at a later point, this should be either numeric or a string. By default Tabulator will look for this value in the id field for the data. If you wish to use a different field as the index, set this using the index option parameter.

$("#example-table").tabulator({
index:"age", //set the index field to the "age" field.
});

If you wish to pass parameters with your request you can either include them in-line with the url string, or as an optional second parameter to the setData function. In the latter case they should be provided in the form of an object with key/value pairs.

A full list of the available config options can be found on the jQuery website.

Note: You MUST NOT set any of the following options in the advanced config option as they are set by Tabulator and needed for correct operation of the library:

url

async

dataType

success

error

Repeated Requests

If you always request the same url for your data then you can set it in the ajaxURL, ajaxParams & ajaxConfig options as needed when you create your Tabulator. This will cause the table to immediately load the data from the remote resource as soon as the table is created. These options take the same input options as the first second and third arguments of the setData function.

Ajax Response Alteration

Tabulator expects the response to an ajax request to be a JSON encoded string representing an array of data objects. If you need to pass other data back in your request as well, you can use the ajaxResponse callback to process the returned data before it is passed to the table. The return value of this callback should be an array of row data objects.

$("#example-table").tabulator({
ajaxResponse:function(url, params, response){
//url - the URL of the request
//params - the parameters passed with the request
//response - the JSON object returned in the body of the response.
return response.tableData; //return the tableData peroperty of a response json object
},
});

Ajax Filtering

If you would prefer to filter your data server side rather than in Tabulator, you can use the ajaxFiltering option to send the filter data to the server instead of processing it client side

Note: This approach can only be used for text, numeric and boolean options, for callbacks and functions you will need to use the constructor object outlined below.

Complex Options Setup

If you need to set up any column options on the imported table you can declare these in table constructor as you would do for any other table. It is important to note that the title parameter for each column definition must match the text in the table element's header cell exactly for the imported data to link to the correct column.

If you use a column definition array in the Tabulator constructor, the order of columns in this array will take priority over the order of the columns in the table element.

Mutators & Accessors Updated

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.

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

{title:"Has Too Many Cars", field:"cars", mutatorParams:{threshold:5}, mutator:function(value, data, type, mutatorParams, cell){
//value - original value of the cell
//data - the data for the row
//type - the type of mutation occuring (data|edit)
//mutatorParams - the mutatorParams object from the column definition
//cell - when the "type" argument is "edit", this contains the cell component for the edited cell, otherwise it is undefined
return value > mutatorParams.threshold; //return the new value for the cell data.
},
}

Mutation Type

By default mutators are applied to data when it is parsed into the table with the setData function and when a user edits a cell. If you only want your mutators to be applied in one of these cases, you can use the mutateType option to specify when you want your mutator to be used.

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)

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)

buttonTick - displays a tick icon on eac row (for use as a button)

buttonCross - displays a cross icon on eac 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 defintion.

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

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)

Variable Height Formatters New

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 variableHieght property to true in the column definition and it will will behave in a similar way to the textarea formatter:

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.

Filters will remain in effect until they are cleared, including during setData calls.

Custom Filter Functions

If you want to perform a more complicated filter then you can pass a callback function to the setFilter method, you can also pass an optional second argument, an object with paramters to be passed to the filter function.

Setting this parameter to true will cause an editor element matching the columns editor type to be displayed in the header below the column title, and will allow the user to filter data in the table by values in that column. The editor will be chosen using the same rules as the editor parameter, for more information on this see the Manipulating Data section.

Alternatively you can pass a string to this parameter containing any of the standard editors listed in the Manipulating Data section

You can also pass a custom editor function to this parameter in the same way as you would for column editor. For more information see the Manipulating Data section.

You can pass an optional additional parameter with the header filter, headerFilterParams that should contain an object with additional information for configuring the header filter element. This will be passed to the editor in the column header instead of the editorParams property.

Note: At present, the progress and star editors are not available as header filters.

Header Filters and Programmatic Filters

Header filters and programatic filters can be set independently allowing you to use a header filter to further restrict the rows shown in an already filtered data set.

Real Time Filtering

If an input element is used as the filter element, then then the table will be filtered in real time as the user types in the input element. To prevent exessive redrawing of the table Tabulator will wait 300 miliseconds after the user has finished typing before tirggering the filter, this ensures that the table is not redrawn for every character typed by the user.

Note: If the input has a type attribute value of text it will be automatically changed to search to give the user the option to clear the input text.

Filter Comparison Types Updated

By default Tabulator will try and match the comparison type to the type of element used for the header filter.

Standard input elements will use the "like" filter, this allows for the matches to be displayed as the user types.

For all other element types (select boxes, check boxes, input elements of type number) an "=" filter type is used.

If you want to specify the type of filter used you can pass it to the headerFilterFunc option in the column definition object. This will take any of the standard filters outlined above or a custom function:

{title:"Age", field:"age", headerFilter:"input", headerFilterPlaceholder:"Max Age", headerFilterFunc:"<="} //show only rows with an age less than or equal the entered value

When using a custom filter function for a header filter, the arguments passed to the function will be slightly different from a normal custom filter function

Callbacks

Sorting Data

Tabulator allows you to sort the data in your table in any way you want.

By default Tabulator will attempt to guess which sorter should be applied to a column based on the data contained in the first row. It can determine sorters for strings, numbers, alphanumeric squences and booleans, anything else will be treated as a string.

To specify a sorter to be used on a column use the param property in the columns definition object

You can pass an optional additional property with sorter, sorterParams that should contain an object with additional information for configuring the sorter.

Custom Sorters

for advanced sorting can define a custom sorter function in the sorter option:

{title:"Name", field:"name", sorter:function(a, b, aData, bData, column, dir, sorterParams){
//a, b - the two values being compared
//aData, bData - the row objects for the values being compared (useful if you need to access additional fields in the row data for the sort)
//column - the column component for the column being sorted
//dir - the direction of the sort ("asc" or "desc")
//sorterParams - sorterParams object from column definition array
return a - b; //you must return the difference between the two values
},
}

The fifth paramter in this callback is a ColumnComponent for the column being fitered.

Header Sorting

By default all columns in a table are sortable by clicking on the column header, if you want to disable this behaviour, set the headerSort property to false in the column defintion array:

Sort Data on Load

When the table is first created it can be setwith an initial set of sorters. These can be set using the initialSort option. This will take the same sorter array as the setSort function. (see Initial Data Sorting for more details)

$("#example-table").tabulator({
initialSort:[
{column:"age", dir:"asc"}, //sort by this first
{column:"height", dir:"desc"}, //then sort by this second
]
});

Trigger Sorting Programmatically

You can trigger sorting using the setSort function

$("#example-table").tabulator("setSort", "age", "asc");

If you wish to sort by multiple columns then you can pass an array of sorting objects to this function, the data will then be sorted in the order of the objects.

$("#example-table").tabulator("setSort", [
{column:"age", dir:"asc"}, //sort by this first
{column:"height", dir:"desc"}, //then sort by this second
]);

Get Current Sorters

If you need to retrieve the details of the currently sorted column at any point you can use the getSort function.

$("#example-table").tabulator("getSort");

This will return an array of sort objects with two properties, column a string of the field name for the sorted column, and dir a string of either "asc" or "desc" indicating the direction of sort.

[
{column:"age", dir:"asc"},
{column:"height", dir:"desc"}
]

If the table is not currently sorted then the array will be empty.

Clear All Sorters

To remove all sorting from the table, call the clearSort function.

$("#example-table").tabulator("clearSort");

Callbacks

A range of callbacks are avaialble for tracking progress of sorting. See the Sorting Callbacks section for more information.

Column Calculations New

Column calculations can be useed to add a row of calcualted values to the top or bottom of your table to display infmation such as the sum of a columns data.

There are two options that can be set in a column definition object to define a calculation, the topCalc option defines a calculation for the top of the column, and the bottomCalc defines a calculation for the bottom of the column. You can define, either, both or neither of the options.

{title:"Rating", field:"rating", topCalc:"avg"} //show average rating

Tabulator comes with a number of preconfigured calculations including:

avg - the average value of the column

optional topCalcParams/bottomCalcParams:

precision - the number of decimals to display (default is 2), setting this falue to false will display however many decimals are provided with the number

max - the maximum value in the column

min - the minimum value in the column

sum - a sum of all values in the column (only sums numerical columns)

concat - join all values into one string

count - a count of all non empty cells in the column

You can pass an optional additional parameter with the each calculation option, topCalcParams and bottomCalcParams that should contain an object with additional information for configuring the calculation function.

Calculations For Grouped Data

When you are using the groupBy option with your table, the calculation rows will be displayed differently. Instead of being displayed at the top and bottom of the table, they will be displayed inside each group, at the top and bottom of that group, showing the calculations for that group.

Editing & Manipulating Data Updated

Tabulator allows you to manipulate the data in the table in a number of different ways

Editable Data

Columns of the table can be set as editable using the editor parameter in the column definition. (see Define Columns for more details).

When a user clicks on an editable column the will be able to edit the value for that cell.

By default Tabulator will use an editor that matches the current formatter for that cell. if you wish to specify a specific editor, you can set them per column using the editor option in the column definition. Passing a value of true to this option will result in Tabulator applying the editor that best matches the columns formatter, if present.

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

textarea - editor for multi-line text, allows the row to vertically resize to fit the text as it is entered.

number - editor for numbers with increment and decrement buttons.

tick - editor for tick and tickCross columns.

star - editor for star columns (can use left/right arrow keys and enter for selection as well as mouse).

progress - editor for progress bar columns (can use left/right arrow keys and enter for selection as well as mouse)

Custom Editor

If you need a different type of editor, you can pass a custom editor function to the editor option. This function should take four parameters, a CellComponent for the cell being edited, a function to call when the cell has ben rendered, which can be used to set focus or tidy up the display after the element has become visible, a function to call to pass back the new value, when the user has successfully entered new data in the cell, and a function to call if the user aborts the edit.

Optional Editing

There are some circumstances where you may want to block editibility of a cell for one reason or another. To meet this need you can use the editable option. This lets you set a callback that is executed before the editor is built, if this callback returns true the editor is added, if it returns false the edit is aborted and the cell remains a non editable cell. The function has one paramter, the CellComponent of the cell about to be edited.

Data Mutationif you have defined any mutator functions in your column definition array, these will be applied to your edited value as it is being parsed into the table. (see Mutators for more details)

Updating Data

If you want to update an existing set of data in the table, without completely replacing the data as the setData method would do, you can use the updateData method.

This function takes an array of row objects and will update each row based on its index value. (the index defaults to the "id" parameter, this can be set using the index option in the tabulator constructor). Options without an index will be ignored, as will items with an index that is not already in the table data. The addRow function should be used to add new data to the table.

Update or Add Data

If the data you are passng to the table contains a mix of existing rows to be updated and new rows to be added then you can call the updateOrAddData function. This will check each row object provided and update the existing row if available, or else create a new row with the data.

Data Mutation if you have defined any mutator functions in your column definition array, these will be applied to the new data before the table is updated. (see Mutators for more details)

Retreiving Data Updated

Retrieve All Data

You can retrieve the data stored in the table using the getData function.

var data = $("#example-table").tabulator("getData");

This will return an array containing the data objects for each row in the table.

By default getData will return an array containing all the data held in the Tabulator. If you only want to access the currently filtered/sorted elements, you can pass a value of true to the first argument of the function.

Retrieve Row Data

To rereive the data of a specific row, you can retrieve the Row Component with the getRow function, then use the getData function on the component. The first argument is the row you are looking for, it will take any of the standard row component looukup options.

Data Accessors If you have defined any accessors on your columns, then these will be applied to the data before the data is returned from any of the above functions. (see Accessors for more details)

Retrieving Row ComponentsNew

You can retrieve all the row components in the table using the getRows function.

var rows = $("#example-table").tabulator("getRows");

This will return an array containing the Row Component for each row in the table.

By default getRows will return an array containing all the Row Component's held in the Tabulator. If you only want to access the currently filtered/sorted elements, you can pass a value of true to the first argument of the function.

Emptying the Table

Row Manipulation

There are a number of ways to manipulate individual rows in the table without affecting any other currently rendered rows.

Add Row

You can add a row to the table using the addRow function.

The first argument should be a row data object. If you do not pass data for a column, it will be left empty. To create a blank row (ie for a user to fill in), pass an empty object to the function.

The second argument is optional and determines whether the row is added to the top or bottom of the table. A value of true will add the row to the top of the table, a value of false will add the row to the bottom of the table. If the parameter is not set the row will be placed according to the addRowPos global option.

By default any new rows will be added to the bottom of the table, to change this to the top set the addRowPos option to "top";

If you want to add the row next to an existing row you can pass an optional third agument to the function that will position the new row next to the specified row (above or below based on the value of the second argument). This argument will take any of the standard row component looukup options:

Data Mutation if you have defined any mutator functions in your column definition array, these will be applied to the new data before the row is added. (see Mutators for more details)

Update Row

You can update any row in the table using the updateRow function.

The first argument is the row you want to update, it will take any of the standard row component looukup options.

The second argument should be the updated data object for the row. As with the updateData function, this will not replace the exisiting row data object, it will only update any of the provided parameters.

Once complete, this function will trigger the rowUpdated and dataEdited events.

This function will return true if the update was successfull or false if the requested row could not be found. If the new data matches the existing row data, no update will be performed.

If you already have the RowComponent for the row you wish to update, you can call the update function directly on the component:

row.update({"name":"steve"}); //update the row data for field "name"

Data Mutation if you have defined any mutator functions in your column definition array, these will be applied to the new data before the row is updated. (see Mutators for more details)

Update or Add Row

If you don't know whether a row already exists you can use the updateOrAddRow function. This will check if a row with a matching index exists, if it does it will update it, if not it will add a new row with that data. This takes the same arguments as the updateRow function.

Get Row Element

To rereive the jQuery element of a specific row, you can retrieve the RowComponent with the getRow function, then use the getElement function on the component. The first argument is the row you are looking for, it will take any of the standard row component looukup options.

Undo Action

With history enabled you can use the undo function to automatically undo a user action, the more times you call the function, the further up the history log you go.

$("#example-table").tabulator("undo");

If the keybindings extension is installed, this action can also be triggered with the ctrl + z key combination.

Redo Action

With history enabled you can use the redo function to automatically redo user action that has been undone, the more times you call the function, the further up the history log you go. once a user interactes with the table then can no longer redo any further actions until an undo is performed

$("#example-table").tabulator("redo");

If the keybindings extension is installed, this action can also be triggered with the ctrl + y key combination.

Navigation

When a cell is being edited it is possible to move the editor focus from the current cell to one if its neighbours. There are a number of functions that can be called to move the focus in different directions.

Note: These actions will only work when a cell is editable and has focus.

Note: Navigation commands will only focus on editable cells, that is cells with an editor and if present an editable function that returns true.

Previous Cell

Use the navigatePrev function to shift focus to the next editable cell on the left, if none available move to the right most editable cell on the row above.

$("#example-table").tabulator("navigatePrev");

If the keybindings extension is installed, this action can also be triggered with the shift + tab key combination.

Next Cell

Use the navigateNext function to shift focus to the next editable cell on the right, if none available move to left most editable cell on the row below.

$("#example-table").tabulator("navigateNext");

If the keybindings extension is installed, this action can also be triggered with the tab key combination.

Left Cell

Use the navigateLeft function to shift focus to next editable cell on the left, return false if none available on row.

$("#example-table").tabulator("navigateLeft");

Right Cell

Use the navigateRight function to shift focus to next editable cell on the right, return false if none available on row.

$("#example-table").tabulator("navigateRight");

Up Cell

Use the navigateUp function to shift focus to the same cell in the row above.

$("#example-table").tabulator("navigateUp");

If the keybindings extension is installed, this action can also be triggered with the up arrow key combination.

Down Cell

Use the navigateDown function to shift focus to the same cell in the row below.

$("#example-table").tabulator("navigateDown");

If the keybindings extension is installed, this action can also be triggered with the down arrow key combination.

Navigation from Cell Components

If you have a CellComponent, you can call navigation functions directly on the component. For more details see the CellComponent documentation

Callbacks

A range of callbacks are avaialble for tracking progress of data manipulation. See the Data Callbacks section for more information.

Table Layout Updated

Tabulator has tons of different ways of customizing the layout the table, have a look through the next few sections to see how you can configure your tables to meet your use case.

Fit Columns to Data

By default Tabulator will resize your tables columns to fit the data held in each column, unless you specify a width or minWidth in the column constructor. If the width of all columns exceeds the width of the containing element, a scroll bar will appear.

Fit Columns to Container

As an alternative to the default column fit you can use the fitColumns option to cause tabulato to resize columns so they fit perfectly in the available table width.

If a width is specified on any columns, where possible the columns will be set at this width and other columns will be resized around them. If there is not enough space to fit all the columns in, then all column widths are ignored and they are sized equally.

In this layout style at least one column must not have a width specified so it can be resized to fill any spare space.

To enable this layout mode set the fitColumns option to true in your table constructor object.

Responsive Layout

Responsive layout will automatically hide/show columns to fit the width of the Tabulator element. This allows for clean rendering of tables on smaller mobile devices, showing important data while avoiding horizontal scroll bars. You can enable responsive layouts using the responsiveLayout option.

By default, columns will be hidden from right to left as the width of the table decreases. You can choose exatly how columns are hidden using the responsive property in the column definition object.

When responsive layout is enabled, all columns are given a default responsive value of 1. The higher you set this value the sooner that column will be hidden as the table width decreases. If two columns have the same responsive value then they are hidden from right to left (as defined in the column definition array, ignoring user moving of the columns). If you set the value to 0 then the column will never be hidden regardless of how narrow the table gets.

Note: If you are using the fitColumns feature, you will need to set a minWidth property on the columns you want to respond responsively to ensure they are hidden when necessary, otherwise Tabulator will keep on reducing the width of the columns instead.

Frozen Columns

You can freeze the position of columns on the left and right of the table using the frozen property in the column definition array. This will keep the column still when the table is scrolled horizontally.

You can freeze any number of columns on the left or right of the table, but they must be next to eachother in the column definition array.

Tabulator builds the frozen columns by looking through the column definition array from both sides, building up the frozen columns as it see the frozen property. Once a non-frozen column is reached it stops building the frozen list for that side of the table.

Note: Frozen columns are locked in place and cannot be reordered by dragging and dropping the column header. It is also not possible to freeze a column that is part of a column group.

Redrawing the table

If the size of the element containing the Tabulator changes or you create a table before its containing element is visible, it will necessary to redraw the table to make sure the rows and columns render correctly.

This can be done by calling the redraw method. For example, to trigger a redraw whenever the viewport width is changed:

The redraw function also has an optional boolean argument that when set to true triggers a full rerender of the table including all data on all rows.

$(window).resize(function(){
$("#example-table").tabulator("redraw", true); //trigger full rerender including all data and rows
});

Virtual DOM Updated

As of version 3.0 tabulator renders its table using a Virtual DOM, this means that it only renders the rows you seen in the table (plus a few above and below the current view) and creates and destroys the rows as you scroll through the table. If no height is set the table will revert to the standard DOM mode and try and render all rows at once, which will have a performance impact on tables with a large number of rows.

This allows tabulator to handle thousands of rows with no overhead as it only processes the information it nedds to display.

In order for the virtual DOM to function correctly you must ensure that the height option is set in the table constructor, this can be set to any valid CSS value.

$("#example-table").tabulator({
height:"100%",
});

Note: It is not possible to externally add event bindings to elements in the table because they are created and destoryed by Tabulator as needed. The good news is there are callbacks and options to register almsost every binding through the setup options.

Render Buffer New

The virtual DOM renders a number of rows above and below the visible rows to ensure a smooth scrolling experience. This buffer will be set at the current of the height of table so there is always and additional tables height worth of rows above and beyond the view.

In some situations, where you have a full screen table with a large number of columns, this can result in slow rendering performance in older browsers. In these situations it is possible to manually set the height of the buffer in pixels using the virtualDomBuffer option. By setting this to a smaller number than the height you can reduce the number of rows that are rendered and increase the performance on older browsers.

Changing Table Height

If you want to manually change the height of the table at any time, you can use the setHeight function, which will also redraw the virtual DOM if necessary.

If the height of the table changes at any point (for example the height is set at a percentage and the user resizes the window), you will need to call the redraw function to ensure that the virtual DOM updates to display the corret number of rows.

$("#example-table").tabulator("redraw");

Standard DOM Exceptions

In order for the virtual DOM to function correctly it needs to know the height of the table, so you must ensure that the height option of the table is set so the table can calculate correctly what it should be displaying.

When pagination is enabled Tabulator will revert to using standard DOM rendering as it will only be displaying one page at a time.

Disabling the Virtual DOM

f you need to disable virtual rendering for any reason you can set the virtualDom option to false to force standard rendering.

Note: You must have the height option set to enable progressive rendering.

Empty Table Placeholder

You can use the placeholder option to display a message to your users when the table has no data set. The function can either take a string to display or, the HTML or jQuery element to display in the empty table.

Table Footer

The footer element that the tables uses for holding pagination elements etc, is automatically generated by Tabulator.

If you want to use your own element for any reason, for example you want to add aditional elements to the footer, then you can use the footerElement option to pass a jquery selector for the footer element into the table.

Callbacks

Pagination

If you would prefer to display your data as pages rather than a scrolling list Tabulator can help you out there too.

There are two forms of pagination available. local pagination, where Tabulator will parse in all available data and then paginate this data set. Or remote pagination, where Tabulator will load indiviudal pages of data via Ajax from a remote server.

When pagination is enabled, a footer element will be added to the bottom of the table, with a range of navigation controls to allow your users to easily switch between pages.

The first page of a table will automatically be loaded when the table is created if pagination is enabled.

If you are a Laravel user then you should find that the auto generated URL's and data processing work straight out the box with no aditional configuration needed.

Note: Changing the filter or sorting while pagination is enabled will revert the table back to the first page.

Note: Pagination and row grouping cannot be used togeather, enabling one will disable the other.

Remote Pagination

To enable remote pagination, set the pagination option to remote, and set the url for the Ajax request using the ajaxURL paramter. You can also pass an optional object to ajaxParams for any paramters you want to pass with the url (these should be static parameters, the page number etc, will be added later on).

By default the page size will be set by the amount of data returned by the remote server, if you need to tell the remote server how many rows to send you can set the paginationSize paramter.

Get Current Page Number

To retrieve the curren page use the getPage function. this will return the number of the current page. If pagination is disabled this will return false.

$("#example-table").tabulator("getPage"); // returns current page

Get Maximum Page Number

To retrieve the maximum available page use the getPageMax function. this will return the number of the maximum available page. If pagination is disabled this will return false.

$("#example-table").tabulator("getPageMax"); // returns maximum page

Custom Pagination Control Element

By default the pagination controls are added to the footer of the table. If you wish the controls to be created in another element pass a JQuery object for that element to the paginationElement option.

Note: Grouping and pagination cannot be used togeather, enabling one will disable the other.

Custom Group Headers

You can set the contents of the group headers with the groupHeader option. This should return the contents of the group header.

groupHeader:function(value, count, data){
//value - the value all members of this group share
//count - the number of rows in this group
//data - an arrya of all the row data objects in this group
return value + "<span style='color:#d00; margin-left:10px;'>(" + count + " item)</span>";
},

Group Open State

You can set the default open state of groups using the groupStartOpen property.

groupStartOpen:true,

This can take one of three possible values:

true - all groups start open (default value)

false - all groups start closed

function() - a callback to decide if a group should start open or closed

Group Open Function

If you want to decide on a group by group basis which should start open or closed then you can pass a function to the groupStartOpen property. This should return true if the group should start open or false if the group should start closed.

groupStartOpen:function(value, count, data){
//value - the value all members of this group share
//count - the number of rows in this group
//data - an arrya of all the row data objects in this group
return count > 3; //all groups with more than three rows start open, any with three or less start closed
},

Multi Level Grouping New

To set multiple levels of grouping, pass an array to the groupBy option. Each item in the array will be a sub-group of the previous item.

groupBy:["gender", "color"], //group by gender then favourite color

To then set the default open state of each of these levels you can pass an array to the groupStartOpen option.

Sub Group Styling

Each group header element is assigned a class based on its level in the grouping list. This allows you to differentiate between different gouping levels by styling thier classes. By default each level's headers are indented more than the last.

For example, all group headers in the first grouping level will be assigned the class tabulator-group-level-1

Note: You can have as many levels of subgroup as you like, but Tabulator only comes with indent styling built in for the first five levels of subgroup.

Changing Group Setup New

If you want to alter the structure of the groups after the table has been created there are a number of functions available.

Change the GroupBy Fields

You can use the setGroupBy function to change the fields that rows are grouped by. This function has one argument and takes the same values as passed to the groupBy setup option.

$("#example-table").tabulator("setGroupBy", "gender");

Change the Start Open States

You can use the setGroupStartOpen function to change the default open state of groups. This function has one argument and takes the same values as passed to the groupStartOpen setup option.

$("#example-table").tabulator("setGroupStartOpen", true);

Change the Header Formatter

You can use the setGroupHeader function to change the header generation function for each group. This function has one argument and takes the same values as passed to the groupHeader setup option.

$("#example-table").tabulator("setGroupHeader", function(value, count, data){
//value - the value all members of this group share
//count - the number of rows in this group
//data - an arrya of all the row data objects in this group
return count > 3; //all groups with more than three rows start open, any with three or less start closed
});

Note: If you use the setGroupStartOpen or setGroupHeader before you have set any groups on the table, the table will not update until the setGroupBy function is called.

Callbacks

A range of callbacks are avaialble for grouping. See the Group Callbacks section for more information.

Selectable Rows

Row selection allows users to select and highlight a number of rows that you can then take action on. This allows rows to be selected in a number of ways:

Clicking on a row, to toggle its state.

Holding down the shift key and click dragging over a number of rows to toggle the state of all rows the cursor passes over.

Programmatically with the selectRow and deselectRow functions.

To enable row selection, set the selectable option to true

$("#example-table").tabulator({
selectable:true,
});

The selectable option can take one of a several values:

false - selectable rows are disabled

true - selectable rows are enabled, and you can select as many as you want

integer - any integer value, this sets the maximum number of rows that can be selected (when the maximum number of selected rows is exceded, the first selected row will be deselected to allow the next row to be selected).

"highlight"(default) - rows have the same hover stylings as selectable rows but do not change state when clicked. This is great for when you want to show that a row is clickable but don't want it to be selectable.

Note: using the setData function will clear the currently selected rows.

Rolling Selection

By default, row selection works on a rolling basis, if you set the selectable option to a numeric value then when you select past this number of rows, the first row to be selected will be deselected. If you want to disabled this behaviour and instead prevent selection of new rows once the limit is reached you can set the selectableRollingSelection option to false.

Persistent Selection

By default Tabulator will maintain selected rows when the table is filtered, sorted or paginated (but NOT when the setData function is used). If you want the selected rows to be cleared whenever the table view is updated then set the selectablePersistance option to false.

Selection Eligibility

You many want to exclude certain rows from being selected. The selectableCheck options allows you to pass a function to check if the current row should be selectable, returning true will allow row selection, false will result in nothing happening. The function should accept a RowComponent as its first argument.

Note: Any selectable rows will be assigned the tabulator-selectable class, any unselectable rows will be assigned the tabulator-unselectable class.

Programmatic Row Selection

As well as clicking on a row, you can trigger the selection or deselection of a row programmatically.

Select Row

To programmatically select a row you can use the selectRow function.

To select a specific row you can pass the any of the standard row component looukup options into the first argument of the function. If you leave the argument blank you will select all rows (if you have set the selectable option to a numeric value, it will be ignored when selecting all rows).

This will allow users to drag rows around by clicking and dragging on any part of the row.

Note: When grouping is enabled, rows can only be moved within their own group.

Row Handles

If you would prefer the user only be able to move a column around by one particular cell, the you can set the rowHandle property to true in the column definition object for that column to restrict the trigger for row movment to that cell only.

Moving on Touch Devices

The jQuery library does not currently support touch events. To enable movable rows on a touch device, you will need to include the excellent touchpunch.js library which adds touch event support touch event support to jQuery.

Scroll To Row

If you want to trigger an animated scroll to a row then you can use the scrollToRow function. The first argument should be any of the standard row component looukup options for the row you want to scroll to.

Columns Definition - The column definition object for the column you want to add.

Before (optional) - Determines how to position the new column. A value of true will insert the column to the left of exisiting columns, a value of false will insert it to the right. If a Position argument is supplied then this will determine whether the new colum is inserted before or after this column.

Position (optional) - The field to insert the new column next to, this can be any of the standard column component looukup options.

Delete Column

To permanently remove a column from the table deleteColumn function. This function takes any of the standard column component looukup options as its first parameter.

$("#example-table").tabulator("deleteColumn", "name");

Alternativly if you have the ColumnComponent of the column you wish to delete, you can call the delete function directly on the component.

column.delete();

Get Column Definitions

To get the current column definition array (including any changes made through user actions, such as resizing or re-ordering columns), call the getColumnDefinitions function. this will return the current columns definition array.

If you are planning on having multiple tables on the same page using column persistence then Tabulator needs a way to uniquely identify each table. There are two ways to do this either set the id attribute on the element that will hold the Tabulator, Tabulator will automatically use this id as a reference for the persistence id.

<div id="example-table"></div>

Alternatively if you do not want to give an id to the table holding element you can set the tabulator options parameter persistentLayoutID to a unique persistence id for that table.

Note: If you update the column definition array after the the column layout has been stored you will have to change the persistentLayoutID or delete your cookies/local storage to clear out the old column layout information, otherwise you may get errors when your table renders.

Get Column Layout Information

If you want to handle column layout persistence manually, for example storing it in a database to use elsewhere, you can use the getColumnLayout function to retrieve a layout object for the current table.

var columnLayout = $("#example-table").tabulator("getColumnLayout");

Set Column Layout

If you have previously used the getColumnLayout function to retrieve a tables layout, you can use the setColumnLayout function to apply it to a table.

$("#example-table").tabulator("setColumnLayout", columnLayout);

Editable Column Titles

Column titles can be made user editable by setting the editableTitle parameter to true in a columns definition object.

{title:"Name", field:"name", editableTitle:true} //alow user to update this columns title

This will result in the columns title being displayed in an input element, that will let the user change the title.

After a the user changes a column title the colTitleChanged callback is triggered.

Bootstrap Theme

The stylesheet maps the standard bootstrap table styling onto Tabulator. If you have customised your bootstrap theme, then the /src/scss/bootstrap directory also contains a variables.scss file containing all the standard bootstrap variables. Make any changes in here to match your custom theme and recompile the tabulator_bootstrap.css file and Tabulator will now match your theme.

The theme also mape some of the standard table styling classes. You can use any of these classes on your tablutor element and get the same effect as bootstrap:

table-striped - alternating row colors

table-bordered - borders arround table and between cells

table-condensed - minimal cell and header padding

You can also apply the following classes to rows using the rowFormatter to get the same results as in bootstrap:

Semantic UI Theme

The stylesheet maps the standard semantic ui table styling onto Tabulator. If you have customised your theme, then the /src/scss/semantic-ui directory also contains the variables.scss and variables_table.scss files containing all the standard semantic ui variables. Make any changes in here to match your custom theme and recompile the tabulator_semantic-ui.css file and Tabulator will now match your theme.

The theme also mape some of the standard table styling classes. You can use any of these classes on your tablutor element and get the same effect as semantic ui:

striped - alternating row colors

celled - borders between cells

compact - minimal cell and header padding

very compact - almost no cell and header padding

padded - more cell and header padding

very padded - a lot more cell and header padding

The full range of colour classes can also be used:

inverted

red

orange

yellow

olive

green

teal

blue

violet

purple

brown

grey

black

You can also apply the following classes to rows or cells using the rowFormatter to get the same results as in semantic ui:

CSS Classes Updated

All elements of Tabulator have classes set to make theming your tables as easy as possible.

General Classes

Class

Element Description

tabulator

Tabulator container element

tabulator-tableHolder

Contain table and scroll bars

tabulator-table

Contain table rows

tabulator-loader

Ajax loader message holder

tabulator-loader-msg

Ajax loader message

tabulator-loading

Applied to .tabulator-load-msg to style a loading message

tabulator-error

Applied to .tabulator-load-msg to style an error message

tabulator-placeholder

The containing element for the empty table placeholder

tabulator-moving

Applied to rows and columns when they are being moved

tabulator-block-select

Applied to the .tabulator element when the mouse is dragging to prevent accidental text selection

tabulator-moving

Applied to rows and columns when they are being moved

Headers & Columns Updated

Class

Element Description

tabulator-header

Table header element

tabulator-headers

Hold all column headers inside table header

tabulator-calcs-holder

Hold column calculations row, appears in both header and footer

tabulator-col

Column header (in header row)

tabulator-col-content

Holds the contents for the column header

tabulator-col-title

Holds the text for the column header title

tabulator-col-group

Marks a column header as a group that contains other columns

tabulator-col-group-cols

Holds the column headers contained in a column group

tabulator-handle

Invisible resize handle on the right of each column header

tabulator-title-editor

The input box used for editing titles when the editableTitle option is set

tabulator-header-filter

The containing element for the header filter elements, when the headerFilter option is set

tabulator-sortable

Applied to columns with header sorting enabled

tabulator-frozen

The containing element for all frozen columns

tabulator-frozen-left

Applied to frozen columns on the left edge of the table

tabulator-frozen-right

Applied to frozen columns on the right edge of the table

Rows Updated

Class

Element Description

tabulator-row

Row of table

tabulator-row-odd

Odd numbered row

tabulator-row-even

Even numbered row

tabulator-cell

Data cell

tabulator-selectable

Styling for selectable rows

tabulator-unselectable

Styling for unselectable rows

tabulator-selected

Currently selected row

tabulator-editing

Applied to cells being edited and the rows that contain them

tabulator-group

The header element for a row group

tabulator-group-visible

Applied to .tabulator-group when the group is visible

tabulator-group-level-X

Applied to .tabulator-group to denote its level in multi level grouping, the X is replaced with the number of that grouping level

tabulator-calcs

A row that contains column calculations instead of data

tabulator-calcs-top

A column calculations row at the top of a group

tabulator-calcs-bottom

A column calculations row at the bottom of a group

Pagination

Class

Element Description

tabulator-footer

Tabulator footer element

tabulator-paginator

Contains the pagination controls

tabulator-pages

Contains individual page buttons

tabulator-page

Page selection button

SASS Variables

The packaged SASS theme files is included in the project with a number of setup variables to make theming a table even easier.

General

Variable

Default Value

Description

backgroundColor

#888

The background colour of the tabulator element

borderColor

#999

The border colour of the tabulator element

textSize

14

The text size for all text in the tabulator

Headers & Columns

Variable

Default Value

Description

headerBackgroundColor

#e6e6e6

The background colour for header cells

headerTextColor

#555

The header cells text colour

headerBorderColor

#aaa

The header cells border colour

headerSeperatorColor

#999

The header row bottom border colour

headerMargin

4

The size in pixels for the header cells margin

sortArrowActive

#666

The colour of the column sorter arrow when sorting is active on a column

sortArrowInactive

#bbb

The colour of the column sorter arrow when sorting is not active on a column

Rows

Variable

Default Value

Description

rowBackgroundColor

#fff

The background colour of the table rows

rowAltBackgroundColor

#e0e0e0

The background colour of the even numbered table rows

rowBorderColor

#fff

The table row border colour

rowTextColor

#333

The table row text colour

rowHoverBackground

#bbb

The table row background colour when hovered over.

rowSelectedBackground

#9ABCEA

The table row background colour when selected.

rowSelectedBackgroundHover

#769BCC

The table row background colour when selected and hovered over.

editBoxColor

#1D68CD

The border colour of a cell being edited.

Pagination

Variable

Default Value

Description

footerBackgroundColor

#e6e6e6

The footer background colour

footerTextColor

#555

The footer text colour

footerBorderColor

#aaa

The footer buttons border colour

footerSeperatorColor

#999

The footer element top border colour

Component Objects Updated

Component objects allow you to interact directly with various parts of your tables. They are usually passed in the arguments of callbacks and expose a range of functions that can be called directly on the object.

Row Component Updated

The row component provides access to a specific row. The example below shows how it is passed to the rowFormatter callback:

Get Index

Delete

The delete function deletes the row, removing its data from the table

row.delete();

Scroll To

The scrollTo function will scroll the table to the row if it passes the current filters.

row.scrollTo();

Update

You can update the data in the row using the update function. You should pass an object to the function containing any fields you wish to update. This object will not replace the row data, only the fields included in the object will be updated.

row.update({"name":"steve"}); //update the row data for field "name"

Select New

The select function will select the current row.

row.select();

Deselect New

The deselect function will deselect the current row.

row.deselect();

Toggle Selection New

The toggleSelect function will toggle the selected state the current row.

row.toggleSelect();

Normalize Height

If you are making manual adjustments to elements conained within the row, it may sometimes be necessary to recalculate the height of all the cells in the row to make sure they remain aligned. Call the normalizeHeight function to do this.

row.normalizeHeight();

Column Component

The column component provides access to a specific column. The example below shows how it is passed to the columnMoved callback.

Get Value

Get Old Value

The getOldValue function returns the previous value of the cell. Very usefull in the event of cell update callbacks.

var cellOldValue = cell.getOldValue();

Get Element

The getElement function returns the jQuery DOM element for the cell.

var cellElement = cell.getElement();

Get Row

The getRow function returns the RowComponent for the row that contains the cell.

var row = cell.getRow();

Get Column

The getColumn function returns the ColumnComponent for the column that contains the cell.

var column = cell.getColumn();

Get Data New

The getData function returns the data for the row that contains the cell.

var data = cell.getData();

Get Field New

The getField function returns the field name for the column that contains the cell.

var field = cell.getField();

Set Value

You can change the value of the cell using the setValue function. The first parameter should be the new value for the cell, the second optional parameter will apply the column mutators to the value when set to true(default = true).

cell.setValue("Steve", true); //set the cell's value to "Steve" and apply the column mutators if present

Check Height

If you are making manual adjustments to elements contained withing the cell, or the cell itself, it may sometimes be necessary to recalculate the height of all the cells in the row to make sure they remain aligned. Call the checkHeight function to check if the height of the cell has changed and normalize the row if it has.

cell.checkHeight();

Edit

You and programatically cause a cell to open its editor element using the edit function.

cell.edit();

Navigation

When a cell is being edited it is possible to move the editor focus from the current cell to one if its neighbours. There are a number of functions that can be called on the nav function to move the focus in different directions.

cell.nav().left(); //move focus left to next editable cell.

You can navigat any direction around the table using the following functions:

prev - next editable cell on the left, if none available move to the right most editable cell on the row above

next - next editable cell on the right, if none available move to left most editable cell on the row below

left - next editable cell on the left, return false if none available on row

right - next editable cell on the right, return false if none available on row

up - move to the same cell in the row above

down - move to the same cell in the row below

Group Component Updated

The group component provides access to a set of grouped rows. The example below shows how it is passed to the groupVisibilityChanged callback.

Get Element

The getElement function returns the jQuery DOM element for the gruop header.

var groupElement = group.getElement();

Get Key

The getKey function returns the unique key that is shared between all rows in this group.

var key = group.getKey();

Get Rows

The getRows function returns an array of RowComponent objects, one for each row in the group.

var rows = group.getRows();

Get Sub Groups New

The getSubGroups function returns an array of GroupComponent objects, one for each sub group of this group.

var subGroups = group.getSubGroups();

Get Parent Group New

The getParentGroup function returns the GroupComponent for the parent group of this group. if no parent exists, this function will return false

var parentGroup = group.getParentGroup();

Get Visibility

The getVisibility function returns a boolean to show if the group is visible, a value of true means it is visible.

var visible = group.getVisibility();

Show Group

The show function shows the group if it is hidden.

group.show();

Hide Group

The hide function hides the group if it is visible.

group.hide();

Toggle Visibility

The toggle function toggles the visibility of the group, switching between hidden and visible.

group.toggle();

Component Lookup

Any function that takes a component as and argument will also attempt to find that component based on the value provided if it is not a component iteslf. The following values can be used for each copmonent type:

Row

Column

Cell

Setup Options Updated

Tabulator has a wide range of setup options to help you customise the user experience of your tables. This section outlines all the available options and links to the relevant section in this documentation to show you how to use them.

Each of these options can be set in the constructor object when you define your Tabulator.

Boolean/function to set the open/closed state of groups when they are first created

addRowPos

string

"bottom"

The position in the table for new rows to be added, "bottom" or "top"

selectable

boolean/integer/string

"highlight"

Enable/Disable row selection

selectableRollingSelection

boolean

true

Allow rolling selection

selectablePersistence

boolean

true

Maintain selected rows on filter or sort

selectableCheck

function

(see documentation)

Check if row should be selectable or unselectable

movableRows

boolean

false

Allow users to move and reorder rows

Data

Option

Data Type

Default Value

Description

index

string

id

The field to be used as the unique index for each row

data

array

[]

Array to hold data that should be loaded on table creation

ajaxURL

string/boolean

false

URL for remote Ajax data loading

ajaxParams

object

{}

Parameters to be passed to remote Ajax data loading request

ajaxConfig

string/object

"GET"

The HTTP request type for Ajax requests or config object for the request

ajaxFiltering

boolean

false

Send filter config to server instead of processing locally

ajaxSorting

boolean

false

Send sorter config to server instead of processing locally

ajaxLoader

boolean

true

Show loader while data is loading

ajaxLoaderLoading

string

html (see below)

html for loader element

ajaxLoaderError

string

html (see below)

html for the loader element in the event of an error

When loading data, Tabulator can display a loading overlay over the table. This consists of a modal background and a loader element. The loader element can be set globally in the options and should be specified as a div with a display style of inline-block.

Column Header Double Tap New

The headerDblTap callback is triggered when a user taps on the column header on a touch display twice in under 300ms, it can be set on a per column basis using the option in the columns definition object.

Column Header Tap Hold New

The headerTapHold callback is triggered when a user taps on the column header on a touch display and holds their finger down for over 1 second, it can be set on a per column basis using the option in the columns definition object.

Cell Double Tap New

The cellDblTap callback is triggered when a user taps on a cell in this column on a touch display twice in under 300ms, it can be set on a per column basis using the option in the columns definition object.

Cell Tap Hold New

The cellTapHold callback is triggered when a user taps on a cell in this column on a touch display and holds their finger down for over 1 second, it can be set on a per column basis using the option in the columns definition object.

HTML Importing

The htmlImporting callback is triggered when Tabulator starts importing data from an HTML table.

$("#example-table").tabulator({
htmlImporting:function(){
},
});

HTML Imported

The htmlImported callback is triggered when Tabulator finishes importing data from an HTML table.

$("#example-table").tabulator({
htmlImported:function(){
},
});

Ajax Callbacks

Ajax Request

The ajaxRequesting callback is triggered when ever an ajax request is made.

$("#example-table").tabulator({
ajaxRequesting:function(url, params){
//url - the URL of the request
//params - the parameters passed with the request
},
});

Ajax Response

The ajaxResponse callback is triggered when a successful ajax request has been made. This callback can also be used to modify the received data before it is parsed by the table. If you use this callback it must return the data to be parsed by Tabulator, otherwise no data will be rendered.

$("#example-table").tabulator({
ajaxResponse:function(url, params, response){
//url - the URL of the request
//params - the parameters passed with the request
//response - the JSON object returned in the body of the response.
return response; //return the response data to tabulator
},
});

Ajax Error

The ajaxError callback is triggered there is an error response to an ajax request.

Row Selection Changed

Whenever the number of selected rows changes, through selection or deselection, the rowSelectionChanged event is triggered. This passes an array of the data objects for each row in the order they were selected as the first argument, and an array of jQuery elements for each of the rows in order of selection as the second argument.

$("#example-table").tabulator({
rowSelectionChanged:function(data, rows){
//rows - array of row components for the selected rows in order of selection
//data - array of data objects for the selected rows in order of selection
},
});

Key Bindings Updated

If you give a table focus by clicking on it, you can then interact with the table using the a number of different keyboard short cuts.

Action

Default Key Combination (keycode)

Function

navPrev

ctrl + tab ("ctrl + 9")

Shift focus to the next editable cell on the left, if none available move to the right most editable cell on the row above

navNext

tab ("9")

Shift focus to the next editable cell on the right, if none available move to left most editable cell on the row below

navLeft

Shift focus to next editable cell on the left

navRight

Shift focus to next editable cell on the right

navUp

up arrow ("38")

Shift focus to the same cell in the row above

navDown

down arrow ("40")

Shift focus to the same cell in the row below

undo

ctrl + z ("ctrl + 90")

Undo last user eata edit

redo

ctrl + y ("ctrl + 89")

Redo last user eata edit

scrollPageUp

Page Up ("33")

scroll page up by table height

scrollPageDown

Page Down ("34")

scroll page down by table height

scrollToStart

Home ("36")

scroll to first row

scrollToEnd

End ("35")

scroll to last row

Customize Key Bindings

If you would prefer to use different key combinations then that is no problem, you can use the keybindings option to change any of the above bindings.

The keybindings option takes an object that should consist of properties with the name of the action you wish to bind and a value of the key code string.

The key code should consist of the keycodes for the keys to be pressed, seperated by the + symbol. The exceptions to this are ctrl and shift which should be used to check that the ctrl or shift keys are pressed as well.

The example below shows how to change the key bindings for the redo function to user the ctrl and r keys:

To trigger a download, call the download function, passing the file type (from the above list) as the first argument, and an optional second argument of the file name for the download (if this is left out it will be "Tabulator.ext"). The optional third argument is an object containing any setup options for the formatter, such as the delimeter choice for CSV's).

$("#example-table").tabulator("download", "csv", "data.csv"); //download table data as a CSV formatted file with a file name of data.csv

Custom CSV Delimiters

By default CSV files are created using a comma (,) delimiter. If you need to change this for any reason the you can pass the options object with a delimiter property to the download function which will then use this delimiter instead of the comma.

Custom File Formatter

If you want to create a custom file type from the table data then you can pass a function to the type argument, instead of a string value. At the end of this function you must call the setFileContents function, passing the formatted data and the mime type.

Localization Updated

If you want to make your table accessible to users from a wide variety of languages then Tabulators localization features are for you.

Using the langs option you can specify the localized content for the table in any number of languages.

You can store as many languages as you like, creating an object inside the langs object with a property of the locale code for that language. A list of locale codes can be found here.

At present there are three parts of the table that can be localised, the column headers, the header filter placeholder text and the pagination buttons. To localize the pagination buttons, create a pagination property inside your language object and give it the properties outlined below.

If you wish you can also localize column titles by adding a columns property to your language object. You should store a property of the field name of the column you wish to change, with a value of its title. Any fields that match this will use this title instead of the one provided by the column definition array.

Setting the Locale

You can set the current local in one of two ways. If you want to set it when the table is created, simply include the locale option in your Tabulator constructor. You can either pass in a string matching one of the language options you have defined, or pass in the boolean true which will cause Tabulator to auto-detect the browsers language settings from the navigator.language object.

You can also set the language at any point after the table has loaded using the setLocale function, which takes the same range of values as the locale setup option mentioned above.

$("#example-table").tabulator("setLocale", "fr"); //set locale to french

Note: if Tabulator cant find a match, it will try and find the next best thing. For example if you were trying to set the locale to Belgian French "fr-be", if that option had not been defined, then Tabulator would go on to look for an"fr" option instead. if no matching locale is found then Then tabulator will default to using its built-in English language text.

When a localization event has occured, the localized callback will triggered, passing the current locale code and language object:

$("#example-table").tabulator({
localized:function(locale, lang){
//locale - a string representing the current locale
//lang - the language object for the current locale
},
});

Getting the Current Locale

It is possible to retrive the locale code currently being used by Tabulator using the getLocale function:

Extensions

Tabulator is built in a modular fashion with a core codebase providing basic table rendering functionality and a series of extensions that provide all of its wonderfull features.

All of the available extensions are installed by default to ensure that you can provide your users with the richest experience possible with minimal setup.

Creating a Custom Tabulator Build

If you want to run a minimal installation of Tabulator, using only the extensions needed for your project then you will need to rebuild a custom distribution using the steps below.

Tabulator's codebase is composed of a number of files located in the /src folder, and is built using the Gulp Task Runner. The gulpfile.js file that controls the build can be found in the root directory.

As gulp is an Node.js tool, you will first need to make sure you have Node.js installed.

Once installed you will then need to install the gulp plugin by opening a console window and typing the following command:

npm install gulp-cli -g

You will then need to setup the project by opening a console window in the root of the Tabulator directory and typing the following command:

npm install

You are now ready to make a custom build. The /src/extensions_enabled.js file lists all extensions that will be installed in the build (they are supposed to be in comments). To remove an extension from your build, simply delete its line in the file.

Once you are happy with the list of extensions that are going to be installed you need to trigger the build process. To do this open a console in the root of the Tabulator directory and run the following command:

gulp

Wait for the command to finish processing, then the /dist folder will contain your own custom build of Tabulator!

Extending Extensions

A lot of the extensions come with a range of default settings to make setting up your table easier, for example the sorters, formatters and editors that ship with Tabulator as standard.

If you are using a lot of custom settings over and over again (for example a custom sorter). you can end up re-delcaring it several time for different tables. To make your life easier Tabulator allows you to extend the default setup of each extension to make your custom options as easily accessible as the defaults.

Using the extendExtension function on the global Tabulator variable allows you to globally add these options to all tables.

The function takes three arguments, the name of the extension, the name of the property you want to extend, and an object containing the elements you want to add in your extension. In the example below we extend the format extension to add two new default formatters:

Ajax Requests (included in tabulator.js by default)

The default ajax configuration object can be extended to changed the default request behaviour. the example below will change the default request type to POST and the contentType header to application/JSON.

Default Options

If you always pass the same setup options to your Tabulator constructor object, you can also make these default by Aextending the jQuery widget, these will then automatically apply to any new Tabulator's unless the value is overwritten in construction object when you create a specific Tabulator.

This code must be inserted after the tabulator.js file is included but before any tables are instantiated.

For example the below code will cause all Tabulators to have resizable columns by default.