SourTable Documentation

A lightweight, dependency-free JavaScript library for adding sorting functionality to HTML tables. It tries to preserve any event-listeners that exist on the table, as it does not uses .innerHTML method which leads to destruction of node, instead it just moves around the elements of table without destroying the listeners.

Installation

Include the library in your HTML file:

<script src="path/to/SourTable.js"></script>

Quick Start

Basic Initialization

Add sorting to a table with minimal setup:

HTML

<table id="my-table">
    <thead>
        <tr>
            <th>Name</th>
            <th>Age</th>
            <th>Salary</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>John Doe</td>
            <td>32</td>
            <td>$75,000</td>
        </tr>
        <!-- More rows -->
    </tbody>
</table>

JavaScript

const table = document.getElementById('my-table');
const sourTable = new SourTable(table);
sourTable.initiate();

API Reference

Constructor

new SourTable(tableElement, excludedColumns = [], keysForAttributes = {})

Creates a new SourTable instance.

Parameters

Parameter Type Description
tableElement HTMLTableElement The table element to make sortable (required)
excludedColumns Array<Number> Array of column indices to exclude from sorting (0-based, optional)
keysForAttributes Object Object mapping columns to attribute names. key = col_N where N = index of column, value=ATTRIBUTE_NAME (e.g., {col_2: 'data-value'}, optional)

initiate()

sourTable.initiate()

Enables sorting functionality on the table. Must be called after creating the SourTable instance.

Important: Throws an error if the table has already been initialized.

disengage()

sourTable.disengage()

Removes all sorting functionality and cleans up event listeners.

Best Practice: Always call disengage() before removing the table from the DOM or before initializing a new SourTable instance on the same table.

Example of disengage()

                        
function disengage() {
    if(sourTableInstance && sourTableInstance.isEngaged()) {
        sourTableInstance.disengage();
        sourTableInstance = null;
    }
}

sort()

sourTable.sort(colIndex, order, key = "")

Programmatically sort a column.

Parameters

Parameter Type Description
colIndex Number Column index to sort (0-based)
order String Sort direction ('asc' or 'desc')
key String Optional attribute key. If specified, the sort will be based on the value of the attribute. If not specified, the sort will be based on the text content of the cell. Usage: attr=ATTRIBUTE_NAME, Example: attr=data-salary

addCustomParseFunction()

sourTable.addCustomParseFunction(colIndex, parseFunction)

Adds a custom parsing function for a specific column.

If a column in your table includes data in a format that is not being correctly parsed by SourTable, eg. if data is in form of dates, percentages, fractions etc., you can use this method to add a custom parser for that column.

Example

// Custom parser for percentage values
sourTable.addCustomParseFunction(2, text => {
    return parseFloat(text.replace('%', ''));
});

Advanced Usage

Excluding Columns

Prevent specific columns from being sortable:

// Exclude first and third columns (0-based index)
const sourTable = new SourTable(table, [0, 2]);
sourTable.initiate();

Attribute-based Sorting

Sort by data attributes instead of displayed text:

<td data-salary="75000">$75,000</td>
// Sort column 2 by data-salary attribute
const sourTable = new SourTable(table, [], {
    col_2: 'data-salary'
});
sourTable.initiate();

Custom Parsers

Handle complex data formats with custom parsing:

// Custom date parser
sourTable.addCustomParseFunction(3, text => {
    return new Date(text).getTime();
});

// Currency parser
sourTable.addCustomParseFunction(2, text => {
    return parseFloat(text.replace(/[$,]/g, ''));
});

Examples

Complete Implementation

// Initialize with all features
const table = document.getElementById('data-table');
const sourTable = new SourTable(table, [0], { 
    col_2: 'data-value',
    col_3: 'data-date'
});

// Add custom parsers
sourTable.addCustomParseFunction(2, text => {
    return parseFloat(text.replace(/[$,]/g, ''));
});

sourTable.addCustomParseFunction(3, text => {
    return new Date(text).getTime();
});

// Enable sorting
sourTable.initiate();

// Later, when needed:
if (sourTable && sourTable.isEngaged()) {
    sourTable.disengage();
    sourTable = null;
}

Live Examples

Basic Demo Tests