Skip to content

api_general

Jump to bottom
Franky Van Liedekerke edited this page Oct 8, 2026 · 18 revisions

FTable API Reference - General Options

How to Set General Options

General options are set when creating a new FTable instance. Unlike the jQuery version, there's no need to set global prototype options - each instance is configured independently.

Setting Options for a FTable Instance

Set options in FTable initialization code. For example, to disable column resizing:

document.addEventListener('DOMContentLoaded', function() {
    const table = new FTable('#MyTableContainer', {
        columnResizable: false, // Disable column resizing
        title: 'My Data Table',
        // Other options...
        actions: {
            listAction: '/api/data'
        },
        fields: {
            // Field definitions...
        }
    });
});

Creating a Configuration Template

If you want to reuse the same configuration across multiple tables, you can create a template:

const defaultFTableConfig = {
    columnResizable: false,
    csvExport: true,
    printTable: true
};

// Usage
const table1 = new FTable('#Table1', {
    ...defaultFTableConfig,
    title: 'Users Table',
    actions: { listAction: '/api/users' },
    fields: { /* user fields */ }
});

const table2 = new FTable('#Table2', {
    ...defaultFTableConfig,
    title: 'Products Table',
    actions: { listAction: '/api/products' },
    fields: { /* product fields */ }
});

List of General Options

animationsEnabled

  • Type: Boolean
  • Default: true
  • Reserved: this option is currently not used by FTable - rows are added/updated/removed without animation, whatever the value. It only exists for backwards compatibility with the old jQuery version.

bulkActions

  • Type: Object
  • Default: None
  • Description: Wires up an existing "bulk actions" <select> + button that are rendered by the page (e.g. server-side, so translations stay where they belong) to the common flow: requires a selection and a chosen action, optionally confirms, disables the button while the request runs, posts the selected record keys, then reloads the table.

Sub-options:

Option Type Default Description
select CSS selector string or Element None The bulk-actions <select> element, already in the DOM.
button CSS selector string or Element None The "Apply"-button element, already in the DOM.
idField String 'ids' Form field name under which the comma-joined selected record keys get posted.
action URL string or function None String URL (posted via FTableHttpClient.post) or a function (data, ctx) => Promise.
confirmActions Array or function None Actions that need confirmation before running. See confirmActions below for all supported forms.
confirmTitle String or function messages.areYouSure Fallback title of the confirmation dialog.
confirmMessage String or function messages.deleteConfirmation Fallback message of the confirmation dialog.
extraData Object or function {} Extra fields merged into the posted data (e.g. a nonce or a static action name). If a function, it receives ctx and must return the extra fields object.
visibleWhen Object None Controls show/hide of page elements based on the selected action. Keys are CSS selectors, values are arrays of action values for which the element matching the selector should be visible. The element is hidden for every other action (and when no action is selected).
handlers Object None Per-action full override. Keys are action values, values are functions (ctx) => ... that bypass the AJAX flow entirely (e.g. to navigate away or trigger a download).

ctx passed to extraData/handlers is { doAction, ids, selectedRows, table }, where:

  • doAction: The currently selected action value.
  • ids: Array of selected record keys.
  • selectedRows: Array of selected row elements.
  • table: The FTable instance.

Example:

const table = new FTable('#MyTableContainer', {
    // ... other options
    bulkActions: {
        select: '#eme_admin_action',
        button: '#LocationsActionsButton',
        idField: 'location_id',
        action: '/api/bulk',
        confirmActions: ['trashLocations', 'deleteLocations'],
        confirmTitle: 'Delete?',
        confirmMessage: 'Are you sure you want to delete the selected records?',
        extraData: (ctx) => ({
            nonce: '1234567890',
            send_mail: document.getElementById('send_mail').value
        }),
        visibleWhen: {
            '#span_transferto':    ['trashLocations', 'deleteLocations'],
            '#span_sendmails':     ['trashLocations'],
            '#span_pdftemplate':   ['pdf']
        },
        handlers: {
            sendMails: ({ ids }) => {
                const form = document.createElement('form');
                form.method = 'POST';
                form.action = '/admin/sendmails';
                // ... submit the ids through a real form
                document.body.appendChild(form);
                form.submit();
            }
        }
    }
});

Flow:

  1. When the selected action changes (or on init), the selectors listed in visibleWhen are shown/hidden according to the selected action.
  2. On "Apply", runBulkAction() validates that rows are selected and an action is chosen, runs the confirmation for confirmActions, disables the button, and posts the ids (under idField) plus do_action (the value of the select-element defined) and optional extraData to action.
  3. After a successful request the table reloads, the button is restored, and the bulkActionComplete event is emitted. On failure the bulkActionError event is emitted. If a matching handlers entry exists for the selected action, the confirmation still runs, but the request/button-reload part of steps 2/3 is skipped and the handler runs instead (it receives the same ctx and is responsible for everything that happens next).

confirmActions

confirmActions determines which bulk actions require a confirmation dialog before they run. It accepts three forms. In every form the confirmation is only shown when runBulkAction() has at least one selected row and a chosen action.

1. Array of action names

The simplest form. Every listed action gets the fallback dialog (using confirmTitle/confirmMessage).

bulkActions: {
    // ... other options
    confirmActions: ['trashLocations', 'deleteLocations'],
    confirmTitle: 'Delete?',
    confirmMessage: 'Are you sure you want to delete the selected records?'
}

2. Array of names and/or objects (per-action title/message)

Mix plain strings with objects. Object entries can override the dialog title and/or message for that specific action. confirmTitle and confirmMessage can be strings or functions that receive ctx.

bulkActions: {
    // ... other options
    confirmActions: [
        {
            name: 'trashEvents',
            confirmTitle: 'Trash events?',
            confirmMessage: 'The events will be moved to the trash, not deleted.'
        },
        {
            name: 'deleteEvents',
            confirmMessage: (ctx) => `Are you sure you want to permanently delete ${ctx.ids.length} events?`
        },
        'deleteRecurrences'
    ]
}

3. Function

The function receives (doAction, ctx). It may return:

  • true → show the fallback dialog,
  • false/null/undefined → no confirmation,
  • an object { confirmTitle, confirmMessage } → show a dialog with those values (both may be functions receiving ctx).
bulkActions: {
    // ... other options
    confirmActions: (doAction, ctx) => {
        if (doAction === 'deleteEvents') {
            return {
                confirmTitle: 'Delete events?',
                confirmMessage: `Are you sure you want to permanently delete ${ctx.ids.length} events?`
            };
        }
        return true; // default dialog for everything else
    }
}

ctx is the same object passed to extraData/handlers: { doAction, ids, selectedRows, table }. This makes messages like "Are you sure you want to delete 10 rows?" easy to build dynamically from ctx.ids.length.

closeOnOverlayClick

  • Type: Boolean
  • Default: true
  • Description: when a popup is shown, it can be closed by clicking 'outside' it (on the overlay). Setting this option to false prevents that, meaning you then have to click the close-sign or the cancel-button if you want to close a popup.

columnResizable

  • Type: Boolean
  • Default: true
  • Description: Indicates whether FTable allows users to resize data columns by dragging.

columnSelectable

  • Type: Boolean
  • Default: true
  • Description: Indicates whether FTable allows users to show/hide data columns by right-clicking the table header.

columnSelectButton

  • Type: Boolean
  • Default: false
  • Description: If set to true, a small button will show next to the table title to allow users to show/hide data columns. The button is only created when a title is set and columnSelectable is not disabled.

csvExport

  • Type: Boolean
  • Default: false
  • Description: Indicates whether FTable should provide CSV export functionality. If so, a button will be created on the toolbar. The text of that button can be changed by the localization string csvExport.

defaultDateFormat

  • Type: String
  • Default: 'Y-m-d'
  • Description: Default format of a date or datetime-local field if a datepicker is detected (fdatepicker currently) is present. See the format of the accordingly detected datepicker. If no datepicker is detected, this value is ignored, but see 'defaultDateLocale'

defaultDateLocale

  • Type: String
  • Default: ''
  • Description: Default locale used to display values for a field of type 'date' in case no specific datepicker is used. Example: 'nl-BE' or 'en-US'. When the value is empty, FTable falls back to the raw stored value (no locale-specific formatting is applied).

defaultSorting

  • Type: String
  • Default: None
  • Description: Default sorting of the table. Example: 'Name ASC' or 'Name DESC'.

deleteConfirmation

  • Type: Function
  • Default: None
  • Description: Customizes the delete confirmation process. Without this option FTable always shows its confirmation dialog (using the deleteConfirmation/areYouSure localization strings). If a function is given, it runs before the dialog: it can change the confirmation message or cancel the delete entirely.

Function example:

const table = new FTable('#MyTableContainer', {
    deleteConfirmation: function(data) {
        data.deleteConfirmMessage = 'Are you sure to delete person ' + data.record.Name + '?';
        // You can also set data.cancel = true to prevent deletion
    },
    // ... other options
});

Function argument properties:

  • row: A DOM element for the deleting row.
  • record: Actual deleting record. For example, you can get Name property of record as data.record.Name.
  • cancel: You can set data.cancel to true to cancel delete process (default value is false).
  • cancelMessage: If you cancel the delete process, you can show a message to the user that explains the cancellation reason.
  • deleteConfirmMessage: The confirmation message shown in the dialog; you can overwrite it with a custom one.

The confirmation dialog itself is always shown afterwards (there is no way to skip it).

forcePost

  • Type: Boolean
  • Default: true
  • Description: if true (the default), read requests (listAction, field-option URLs and editRecordViaAjax) are made via POST, not GET. Set to false to have them done via GET. Note: create/update/delete/bulk requests are always POST.

gotoPageArea

  • Type: String
  • Default: 'combobox'
  • Description: Determines how to show the 'go to page' input. Possible values:
    • 'combobox': Show a combobox with all pages.
    • 'textbox': Show a text box.
    • 'none': Do not show the input.

listCache

  • Type: Integer
  • Default: 30000
  • Description: the amount of time (in ms) the table caches list queries (also applicable on search results)

listQueryParams

  • Type: Function
  • Default: None
  • Description: A function returning a list of parameters to be added to every load call. The parameters are merged in last, so they override parameters with the same name coming from the load call itself (paging, sorting, search, ...).

Example:

// Dynamic parameters (evaluated on each load)
const table = new FTable('#MyTableContainer', {
    listQueryParams: function() {
        return {
            'action': "my_action",
            'search_person': document.getElementById('search_person').value,
            'search_groups': document.getElementById('search_groups').value
        };
    },
    // ... other options
});

Note: only the function form is supported - a plain object is ignored.

loadingAnimationDelay

  • Type: Integer
  • Default: 1000
  • Description: Delay (in milliseconds) before showing the 'loading...' animation. Use 0 to show it immediately.

logLevel

  • Type: Integer

  • Default: 2 (FTableLogger.LOG_LEVELS.WARN)

  • Description: limit fTable console messages to the mentioned level. Use the numeric constants:

    • 0 (DEBUG) - all messages
    • 1 (INFO)
    • 2 (WARN) - default
    • 3 (ERROR)
    • 4 (NONE) - no messages at all

    Strings are not supported: FTableLogger.LOG_LEVELS holds the numeric values.

messages

  • Type: Object
  • Description: Used to localize fTable. See localization.

multiselect

  • Type: Boolean
  • Default: false
  • Description: Indicates whether fTable allows users to select multiple rows at once.

multiSorting

  • Type: Boolean
  • Default: false
  • Description: Indicates whether fTable allows users to sort by multiple columns. If this option is set to true, User can perform multiple sorting by holding CTRL key. If user selects multiple column for sorting, fTable sends column names seperated by comma as like 'Name DESC,BirthDay ASC'. See listAction for more information.

multiSortingCtrlKey

  • Type: Boolean
  • Default: true
  • Description: Only relevant when multiSorting is enabled. If true, a new sort is only added to the existing sorting when the user holds the CTRL/CMD key (a plain click then replaces the sorting). Set to false to always add to the current sorting.

openChildAsAccordion

  • Type: Boolean
  • Default: false
  • Description: If true, fTable automatically closes other open child tables when a new one is opened.

orderResetButton

  • Type: Boolean
  • Default: true
  • Description: Shows a button to reset the column order to the originally defined order. The button is only created when reorder is enabled.

paging

  • Type: Boolean
  • Default: false
  • Description: Indicates whether fTable uses paging. See listAction for more information.

pageList

  • Type: String
  • Default: 'normal'
  • Description: Determines the type of page list. Possible values:
    • 'minimal': Show only first, previous, next, and last links.
    • 'normal': Show page numbers in addition to 'minimal'.

pageSize

  • Type: Number
  • Default: 10
  • Description: Number of rows per page (must be one of pageSizes). The value used while paging is copied into the table state on the first load and can be changed at runtime with the page-size combobox or:
table.changePageSize(20);

Note: this is not a jQuery plugin - table is the FTable instance (new FTable(...) or document.querySelector('#MyTableContainer').ftableInstance).

pageSizes

  • Type: Array of Numbers
  • Default: [10, 25, 50, 100, 250, 500]
  • Description: Determines the options in the 'page size change combobox'.

pageSizeChangeArea

  • Type: Boolean
  • Default: true
  • Description: Determines whether the 'page size change combobox' is visible.

printTable

  • Type: Boolean
  • Default: false
  • Description: Indicates whether fTable should do provide print Table functionality. If so, a button will be created on the toolbar. The text of that button can be changed by the localisation string printTable.

reorder

  • Type: Boolean
  • Default: false
  • Description: Indicates whether fTable allows users to reorder columns via drag and drop.

searchDebounceMs

  • Type: Integer
  • Default: 300
  • Description: The debounce time for searhing when using the toolbarsearch option. This adds a delay before executing the search, thus avoiding many server side queries.

saveUserPreferences

  • Type: Boolean
  • Default: true
  • Description: Indicates whether fTable saves/loads user preferences (e.g., resized columns).
    Saving/restoring preferences are based on a hashed value that is generated using tableId, all column names and total column count. So, changing columns will change the hash and user preferences are reset.

saveUserPreferencesMethod

  • Type: String
  • Default: 'localStorage'
  • Description: Indicates how fTable saves/loads user preferences. Possible values (case-sensitive):
    • 'localStorage': Store user preferences in browser local storage (default and preferred)
    • 'cookie': Store user preferences in browser cookies (plain document.cookie, no extra library needed)

selecting

  • Type: Boolean
  • Default: false
  • Description: Indicates whether fTable allows users to select rows.

selectingCheckboxes

  • Type: Boolean
  • Default: false
  • Description: Indicates whether fTable shows a checkbox column for selecting rows. Only works when selecting is also enabled.

selectOnRowClick

  • Type: Boolean
  • Default: true
  • Description: Indicates whether users can select a row by clicking anywhere on it (only when selecting is enabled). Clicks on interactive elements (input, button, select, textarea, link) never select the row; add the class "norowselectonclick" to any other element to keep it from selecting the row. Set this option to false to disable row selection by clicking altogether.

sorting

  • Type: Boolean
  • Default: false
  • Description: Indicates whether fTable allows sorting.

sortingResetButton

  • Type: Boolean
  • Default: false
  • Description: Shows a button to clear the current sorting. Only created when sorting is enabled; it appears as soon as the table is sorted.

sortingInfoSelector

  • Type: String
  • Default: ''
  • Description: if not empty, it should be a CSS selector (a plain document.querySelector, e.g. '#currentSorting') where the current applied table sorting will be displayed. Only used when sorting is enabled. The localized messages sortingInfoPrefix and sortingInfoSuffix are used too.

tableId

  • Type: String
  • Default: None
  • Description: A unique identifier for the table, used for saving/restoring user preferences.

tableResetButton

  • Type: Boolean
  • Default: false
  • Description: If true, a button will be shown next to the paging info to reset the complete table to its default settings concering column visibility, column width and page sizing.

title

  • Type: String
  • Default: None
  • Description: A string shown at the top of the table.

toolbar

  • Type: Object
  • Default: 
    toolbar: {
    items: []
}
  • Description: Controls the fTable toolbar and its items. By default, no items are on the toolbar. fTable adds the 'Add new record' item if you define createAction, the CSV export item (see csvExport and/or the print item (see printTable). Using this option, you can add custom items

Example:

toolbar: {
    items: [{
        icon: '/images/excel.png',
        text: 'Export to Excel',
        click: function () {
            // Custom code...
        }
    }]
}

icon, text and click are optional. But you must define 'icon' and/or 'text', otherwise fTable can not show the toolbar item. In the click function, you can write your custom javascript codes.

You can also use some additional options for each toolbar item:

buttonClass: used to add custom css classes to the toolbar item.
buttonId: used to set a custom ID on the toolbar item. tooltip: used to set a tool tip for this item. fTable sets HTML 'title' attribute.

The items added via the toolbar option are added before any items added by fTable itself.

toolbarreset

  • Type: Boolean
  • Default: true
  • Description: Indicates whether the toolbar should show the seach reset button. If 'toolbarsearch' is not set, this setting is ognored

toolbarsearch

  • Type: Boolean
  • Default: false
  • Description: Indicates whether the toolbar should show a seach form per field. This can be overriden per field via the 'searchable' option

This passes the params 'q' and 'opt' to the listAction url. A simple example in php on how to use these:

    global $pdo;

    $q = $_POST['q'] ?? [];
    $opt = $_POST['opt'] ?? [];
    $where = '';
    $params = [];

    // Validate and process search parameters
    if (!empty($q) && is_array($q) && is_array($opt) && count($q) === count($opt)) {
        foreach ($opt as $i => $field) {
            $where_array[] = "`" . str_replace("`", "``", $field) . "` LIKE ?";
            $params[] = '%' . addcslashes($q[$i], '%\\') . '%';
        }
    }

    if (!empty($where_array)) {
            $where = ' WHERE ' . implode(' AND ', $where_array);
    }
    ....
    $stmt->execute([$params]);

A more complete example (with multi-select compatibility, so recommended to use this function):

function normalizeSearchToolbarFields($q, $opt) {
    $normalized_q = [];
    $normalized_opt = [];
    $grouped_data = [];

    foreach ($opt as $i => $field) {
        if (!isset($q[$i]) || $q[$i] === '') {
            continue;
        }

        if (substr($field, -2) === '[]') {
            $base_field = substr($field, 0, -2);
            if (!isset($grouped_data[$base_field])) {
                $grouped_data[$base_field] = [];
            }
            $grouped_data[$base_field][] = $q[$i];
        } else {
            $normalized_q[] = $q[$i];
            $normalized_opt[] = $field;
        }
    }

    foreach ($grouped_data as $field => $values) {
        $normalized_q[] = $values;
        $normalized_opt[] = $field . '[]';
    }

    return [$normalized_q, $normalized_opt];
}

list($q, $opt) = normalizeSearchToolbarFields($_REQUEST['q'] ?? [], $_REQUEST['opt'] ?? []);
$where = '';
$params = [];
$where_array = [];
foreach ($opt as $i => $field) {
    if ($field == 'class_id[]' ) {
        $or_arr = [];
        $class_ids = $q[$i];
        foreach ($class_ids as $class_id) {
            if ($class_id == -1) {
                $or_arr[] = "(u.class_id IS NULL OR u.class_id='')";
            } else {
                $or_arr[] = "u.class_id = ?";
                $params[] = $class_id;
            }
        }
        $where_array[]= "(" . implode(' OR ', $or_arr) . ")";
        continue;
    }
    $where_array[] = "`" . str_replace("`", "``", $field) . "` LIKE ?";
    $params[] = '%' . addcslashes($q[$i], '%\\') . '%';
}

fTable Documentation

Getting Started

API reference

Tips

Examples

Clone this wiki locally