# JDataTable
A library used to initialize a basic data table. Includes the main components of a data table such as: sorting, per page, pagination, table. Supports additional configuration of search and filtering features.
## Table of contents
[Tech Stack](#tech-stack)
[Initialization](#initialization)
- [1. Create a table element in HTML](#1-create-a-table-element-in-html)
- [2. Initialize a TableData class in javascript](#2-initialize-a-tabledata-class-in-javascript)
- [3. Render table](#3-render-table)
[Configuration](#configuration)
- [1. Structure of config variable](#1-structure-of-config-variable)
- [2. Default configuration](#2-default-configuration)
- [3. Detailed configuration](#3-detailed-configuration)
[Filter](#filter)
[Search](#search)
[Edit cell content directly](#edit-cell-content-directly)
- [1. Functions to use](#1-functions-to-use)
- [2. Example](#2-example)
[Sample data structure](#sample-data-structure)
[Demo](#demo)
## Tech Stack
**Language:** HTML, JavaScript.
**Library:** jQuery, Remix Icon.
**Framework:** Bootstrap.
## Initialization
#### 1. Create a table element in HTML
Example:
```
```
#### 2. Initialize a `TableData` class in javascript
Example:
```
var tableData = new TableData("#data_table", config);
```
#### 3. Render table
Example:
```
tableData.render();
```
## Configuration
#### 1. Structure of _config_ variable
```js
var config = {
// Declare configuration for table headers
// 'render' function is used to customize the header
heads: [],
// Use data if config.ajax not exist
data: [],
// Used to customize rows according to column names
rowRender: (colName, colValue, row) => {},
// Ajax function to automatically get initial data and re-render times
// If this parameter is not present, the library will use the default parameter "data" passed directly
ajax: (params) => {
return new Promise((resolve, reject) => {});
},
// Information used to call the API for the row and cell update function
apiUpdate: {},
// Includes options for number of rows to display, pagination and row count details
footer: {},
// Customize sorting toggle or select which columns are allowed to be sorted
sort: {},
// Columns are sorted by default when initialized
order: {},
// Filter based on columns declared in config.heads
filter: {},
// Current page
page: 1,
// Number of lines on the page
per_page: 15,
};
```
#### 2. Default configuration
```js
config = {
order: null,
filter: null,
heads: [],
page: 1,
per_page: 15,
data: {},
rowRender: (colName, colValue, row) => {
return colValue;
},
footer: {
pagination: false,
detail: false,
},
sort: {
enable: false,
listColumn: [],
},
};
```
_Note: The user-declared configuration will be merged with the default configuration_
#### 3. Detailed configuration
| Properties | Type | Description |
| ---------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data | Array | The array contains data to render when the user wants to pass data directly to the table. By default, the library will receive this `data` variable as rendering data if the user does not declare the config.ajax attribute. |
| order | Object | Columns are sorted by default when initialized. The syntax includes 'order*by*' + column name to sort. Example: `{order_by_id: 'desc'}` |
| filter | Object | Filter based on columns declared in config.heads. Example: `{email: '@gmail.com', name: 'Jonh'}` |
| page | Number | Current page. Default is 1. |
| per_page | Number | Number of lines on the page. Default is 15. |
| heads | Array | An array of objects representing the columns of the table. Each object has two fields: `name` (the column name) and `value` (the display title of the column). It can have a `render` field to customize the display of the header. |
| | | |
Example:
```js
[
{
name: "id",
value: "ID",
},
{
name: "email",
value: "Email",
},
{
name: "code",
value: "Code",
render: (heads) => {
var html = `
${heads.value}
`;
return html;
},
},
];
```
| Properties | Type | Description |
| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rowRender | Function | A function used to customize the display of each cell in a row. Takes three parameters: `colName` (the column name), `colValue` (the value of the cell), and `row` (the data of the row). Returns an HTML string to display. |
Example:
```js
(colName, colValue, row) => {
switch (colName) {
case "id":
return `
${row.id}
`;
case "email":
return tableData.cellEdit(colName, colValue);
default:
return colValue;
}
};
```
| Properties | Type | Description |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ajax | Function | A function used to call an API and fetch initial data for the table. Takes one argument `params` (query parameters). Returns a promise with data resolved or rejects if there is an error. |
| | | |
Example:
```js
(params) => {
return new Promise((resolve, reject) => {
$.ajax({
url: "https://your.domain.net/api/v1/.../get",
type: "GET",
data: params, // Autofill based on 'order' and 'filter' attributes
headers: {
Authorization: "Bearer ...", // Include the token in the request header
},
success: function (response) {
resolve(response);
},
error: function (error) {
console.log(error);
reject(error);
},
});
});
};
```
| Properties | Type | Description |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apiUpdate | Object | An object containing information to call the API to update row and cell data. Includes fields: `url` (API endpoint), `type` (API method), and `headers` (request headers, including authentication token). |
| | | |
Example:
```js
{
url: "https://your.domain.net/api/v1/.../update",
type: "POST",
headers: {
Authorization: "Bearer ...", // Include the token in the request header
},
}
```
| Properties | Type | Description |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| footer | Object | An object containing configurations for the table footer. It has two fields: `pagination` (true/false to enable/disable pagination) and `detail` (true/false to show/hide detailed information about the record count). |
| | | |
Example:
```js
{
pagination: true,
detail: true
}
```
| Properties | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sort | Object | An object containing configurations for the table sorting feature. It has two fields: `enable` (true/false to enable/disable sorting feature) and `listColumn` (an array of column names that can be sorted). |
| | | |
Example:
```js
{
enable: true,
listColumn: ["id", "email", "code", "created_at"]
}
```
## Filter
### To use the filter function, users need to create a filter form and a function to retrieve values from the form.
Example:
HTML
```html
Filter
```
JS
```js
// Get values from form html and append to config -> re-render with new data
const getFormValues = () => {
const formData = {};
const form = document.getElementById("filterForm");
for (let i = 0; i < form.elements.length; i++) {
const element = form.elements[i];
if (!element.name || element.tagName === "BUTTON") {
continue;
}
formData[element.name] = element.value;
}
config.filter = formData;
tableData.updateConfig(config);
};
```
## Search
### Users need to design an input to enter the keyword to search, an event to listen for changes and filter results.
Example:
HTML
```html