Getting Started

FTable - A Modern Vanilla JavaScript CRUD Table Library

Getting Started

Introduction

Here, I will examine a simple table implementation with FTable. Assume that you have a database table as shown below.

FTable does not care about any server-side technology - you can use it with any backend.

The demo SQL for import into MySQL can be found here

Dependencies

FTable is built with vanilla JavaScript and has no dependencies! No jQuery, no external libraries needed.

There are two optional libraries that FTable integrates with when they are loaded - without them FTable falls back to plain HTML controls:

• SnapSelect (@liedekef/snapselect): transforms the <select multiple> elements that FTable creates for multi-value fields (create/edit form and search bar) into a modern searchable dropdown with tags, select-all, clear button, ... Load its CSS and JS before creating the FTable instance. See SnapSelect (optional dependency).
• fdatepicker: gives date fields a real datepicker; without it FTable uses the native HTML5 date input.

<!-- Optional: SnapSelect for multi-selects -->
<link rel="stylesheet" href="/path/to/snapselect/dist/css/snapselect.min.css">
<script src="/path/to/snapselect/dist/js/snapselect.min.js"></script>

Installation

Via NPM

npm install @liedekef/ftable

Via CDN or Download

You can download FTable from the Releases section on GitHub, or include it directly:

<!-- Include FTable theme CSS -->
<link href="https://cdn.jsdelivr.net/npm/@liedekef/ftable/themes/metro/blue/ftable.min.css" rel="stylesheet">

<!-- Include FTable JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/@liedekef/ftable/ftable.js"></script>

After downloading, you will have a folder structure like:

Demo DB and PHP Files

The demo SQL for import into MySQL can be found here
The demo PHP files (update paths as needed):
FTablePagedSortedExample html
FTableSimpleExample html
PersonActions php
PersonActionsPagedSorted php

Creating Header

As ES6 Module

<script type="module">
import '@liedekef/ftable/themes/metro/blue/ftable.min.css';
import FTable from '@liedekef/ftable';
</script>

As Standalone Script

Add these lines to the HEAD section of your HTML document:

<!-- Include FTable theme CSS -->
<link href="/ftable/themes/metro/blue/ftable.min.css" rel="stylesheet" type="text/css" />

<!-- Include FTable script file -->
<script src="/ftable/ftable.min.js" type="text/javascript"></script>

You can select any theme and color schema in the themes folder.

Note: No jQuery required! FTable is pure vanilla JavaScript.

Creating a Container

FTable needs only a container element for your table.

<div id="PersonTableContainer"></div>

Container element can be a simple div element as shown above.

Creating a FTable Instance

Add this JavaScript code to your page:

<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', function() {
        const table = new FTable('#PersonTableContainer', {
            title: 'Table of people',
            actions: {
                listAction: '/GettingStarted/PersonList',
                createAction: '/GettingStarted/CreatePerson',
                updateAction: '/GettingStarted/UpdatePerson',
                cloneAction: '/GettingStarted/ClonePerson',
                deleteAction: '/GettingStarted/DeletePerson'
            },
            fields: {
                PersonId: {
                    key: true,
                    list: false
                },
                Name: {
                    title: 'Author Name',
                    width: '40%'
                },
                Age: {
                    title: 'Age',
                    width: '20%'
                },
                RecordDate: {
                    title: 'Record date',
                    width: '30%',
                    type: 'date',
                    create: false,
                    edit: false
                }
            }
        });
    });
</script>

All HTML and JavaScript codes are ready! We set the title of the table, action URLs to perform AJAX operations on the server, and the structure of our Person record fields. If you run the page now, you will see the table without data:

If you click '+ Add new record' link, a dialog is automatically created:

We must create server-side codes to be able to run the page.

Creating the List Action

The listAction option of FTable is used to get data to create a table of records. It's a regular URL like '/GettingStarted/PersonList'. If you are working with PHP, it might be '/GettingStarted/PersonList.php'. FTable performs an AJAX POST request to this URL to get records when you call the load method (with the default forcePost: true option; set forcePost to false to use GET instead).

table.load();

The load method can be called after the table is initialized.

All server actions used by FTable must return a JSON object. Here is a sample return value for this example:

{
 "Result":"OK",
 "Records":[
  {"PersonId":1,"Name":"Benjamin Button","Age":17,"RecordDate":"\/Date(1320259705710)\/"},
  {"PersonId":2,"Name":"Douglas Adams","Age":42,"RecordDate":"\/Date(1320259705710)\/"},
  {"PersonId":3,"Name":"Isaac Asimov","Age":26,"RecordDate":"\/Date(1320259705710)\/"},
  {"PersonId":4,"Name":"Thomas More","Age":65,"RecordDate":"\/Date(1320259705710)\/"}
 ]
}

Don't worry about creating a JSON object. All common server-side technologies have the ability to create these objects easily (see samples below).

The Result property can be "OK" or "ERROR". If it is "OK", the Records property must be an array of records. If it is "ERROR", a Message property can explain the reason; for the listAction FTable shows a generic "error communicating with the server" message to the user and logs the server Message in the console.

Here are sample server-side codes for listAction in PHP:

//Get records from database
$result = mysqli_query($connection, "SELECT * FROM people;");

//Add all records to an array
$rows = [];
while($row = mysqli_fetch_array($result))
{
    $rows[] = $row;
}

//Return result to FTable
$fTableResult = [
    'Result' => "OK",
    'Records' => $rows
];
header('Content-Type: application/json');
echo json_encode($fTableResult);

So, now we can run the page and see the result:

Creating a New Record

When we click the '+ Add new record' link below the table, a create record form is automatically generated by FTable:

When we try to add a person, we get an error since we haven't implemented createAction yet! The createAction option of FTable is used to submit (POST) a 'create record form' to the server. When you press the Save button, a POST data is sent to the server as shown below:

Name=Dan+Brown&Age=55

On the server side, you can save the new person to the database. The createAction should return the newly created record (as a JSON object)! A sample return value for createAction can be:

{
 "Result":"OK",
 "Record":{"PersonId":5,"Name":"Dan Brown","Age":55,"RecordDate":"\/Date(1320262185197)\/"}
}

Same as all FTable actions, the returning object must contain a Result property that's value can be "OK" or "ERROR". If it's "OK", the Record property is the created record.

Here are sample server-side codes for createAction in PHP:

//Insert record into database
$result = mysqli_query($connection, "INSERT INTO people(Name, Age, RecordDate) VALUES('" . $_POST["Name"] . "', " . $_POST["Age"] . ", NOW());");

//Get last inserted record (to return to FTable)
$result = mysqli_query($connection, "SELECT * FROM people WHERE PersonId = LAST_INSERT_ID();");
$row = mysqli_fetch_array($result);

//Return result to FTable
$fTableResult = [
    'Result' => "OK",
    'Record' => $row
];
header('Content-Type: application/json');
echo json_encode($fTableResult);

When the server successfully saves the new record, FTable reloads the table, so the new record shows up.

Editing/Updating a Record

When we click the edit icon for a record, an edit record form is automatically generated by FTable:

When we change the age of Douglas Adams and save the form, a POST operation is made to the updateAction URL with the following values:

PersonId=2&Name=Douglas+Adams&Age=43

On the server side, you can update fields in the database table for PersonId=2. The updateAction must return a JSON object like this:

{"Result":"OK"}

If Result is "ERROR", a Message property can explain the error reason. If Result is "OK", FTable updates the cells of that row in the table on the page.

Here are sample server-side codes for updateAction in PHP:

//Update record in database
$result = mysqli_query($connection, "UPDATE people SET Name = '" . $_POST["Name"] . "', Age = " . $_POST["Age"] . " WHERE PersonId = " . $_POST["PersonId"] . ";");

//Return result to FTable
$fTableResult = [
    'Result' => "OK"
];
header('Content-Type: application/json');
echo json_encode($fTableResult);

Clone a Record

When the cloneAction option is defined, a clone icon is added to the table. Cloning is implemented as a create: when we click the clone icon for a record, FTable copies that record, clears the key field and opens the same create record form (with the copied values filled in):

When we change the age of Douglas Adams and save the form, a POST operation is made to the createAction URL (not to cloneAction) with the following values:

Name=Douglas+Adams&Age=43

On the server side, you can create fields in the database table with a new PersonId. createAction must return a JSON object like this:

{"Result":"OK","Record":{"PersonId":6,"Name":"Douglas Adams","Age":43,"RecordDate":"\/Date(1320262185197)\/"}}

If Result is "ERROR", a Message property can explain the error reason. If Result is "OK", FTable reloads the table, so the cloned record shows up.

The cloneAction URL itself is never called: the option only decides whether the clone button is shown (it must be defined, a URL string or any truthy value works).

Here are sample server-side codes for handling that clone request (this is your createAction handler) in PHP:

//Insert record into database
$result = mysqli_query($connection, "INSERT INTO people(Name, Age, RecordDate) VALUES('" . $_POST["Name"] . "', " . $_POST["Age"] . ", NOW());");

//Get last inserted record (to return to FTable)
$result = mysqli_query($connection, "SELECT * FROM people WHERE PersonId = LAST_INSERT_ID();");
$row = mysqli_fetch_array($result);

//Return result to FTable
$fTableResult = [
    'Result' => "OK",
    'Record' => $row
];
header('Content-Type: application/json');
echo json_encode($fTableResult);

Deleting a Record

When we click the delete icon for a record, a confirmation dialog is shown to the user by FTable (this dialog is always shown; the deleteConfirmation option lets you customize its message):

When we click the delete button, a POST operation is made to the deleteAction URL with the following values:

PersonId=3

You can delete the record 3 on the server. The deleteAction also returns a JSON object like this:

{"Result":"OK"}

If Result is "ERROR", a Message property can explain the error reason. If Result is "OK", FTable removes the related row from the table on the page (and reloads the table when paging is enabled).

Here are sample server-side codes for deleteAction in PHP:

//Delete from database
$result = mysqli_query($connection, "DELETE FROM people WHERE PersonId = " . $_POST["PersonId"] . ";");

//Return result to FTable
$fTableResult = [
    'Result' => "OK"
];
header('Content-Type: application/json');
echo json_encode($fTableResult);

The Result

Here is the complete FTable instance. Try it yourself:

<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', function() {
        const table = new FTable('#PersonTableContainer', {
            title: 'Table of people',
            actions: {
                listAction: '/GettingStarted/PersonList',
                createAction: '/GettingStarted/CreatePerson',
                updateAction: '/GettingStarted/UpdatePerson',
                cloneAction: '/GettingStarted/ClonePerson',
                deleteAction: '/GettingStarted/DeletePerson'
            },
            fields: {
                PersonId: {
                    key: true,
                    list: false
                },
                Name: {
                    title: 'Author Name',
                    width: '40%'
                },
                Age: {
                    title: 'Age',
                    width: '20%'
                },
                RecordDate: {
                    title: 'Record date',
                    width: '30%',
                    type: 'date',
                    create: false,
                    edit: false
                }
            }
        });

        // Load the data
        table.load();
    });
</script>