tables-js
v1.1.19
Published
Simple, dynamic, and customizable HTML table generator for vanilla JavaScript. Includes CSV, TSV, and JSON to HTML table conversion.
Downloads
20
Maintainers
Readme
tables.js Version 1.1.x
Note: This is a work in progress. If you find any bugs, please report them on the GitHub repository.
Description
The power of tables.js comes from the dynamic nature of the Table class. While jQuery Datatables is a great tool, and it's customizable, I want to expand on its functionality. You can combine datatables with this tool by just setting options.datatable = true
or options.datatable = { ...datatableOptions }
. I have added state management and independent cell/row/column rendering through the object the Table class creates. My goal is for you to have full customizability over your tables
Installation
<!-- Most recent version -->
<script src="https://cdn.jsdelivr.net/npm/tables-js/tables.min.js"></script>
<!-- Specific version -->
<script src="https://cdn.jsdelivr.net/npm/tables-js/1.1/tables.min.js"></script> <!-- Uses Table Class -->
<script src="https://cdn.jsdelivr.net/npm/tables-js/1.0/tables.min.js"></script> <!-- Uses setTable -->
It is recommended that tables.js be used with Bootstrap, jQuery, jQuery Datatables, and Material Icons, but it is not required. If you want to use tables.js with Bootstrap, jQuery, and jQuery Datatables, you can use the following code:
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/5.2.1/css/bootstrap.min.css">
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js"></script>
<script src="https://cdn.datatables.net/1.10.24/js/jquery.dataTables.min.js"></script>
<script src="https://cdn.datatables.net/1.10.24/js/dataTables.bootstrap4.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/js-tables/1.1/tables.js"></script>
Usage
Initialize the table with the following code:
const table = document.getElementById("my-table");
const headers = ["Name", "Age", "Favorite Color"]; // these can be objects as well
const data = [
{
Name: "John",
Age: 20,
"Favorite Color": "Blue"
},
{
Name: "Jane",
Age: 21,
"Favorite Color": "Red"
}
];
const options = { // optional
// options go here
};
const myTable = new Table(table, headers, data, options);
Generating from Various Data Types
JSON
const myTable = Table.from(table, json, options, 'json'); // 'json' may not be necessary as the function attempts to detect the type of data.
// or
const myTable = Table.fromJSON(table, json, options);
CSV
const myTable = Table.from(table, csv, options, 'csv'); // 'csv' may not be necessary as the function attempts to detect the type of data.
// or
const myTable = Table.fromCSV(table, csv, options);
TSV
const myTable = Table.from(table, tsv, options, 'tsv'); // 'tsv' may not be necessary as the function attempts to detect the type of data.
// or
const myTable = Table.fromTSV(table, tsv, options);
HTML
const myTable = Table.from(table /* already populated table */, null /* Data is in the prerendered table */, options, 'html'); // 'html' may not be necessary as the function attempts to detect the type of data.
// or
const myTable = Table.fromHTML(table, options);
Custom Table Classes
Table
class Table {
/* properties */
el // the table element
headers // the headers
data // the data
originalData // data before any filters/sorting/inserting/deleting
options // the options
states // the Table_StateStack object
rows // the array of TableRow objects
tableHeaders // the array of TableHeader objects
columns // the array of TableColumn objects
/* public methods */
render() // renders the table
destroy(deleteData: Booean) // destroys the table (deleteData removes all data from the Table object)
/* public static methods */
static fromHTML(table: HTMLElement, options: Object) // creates a Table object from a populated html table
static fromJSON(table: HTMLElement, json: String, options: Object) // creates a Table object from a JSON string
static fromCSV(table: HTMLElement, csv: String, options: Object) // creates a Table object from a CSV string
static fromTSV(table: HTMLElement, tsv: String, options: Object) // creates a Table object from a TSV string
static from(table: HTMLElement, data: Object | null, options: Object | null, type: String | null) // autodetects the type of data and creates a Table object from your inputs
/* private methods */
showInsertRows(TableRow) // shows the insert rows above and below the TableRow (used with reorderable tables)
hideInsertRows() // hides the insert rows
renderRows() // renders the rows
renderHeaders() // renders the headers
sort() // used with sortable tables
update() // updates the table
renderFromContent() // renders the table from the content of the Table object (for use with editable tables)
/* getters */
get content() // returns the array of TableRow.content objects
get json() // returns JSON.stringify(this.content)
}
Table_StateStack
This class is an extension of js-state-stack and is used to keep track of the table's/cell's state. It is used to keep track of the table's state when editing, sorting, etc. It is not recommended to use this class directly.
TableRow
class TableRow {
/* properties */
cells // the array of TableCell objects
el // the tr element
data // the data passed into header.getData()
/* private methods */
render() // renders the row
/* getters */
get content() // returns an object of {headerTitle: tableCell.content}
}
TableHeader
class TableHeader {
/* properties */
el // the th element
options // the options (currently unused)
/* public methods */
changeContent(content) // changes the content of the header and rerenders the <td> element
/* private methods */
render() // renders the header
}
TableFooter
An extension of TableHeader
that is used with the footer
option. This has all the same properties and methods as TableHeader
.
TableColumn
class TableColumn {
/* properties */
cells // the array of TableCell objects (includes the header cell)
header // the TableHeader object
/* getters */
get content() // returns an array of the content of each cell in the column (includes the header cell)
}
TableCell
class TableCell {
/* properties */
el // the td or th element
colPos // the column position
rowPos // the row position
headerTitle // the header title
header // the TableHeader object
editable // the editable object in Table.options
stack // the Table_StateStack object
/* public methods */
onChange() // custom function that is called when the cell is changed (used with editable tables)
onCancel() // custom function that is called when the cell is cancelled (used with editable tables)
changeContent(content) // changes the content of the cell and rerenders the <td> element
/* private methods */
render() // renders the cell
}
ReorderInsertRow
This is only used with reorderable tables. These are the rows that hare hidden and shown when you drag over a row. They are used to insert a row above or below the row you are dragging over.
class ReorderInsertRow {
el // the tr element
row // the TableRow object that the insert row is above or below
/* private methods */
show() // shows the insert row
hide() // hides the insert row
}
Parameters
The Table Element
All you need to do is pass in the table element you want to use. This can be done in two ways:
const myTable = new Table(document.getElementById("my-table"));
or
const myTable = new Table("#my-table"); // you can use any selector you wish :)
Headers
The headers parameter is either an object where each key is the header name, or an array of objects or strings that generate each header and subsequent column. If you pass in an array of strings, the headers will be generated with the string as the header text and the data will be generated by row[headerTitle]. If you pass in an array of objects, you must specify the following properties:
header.title || header.name || header.key
which will be the string that the<th>
is populated withheader.getData
this must be a function that returns either a string to populate inside of the<td>
element usingtd.innerHTML
, or an element to populate inside of the<td>
usingtd.appendChild()
. If noheader.getData
is specified, it will returnrow[header.title || header.name || header.key]
.
All of these examples will make this in HTML:
<table>
<thead>
<tr>
<th>Name</th>
</tr>
</thead>
<tbody>
<tr>
<td>John</th>
</tr>
</tbody>
</table>
Object Array Header Example:
const headers = [{
title: 'Name',
getData: (row) => {
return row.name;
}
}];
const data = [{
name: 'John'
}];
const myTable = new Table("#my-table", headers, data);
String Array Header Example:
const headers = ['Name'];
const data = [{
Name: 'John' // notice how this must be the same capitalization as the header
}];
const myTable = new Table("#my-table", headers, data);
Object Header Example:
const headers = {
Name: {
getData: (row) => {
return row.name;
}
}
};
const data = [{
name: 'John'
}];
const myTable = new Table("#my-table", headers, data);
The other properties of the header objects are used to customize the columns.
All the properties below are written as header.property
. These properties are the same whether you pass in an array of objects or an object.
Changing the <td>
Elements
Classes
header.th.classes
is an array of strings that will be added to the <th>
element.
header.td.classes
is an array of strings that will be added to each <td>
element in this column.
header.td.classTests
is an array of objects that will be used to add classes to the <td>
element. Each object must have the following properties:
test
is a function that returns a boolean. If the function returns true, the class will be added to the<td>
element.class
(OPTIONAL) is a string that will be added to the<td>
element if thetest
function returns true.classes
(OPTIONAL) is an array of strings that will be added to the<td>
element if thetest
function returns true.
Example:
const headers = [{
title: 'Name',
th: {
classes: ['my-class', 'my-other-class'] // applies to <th>
},
td: {
classes: ['my-td-class', 'my-other'], // applies to <td>
classTests: [{
test: (row) => {
return row.name === 'John';
},
class: 'my-class' // applies to <td>
}, {
test: (row) => {
return row.name === 'John';
},
classes: ['my-class', 'my-other-class'] // applies to <td>
}]
}
}];
Attributes
header.td.attributes
is an array of objects that will be added to the <td>
element. Each object must have the following properties:
name
is a string that will be the name of the attribute.value
is a either a string that is the value of the attribute, or a function that returns a string that is the value of the attribute that passes in the row as a parameter.header.th.attributes
is an array of objects that will be added to the<th>
element.header.th.attrubutes[].value
can only be a string, not a function.
Example:
const headers = [{
title: 'Name',
td: {
attributes: [{
name: 'data-name',
value: 'John'
}, {
name: 'data-name',
value: (row) => { // row is a TableRow object
return row.name;
}
}]
},
td: {
attributes: [{
name: 'data-name',
value: 'John'
}]
}
}];
Event Listeners
All lisener arrays are structured the same way. Each object must have the following properties:
type
is a string that is the name of the event.callback
(v1.1.x) is a function that is the listener that passes in the event as a parameter. (Uses a different data structure than v1.0.x)action
(v1.0.x) is a function that is the listener that passes in the event as a parameter.
header.th.listeners
is an array of objects that will be added to the <th>
element.
header.td.listeners
is an array of objects that will be added to each <td>
element in this column.
Example:
const headers = [{
title: 'Name',
th: {
listeners: [{
event: 'click', // runs when the `<th>` is clicked
callback: (event) => { // v1.1.x
/*
event is an event object with the following expanded property:
- event.__row = TableRow object
*/
console.log(event);
}
}]
},
td: {
listeners: [{
event: 'click',
action: ({
event, // event object
row, // data row (custom data)
tableRow // TableRow object
}) => { // v1.0.x
console.log(event);
}
}]
}
}];
Sorting
header.sort
is a sorting function that runs when the header is clicked. It sorts through the data and rerenders the table. This does not change table.originalData
, only table.data
. Currently, if you click it once, it sorts up, click again, it sorts down, and click again, it sorts back to the original order. This will be changed in the future to allow for more customization.
Example:
const headers = [{
title: 'Name',
sort: (a, b) => { // a and b are TableRow objects
return a.data.name > b.data.name;
}
}];
<td>
Editing (to be used with options.editable
)
header.editable
is a boolean that determines if the <td>
element is editable. If true, each <td>
element will have a contenteditable attribute.
const headers = [{
title: 'Name',
editable: true
}, {
title: 'Age',
editable: false
}];
const data = [{
Name: 'John',
Age: 34
}];
const options = {
editable: true
};
Will create
<table>
<thead>
<tr>
<th>Name</th>
</tr>
<tr>
<th>Age</th>
</tr>
</thead>
<tbody>
<tr>
<td contenteditable="true">John</td>
</tr>
<tr>
<td>34</td>
</tr>
</tbody>
</table>
Note: Even if a user edits the html, it will not change TableCell.content
Changing the <th>
Elements
Minimize
header.minimize
is a boolean that determines if the <th>
element is minimized. If true, the <th>
element will have a minimize
class.
const headers = [{
title: 'Name',
minimize: true
}, {
title: 'Age',
minimize: false
}];
Will create
<table>
<thead>
<tr>
<th>
<div style="display: flex; justify-content: space-between; align-items: center;">
<div>Name</div>
<!-- This icon can change with options.minimize.open -->
<i class="material-icons">chevron_left</i>
</div>
</th>
</tr>
<tr>
<th>Age</th>
</tr>
</thead>
<tbody>
<tr>
<td>John</td>
</tr>
<tr>
<td>John</td>
</tr>
</tbody>
</table>
Data
The header array is used to represent each row in the table. This is fully customizable because nothing from the Table
class reads this data, only your getData
does and other custom functions.
Each row's data will be in TableRow.data
.
Options
<tr>
Event Listeners
options.tr.listeners
is the same as header.th.listeners
and header.td.listeners
except it applies to all <tr>
elements.
Attributes
options.tr.attributes
is the same as header.th.attributes
except it applies to all <tr>
elements.
Classes
options.tr.classes
is the same as header.th.classes
except it applies to all <tr>
elements.
options.tr.classTests
is the same as header.td.classTests
except it applies to all <tr>
elements.
Jquery DataTable
options.datatable = true
or options.dataTable = true
will create a Jquery DataTable. This will override all other options except options.editable
.
Header Sorting
header.sortable
will make every <th>
element sortable. This will not override header.sort
. The sort function will be the same as the default header sort function ((a, b) => a.el.innerText.localCompare(b.el.innerText);
).
Even Columns
options.evenColumns = true
will set the width to be the same for every column using percentages.
Minimize
minimize.open
is the icon that will be used for the minimize button. The default is <i class="material-icons">chevron_left</i>
.
minimize.minimized
is a boolean that determines if the table is minimized. The default is false
.
Caption
options.caption
is a caption you can add onto the table. This will be added to the <table>
element.
Example:
const options = {
caption: 'This is a caption'
}
// or
const options = {
caption: {
content: 'This is a caption',
attributes: [], // Attributes onto the <caption> element
classes: [], // Classes onto the <caption> element
listeners: [] // Event listeners onto the <caption> element
}
}
Will create
<table>
<caption>This is a caption</caption>
<thead>
<!-- Your headers -->
</thead>
<tbody>
<!-- Your rows -->
</tbody>
</table>
Options soon to be implemented
- Reorder: Drag and drop to reorder rows and columns. Currently working on this, you can try it out by setting
options.reorder = true
to see what is happening. If you have tips please let me know. - Search: Search through the table using fuzzy search
- Pagination: Different pagination options for the table (ex. using dots, arrows, select, etc.)
- Insertion: Insert a row or column
- Deletion: Delete a row or column
Version 1.0.x
Note: This version is deprecated and will not be updated. Please use version 1.1.x. The basics are the same, but the options and headers parameters are different.
Headers
const headers = [{
title: 'Name',
getData: (row) => row.name,
listeners: [{ // applied only to <td> elements
event: 'click',
callback: (e) => {
console.log(e);
}
}],
classes: ['class1', 'class2'], // applied only to <th> elements
tdClassTests: [{ // applied only to <td> elements
test: (row) => row.name === 'John',
classes: ['class1', 'class2']
}],
tdClasses: ['class1', 'class2'], // applied only to <td> elements
tdAttributes: [{ // applied only to <td> elements
name: 'contenteditable',
value: 'true' // can be string
value: (row) => row.name === 'John' ? 'true' : 'false' // or function
}]
}]
Options
const options = {
evenColumns: true,
trAttributes: [{
name: 'contenteditable',
value: 'true' // can be string
value: (row) => row.name === 'John' ? 'true' : 'false' // or function
}],
appendTest: (row) => row.name === 'John',
trClasses: ['class1', 'class2'],
trClassTests: [{
test: (row) => row.name === 'John',
classes: ['class1', 'class2']
}],
trListeners: [{
event: 'click',
callback: (e) => {
console.log(e);
}
}]
}
Example
setTable(document.getElementById('my-table'), headers, data, options);