Skip to content

api_methods

Jump to bottom
Franky Van Liedekerke edited this page Aug 1, 2025 · 22 revisions

FTable API Reference - Methods

Static methods:

Instance methods:

FTable.waitForFieldReady

Waits for a field in a form to be ready, mostly used for dependant fields when they get their data from the server See the events section for examples

Syntax:

FTable.waitForFieldReady('myfieldname', e.form);

FTableHttpClient.get

do a ftable-get

Syntax:

            const result = await FTableHttpClient.get('incidents.php', {
                ids: idsjoined,
                action: 'ajax_bulk_assets',
                do_action,
                change_location
            });

FTableHttpClient.post

do a ftable-post

Syntax:

            const result = await FTableHttpClient.post('incidents.php', {
                ids: idsjoined,
                action: 'ajax_bulk_assets',
                do_action,
                change_location
            });

addRecordToTable

This method is used to add a new record to the table programmatically.

Syntax:

table.addRecordToTable(record)

Parameters:

  • record: The record object to add (required).

Example:

const table = new FTable('#StudentTableContainer', { /*...*/ });

table.addRecordToTable({
        Name: 'My full Student name',
        EmailAddress: 'test123@example.com',
        Password: '123',
        Gender: 'M',
        CityId: 4,
        BirthDate: '2002-11-18',
        Education: '2',
        About: 'Adding test record',
        IsActive: true,
        RecordDate: '2011-11-12'
});

If you want to update the backend server too, use performCreate:

async function addRecordWithServer(data) {
    try {
        const result = await table.performCreate(data);
        if (result.Result === 'OK') {
            const record = result.Record || data;
            table.addRecord(record); // Add to UI
            table.emit('recordAdded', { record, serverResponse: result });
            return record;
        } else {
            table.showError(result.Message || 'Create failed');
        }
    } catch (error) {
        table.showError(table.options.messages.serverCommunicationError);
    }
}

// Usage example:
addRecordWithServer({
    name: 'John',
    email: 'john@example.com'
});

closeChildRow

Closes an open child row for a table row. Used internally by FTable to close child tables. See openChildRow.

Syntax:

table.closeChildRow(row)

Parameters:

  • row: The DOM row element.

closeChildTable

Closes an open child table for a table row.

Syntax:

table.closeChildTable(row, closed)

Parameters:

  • row: The DOM row element.
  • closed: Callback function called when the child table is closed.

changeColumnVisibility

Changes the visibility of a column.

Syntax:

table.changeColumnVisibility(columnName, visibility)

Parameters:

  • columnName: The name of the column.
  • visibility: Can be 'fixed', 'visible', or 'hidden'.

deleteRecord

Deletes an existing record from the table programmatically.

Syntax:

table.deleteRecord(options)

Parameters:

  • key: The key (ID) of the record to delete (required).
  • clientOnly (boolean, default: false): If true, the record is only deleted from the table, not from the server.
  • animationsEnabled (boolean, default: table's behavior): If false, no animation is shown.
  • url (string, default: deleteAction of the table): A custom URL for deleting the record.
  • success (function): Callback when the record is successfully deleted.
  • error (function): Callback if an error occurs.

Example:

const table = new FTable('#StudentTableContainer', { /*...*/ });

table.deleteRecord({
    key: 42
});

deleteRows

Deletes the specified rows from the server and table. This method can be combined with getSelectedRows method. Thus, you can get selected rows and pass to deleteRows method to delete them.

Syntax:

table.deleteRows(rowskeys)

Parameters:

  • rowkeys: An array of row keys to delete.

destroy

Completely removes the table from its container.

Syntax:

table.destroy()

editRecordByKey

Forces the edit dialog of a record to open.

Syntax:

table.editRecordByKey(keyFieldValue)

Example:

const table = new FTable('#MyTableContainer', { /*...*/ });

// To force the editDialog to open
const hash = window.location.hash;
const match = hash.match(/edit=(\d+)/);
if (match) {
    const idToEdit = match[1];
    table.editRecordByKey(idToEdit);
}

This example allows linking from other HTML pages to the page containing this JS with something like mypage.html#edit=123. This will then open the MyTableContainer FTable edit dialog for row with key value 123 (if the row is present, can be a problem if paging is on, but see editRecordViaAjax).

editRecordViaAjax

Forces the edit dialog of a record to open via AJAX.

Syntax:

table.editRecordViaAjax(keyFieldValue, myAjaxUrl)

Example:

const table = new FTable('#MyTableContainer', { /*...*/ });

// To force the editDialog to open
const hash = window.location.hash;
const match = hash.match(/edit=(\d+)/);
if (match) {
    const idToEdit = match[1];
    table.editRecordViaAjax(idToEdit, myAjaxUrl);
}

The myAjaxUrl call will get the name and value of the key-field passed along and should respond with something like:

//Return result to FTable
$fTableResult = [
    'Result' => "OK",
    'Record' => $row
];
echo json_encode($fTableResult);

Resulting JSON is then something like:

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

This example allows linking from other HTML pages to the page containing this JS with something like mypage.html#edit=123. This will then open the MyTableContainer FTable edit dialog for row with key value 123 (row content loaded via AJAX request).

getChildRow

Returns the child row for a table row. Used to add custom content to the child row.

Syntax:

table.getChildRow(row)

Parameters:

  • row: The DOM row element.

getRowByKey

Returns the DOM row element for a record via the key field's value of the record key.

Syntax:

table.getRowByKey(keyValue)

getSelectedRows

Returns all selected rows as an array of DOM elements.

Syntax:

const selectedRows = table.getSelectedRows()

Example:

const table = new FTable('#PersonTable', { /*...*/ });
const selectedRows = table.getSelectedRows();

selectedRows.forEach(function(row) {
    const record = row.ftableRecord; // or however the record data is stored
    const personId = record.PersonId;
    const name = record.Name;
});

getSortingInfo

Returns an array of field names with their current sorting (ASC/DESC).

Syntax:

const sortingInfo = table.getSortingInfo()

invertRowSelection

Inverts the selection state of the specified row in the table.

Syntax:

table.invertRowSelection(row)

Parameters:

  • row: A DOM row element to invert.

isChildRowOpen

Returns true if the child row is open for the specified row.

Syntax:

table.isChildRowOpen(row)

Parameters:

  • row: A DOM row element to check.

load

Loads records from the server.

Syntax:

table.load(postData, completeCallback)

Parameters:

  • postData: Optional data to send to the server.
  • completeCallback: Optional callback function called when loading is complete.

Example:

const table = new FTable('#PersonTable', { /*...*/ });

table.load({ CityId: 2, Name: 'Halil' });

If parameters are given via the load call and the same parameters exist in the listQueryParams option, the ones in the load call add/override params defined in the listQueryParams option.

openChildRow

Opens a child row for a table row. Used to show custom content.

Syntax:

table.openChildRow(row)

Parameters:

  • row: A DOM row element for which to open a child row.

openChildTable

Opens a child table for a table row.

Syntax:

table.openChildTable(row, tableOptions, opened)

Parameters:

  • row: The DOM row element.
  • tableOptions: Standard FTable options for the child table.
  • opened: Callback function called when the child table is opened.

Example:

const table = new FTable('#PersonTable', {
    // ... other options
    fields: {
        // ... other fields
        Phones: {
            title: '',
            width: '5%',
            sorting: false,
            edit: false,
            create: false,
            listClass: 'child-opener-image-column',
            display: function (personData) {
                // Create an image that will be used to open the child table
                const img = document.createElement('img');
                img.className = 'child-opener-image';
                img.src = '/Content/images/Misc/phone.png';
                img.title = 'Edit phone numbers';
                
                // Open child table when user clicks the image
                img.addEventListener('click', function () {
                    table.openChildTable(
                        img.closest('tr'),
                        {
                            title: personData.record.Name + ' - Phone numbers',
                            actions: {
                                listAction: '/PagingPerson/PhoneList?PersonId=' + personData.record.PersonId,
                                deleteAction: '/PagingPerson/DeletePhone',
                                updateAction: '/PagingPerson/UpdatePhone',
                                cloneAction: '/PagingPerson/ClonePhone',
                                createAction: '/PagingPerson/CreatePhone?PersonId=' + personData.record.PersonId
                            },
                            fields: {
                                PhoneId: {
                                    key: true,
                                    create: false,
                                    edit: false,
                                    list: false
                                },
                                PhoneType: {
                                    title: 'Phone type',
                                    width: '30%',
                                    options: { '1': 'Home phone', '2': 'Office phone', '3': 'Cell phone' }
                                },
                                Number: {
                                    title: 'Phone Number',
                                    width: '30%'
                                },
                                RecordDate: {
                                    title: 'Record date',
                                    width: '20%',
                                    type: 'date',
                                    displayFormat: 'dd.mm.yy',
                                    create: false,
                                    edit: false
                                }
                            }
                        }, 
                        function (data) { // opened handler
                            data.childTable.load();
                        }
                    );
                });
                
                // Return image to show on the person row
                return img;
            }
        }
    }
});

recalcColumnWidths

Recalculate the column widths when a table becomes visible. Can be useful in hidden tabs.

Syntax:

table.recalcColumnWidths()

recalcColumnWidthsOnce

Recalculate the column widths once when a table becomes visible. Can be useful in hidden tabs but is only done the first time the table becomes visible.

Syntax:

table.recalcColumnWidthsOnce()

Example usage (as used in Events Made Easy WordPress plugin):

if (target == "tab-mailings") {
    // Do this only when the tab is active, to avoid doing mail lookups if not needed
    // Delay the trigger to ensure the tab content is fully rendered
    setTimeout(function() {
        const table = new FTable('#MailingsTableContainer', { /*...*/ });
        table.recalcColumnWidthsOnce();
        document.getElementById('MailingsLoadRecordsButton').click(); // custom button that triggers load with extra filters set
    }, 100); // Adjust the delay as necessary
}

reload

Reloads records from the server using the last postData.

Syntax:

table.reload(completeCallback)

Parameters:

  • completeCallback: Optional callback function called when reloading is complete.

selectRows

Selects the specified rows.

Syntax:

table.selectRows(rows)

Parameters:

  • rows: An array or NodeList of row elements to select.

showAddRecordForm

Programmatically opens a "create new record" form dialog.

Syntax:

table.showAddRecordForm()

updateRecordInTable

Updates an existing record on the table programmatically.

Syntax:

table.updateRecordInTable(record)

Parameters:

  • record: The record object to update (required).

Example:

const table = new FTable('#StudentTableContainer', { /*...*/ });

table.updateRecordInTable({
        StudentId: 42,
        Name: 'My full Student name',
        EmailAddress: 'test123@example.com',
        Password: '123456',
        Gender: 'M',
        CityId: 4,
        BirthDate: '2001-11-18',
        Education: '3',
        About: 'Updated this record',
        IsActive: true,
        RecordDate: '2012-01-05'
});

If you want to update the backend server too, use performUpdate:

async function updateRecordWithServer(key, newData) {
    try {
        const result = await table.performUpdate(newData);
        if (result.Result === 'OK') {
            const row = table.getRowByKey(key);
            if (row) {
                table.updateRowData(row, result.Record || newData);
                table.emit('recordUpdated', { record: result.Record || newData, row, serverResponse: result });
            }
        } else {
            table.showError(result.Message || 'Update failed');
        }
    } catch (error) {
        table.showError(table.options.messages.serverCommunicationError);
    }
}

// Usage example:
updateRecordWithServer(5, {
    id: 5,
    name: 'Jane',
    email: 'jane@example.com'
});

fTable Documentation

Getting Started

API reference

Tips

Examples

Clone this wiki locally