api_actions

FTable API Reference - Actions

• listAction
• createAction
• updateAction
• cloneAction
• deleteAction

---

Actions

An action defines how to communicate from the client to the server. There are five types of actions:

1. listAction: Defines how to get the list of records.
2. createAction: Defines how to submit a "create new record" form (also used by the clone button).
3. updateAction: Defines how to submit an "edit record" form.
4. cloneAction: Only decides whether the clone button is shown - the clone itself goes through createAction.
5. deleteAction: Defines how to delete a record.

Actions must be defined in the actions object of FTable options:

actions: {
    // Action definitions go here
}

An action value can be a URL string or a function. See each action for details.

---

listAction

• Type: URL string or function
• Default: None

Setting a URL string as listAction

If listAction is defined as a URL string, FTable makes an AJAX request to this URL to fetch the list of records: a POST with the default forcePost: true option, a GET when you set forcePost: false. The URL must return a JSON object:

{
    "Result": "OK",
    "Records": [
        { "PersonId": 1, "Name": "Benjamin Button", "Age": 17, "RecordDate": "/Date(1320259705710)/" },
        { "PersonId": 2, "Name": "Douglas Adams", "Age": 42, "RecordDate": "/Date(1320259705710)/" }
    ]
}

• Result: Can be "OK" or "ERROR". If "OK", the Records property must contain an array of records.
• Records: An array of records to display in the table.
• TotalRecordCount: Total number of records (not just the current page). Falls back to Records.length when omitted.
• Message: If Result is "ERROR", this property explains the error (it is logged to the console; the user sees FTable's generic "error communicating with the server" message).

Date Formats

• /Date(milliseconds)/: Example: /Date(1320259705710)/.
• YYYY-MM-DD HH:MM:SS: Example: 2012-01-03 21:40:42.
• YYYY-MM-DD: Example: 2012-01-03.

Paging

If paging is enabled, FTable sends the following parameters:

• jtStartIndex: Start index of records for the current page.
• jtPageSize: Maximum number of records to fetch.

With the default forcePost: true these are sent as multipart/form-data fields in the POST body (not as a query string); with forcePost: false they become query string parameters.

The server must return:

• TotalRecordCount: Total number of records (not just the current page).

Sorting

If sorting is enabled, FTable sends:

• jtSorting: A string representing the sorting request (e.g., Name ASC, BirthDate DESC).

Searching

If toolbarsearch is enabled, FTable also sends q[] (the search values) and opt[] (the field names) - see the toolbarsearch example.

Setting a Function as listAction

You can define listAction as a function. It is called with one argument: the complete parameter object (everything you passed to load(), plus jtStartIndex/jtPageSize/jtSorting, the search parameters and the listQueryParams result). The function can return:

• The data itself.
• A promise to return the data.

Example using modern fetch API:

listAction: function (params) {
    return fetch('/Demo/StudentList', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(params)
    })
    .then(response => response.json())
    .catch(error => {
        console.error('Error:', error);
        throw error;
    });
}

Example using async/await:

listAction: async function (params) {
    try {
        const response = await fetch('/Demo/StudentList', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(params)
        });
        return await response.json();
    } catch (error) {
        console.error('Error:', error);
        throw error;
    }
}

• params: The merged parameter object described above (paging, sorting, search, your load() data and listQueryParams). When the value is an array it is sent as name[].

---

createAction

• Type: URL string or function
• Default: None

Setting a URL string as createAction

If createAction is defined as a URL, FTable makes an AJAX POST request to this URL to save a new record. The URL must return a JSON object:

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

• Result: Can be "OK" or "ERROR".
• Record: Optional. The server data used to add the new row to the table; when absent FTable adds the submitted form values. Returning Message together with Result: "OK" shows an info-dialog with that message after the record has been inserted.
• Message: Error message if Result is "ERROR" (required in the ERROR case, otherwise a "communication error" will be shown).

Setting a Function as createAction

You can define createAction as a function. The function can return:

• The data itself.
• A promise to return the data.

Example using modern fetch API:

createAction: function (postData) {
    return fetch('/Demo/CreatePerson', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(postData)
    })
    .then(response => response.json())
    .catch(error => {
        console.error('Error:', error);
        throw error;
    });
}

Example using async/await:

createAction: async function (postData) {
    try {
        const response = await fetch('/Demo/CreatePerson', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(postData)
        });
        return await response.json();
    } catch (error) {
        console.error('Error:', error);
        throw error;
    }
}

---

updateAction

• Type: URL string or function
• Default: None

Setting a URL string as updateAction

If updateAction is defined as a URL, FTable makes an AJAX POST request to this URL to update a record. The URL must return a JSON object:

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

• Result: Can be "OK" or "ERROR".
• Record: Optional. Overwrites fields in the updated row after the update.
• Message: Error message if Result is "ERROR" (required in the ERROR case, otherwise a "communication error" will be shown). Returning Message together with Result: "OK" shows an info-dialog with that message after the record has been updated.

Setting a Function as updateAction

You can define updateAction as a function. The function can return:

• The data itself.
• A promise to return the data.

Example using modern fetch API:

updateAction: function (postData) {
    return fetch('/Demo/UpdatePerson', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(postData)
    })
    .then(response => response.json())
    .catch(error => {
        console.error('Error:', error);
        throw error;
    });
}

Example using async/await:

updateAction: async function (postData) {
    try {
        const response = await fetch('/Demo/UpdatePerson', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(postData)
        });
        return await response.json();
    } catch (error) {
        console.error('Error:', error);
        throw error;
    }
}

---

cloneAction

• Type: URL string or function
• Default: None

cloneAction is never requested by FTable. It is only checked for truthiness: when it is set, the clone button is shown in the toolbar / row menu. Clicking that button opens the add-record form prefilled with the record's data, and saving that form posts to createAction.

So you only have to define cloneAction as a flag (cloneAction: '/Demo/ClonePerson' or cloneAction: function () {}), and let createAction handle the actual insert. In createAction you can distinguish the clone by extra request data if you want.

Example

actions: {
    listAction: '/Demo/PersonList',
    createAction: '/Demo/CreatePerson',   // also receives the clone requests
    updateAction: '/Demo/UpdatePerson',
    deleteAction: '/Demo/DeletePerson',
    cloneAction: '/Demo/ClonePerson'      // only enables the clone button
}

---

deleteAction

• Type: URL string or function
• Default: None

Setting a URL string as deleteAction

If deleteAction is defined as a URL, FTable makes an AJAX POST request to this URL to delete a record. The posted data is only the key of the record: { [keyField]: value } (e.g. PersonId=3). The URL must return a JSON object:

{
    "Result": "OK"
}

• Result: Can be "OK" or "ERROR".
• Message: Error message if Result is "ERROR" (required in the ERROR case, otherwise a "communication error" will be shown). Returning Message together with Result: "OK" shows an info-dialog with that message after the record has been deleted. When Result is "OK" the row is removed from the table immediately (and the table reloads when paging is enabled).

Setting a Function as deleteAction

You can define deleteAction as a function. The function can return:

• The data itself.
• A promise to return the data.

Example using modern fetch API:

deleteAction: function (postData) {
    return fetch('/Demo/DeletePerson', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(postData)
    })
    .then(response => response.json())
    .catch(error => {
        console.error('Error:', error);
        throw error;
    });
}

Example using async/await:

deleteAction: async function (postData) {
    try {
        const response = await fetch('/Demo/DeletePerson', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(postData)
        });
        return await response.json();
    } catch (error) {
        console.error('Error:', error);
        throw error;
    }
}