Skip to content

api_fieldoptions

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

FTable API Reference - Field Options

A field definition defines the structure and behavior of a field of the record. It's generally formatted as:

FieldName: {
    // Field options
}

action

  • Type: string
  • Default: None
  • Valid options: select,update,clone,delete
  • Description: by default - when specifying updateAction, cloneAction, deleteAction or the row-select checkboxes - FTable creates custom columns to accomodate room for these: checkboxes at the beginning of a row, update/clone/deleteAction become columns at the end. Specifying the action will cause the column to appear where you want it, allowing free positioning of the actions. See also Actions

columnResizable

  • Type: Boolean
  • Default: true
  • Description: Indicates whether this column can be resized by the user. The table's columnResizable option must be set to true (default) to use this option.

create

  • Type: Boolean
  • Default: true
  • Description: Indicates whether this field is shown in the "create record" form. Defaults to true for normal fields and false for action columns. For the key field FTable forces create to true and the field type to 'hidden', unless you explicitly set create: true yourself (then the key is shown as a regular input).

dateFormat

  • Type: String
  • Default: none
  • Description: per-field override of the generic option 'defaultDateFormat'. Format of a date field if a datepicker is detected (fdatepicker currently). See the format of the accordingly detected datepicker. If no datepicker is detected, this value is ignored, but see 'dateLocale'

dateLocale

  • Type: String
  • Default: None,
  • Description: per-field override of the generic option 'defaultDateLocale'. Defines the locale used to display values for a field of type 'date' in case no specific datepicker is used. Example: 'nl-BE' or 'en-US'.

defaultValue

  • Type: String
  • Default: None
  • Description: Sets a default value for the field. It must be a valid value (e.g., for an option list, it must be one of the options).

dependsOn

  • Type: String (comma-separated field names)
  • Default: None
  • Description: Used to create cascaded dropdowns. If a combobox field depends on another combobox, FTable can automatically create cascaded dropdowns. The dependsOn can also be a text field (or anything that supports getting the value).

Example:

CountryId: {
    title: 'Country',
    options: 'Demo/GetCountryOptions',
    list: false
},
CityId: {
    title: 'City',
    dependsOn: 'CountryId', // Cities depend on countries.
    options: function (data) {
        if (data.source == 'table') {
            return 'Demo/GetCityOptions?countryId=0'; // Return URL for all cities.
        }
        return 'Demo/GetCityOptions?countryId=' + data.dependedValues.CountryId;
    }
}

A field can depend on multiple fields. Use a comma-separated string:

  • dependsOn: 'ContinentalId,CountryId'

(An array is not supported: FTable splits the value on commas, so dependsOn: ['ContinentalId', 'CountryId'] is ignored.)

The dependsOn option works in tandem with dependedValues, as shown in the example above.

display

  • Type: Function
  • Default: None
  • Description: Allows you to define a fully custom column for the table. The return value of this function is shown in the table.

Example:

TestColumn: {
    title: 'Test',
    display: function (data) {
        return '<b>test</b>';
    }
}
  • data.record: Contains the record of the row.
  • data.value: Contains the value of this column of the row, just a handy shortcut for data.record.colname
  • data.displayValue: Contains the display value of this column of the row if no function was defined, very handy if you just want to change colors or so

Use this for calculated columns, child tables, etc.

edit

  • Type: Boolean
  • Default: true
  • Description: Indicates whether this field is shown in the "edit record" form. Defaults to true for normal fields and false for action columns. For the key field FTable forces edit to true and the field type to 'hidden', unless you explicitly set edit: true yourself (then the key is shown as a regular input).

explain

  • Type: String
  • Default: None
  • Description: Allows you to create an extra explanation for an input field (in the create/edit forms) just below the input field.

input

  • Type: Function
  • Default: None
  • Description: Allows you to define a fully custom input element for create/edit forms.

Example:

Name: {
    title: 'Name',
    input: function (data) {
        if (data.record) {
            return '<input type="text" name="Name" value="' + data.record.Name + '" />';
        } else {
            return '<input type="text" name="Name" value="Enter your name" />';
        }
    }
}
  • data.formType: Can be 'create' or 'edit'.
  • data.inputField: The original input field (vanilla DOM element).
  • data.record: The editing record (for 'edit' forms).
  • data.field: The field definition itself.

The data.inputField can come in handy if you just want to prepend something to the input field but don't want to code the field itself again. As an example, here is a field called "files" that in the list (display) shows a list of uploaded files and in the create/edit shows this list before the files-input field:

files: {
    title: 'Files',
    type: 'file',
    inputAttributes: "multiple",
    searchable: false,
    sorting: false,
    display: function (data) {
        if (data.record && data.record['files']) {
            return data.record['files'];
        }
    },
    input: function (data) {
        if (data.record && data.record['files']) {
            let val = data.record['files'];
            val += data.inputField.outerHTML;
            return val;
        } else {
            return data.inputField;
        }
    }
}

Another example that adds the input field original value above the input itself:

description: {
    title: 'Description',
    type: 'textarea',
    list: false,
    input: function (data) {
        const container = document.createElement('div');
        const span = document.createElement('span');
        span.innerHTML = data.record['description'];
        container.appendChild(span);
        container.appendChild(data.inputField);
        return container.outerHTML;
    }
}

inputAttributes

  • Type: String
  • Default: None
  • Description: Adds html attributes to the input element for this field in create/edit forms. FTable does form validation (as a regular form) before submit, so if you set this to e.g. "required", the required attribute will be set to the input field.
MyTextField: {
    title: 'My phone is required',
    inputAttributes: "size='60' required"
}

inputClass

  • Type: String
  • Default: None
  • Description: Adds one or more CSS classes to the input element for this field in create/edit forms.

inputTitle

  • Type: String
  • Default: None
  • Description: Sets a different title for the field in create/edit forms. If not set, the title option is used.

key

  • Type: Boolean

  • Default: false

  • Description: Indicates whether this field is the primary key of the record. Every record must have one key field.

  • In the edit/create modals, the key field is always included: by default FTable forces the field type to 'hidden' (so a hidden input carrying the key is posted under the key field name). If you set edit (or create) explicitly to true, the key is shown as a regular editable input instead.

list

  • Type: Boolean
  • Default: true
  • Description: Indicates whether this field is shown in the table.

listClass

  • Type: String
  • Default: None
  • Description: Adds a CSS class to the table cell (<th> and <td>) for this field. Applied to columns in both header row and regular rows.

listClassEntry

  • Type: String
  • Default: None
  • Description: Adds a CSS class to the table body cell (<td>) for this field.

listClassHeader

  • Type: String
  • Default: None
  • Description: Adds a CSS class to the table header cell (<th>) for this field.

listEscapeHTML

  • Type: Boolean
  • Default: False
  • Description: if set to true, the value of the field will be escaped before showing it in the table. Might be useful for e.g. text and textarea fields.

noCache

  • Type: Boolean, Function or Object
  • Default: false
  • Description: Skips the option-list cache for this field. true always fetches fresh options, a function is called with { context, ...params } (return true to bypass the cache), an object can set it per context: { table: true, create: false, edit: true, search: true }. See also the general option listCache.

options

  • Type: Object, Array, URL, or Function

  • Default: None

  • Description: Defines the source for an option list (e.g., radio buttons, dropdown).

  • If this is defined but not the field type, the field type is assumed to be "select".

Defining an Object

PhoneType: {
    title: 'Phone type',
    options: { '1': 'Home phone', '2': 'Office phone', '3': 'Cell phone' }
}

Defining an Array (the most flexible)

PhoneType: {
    title: 'Phone type',
    options: [
        { Value: '1', DisplayText: 'Home phone' },
        { Value: '2', DisplayText: 'Office phone' },
        { Value: '3', DisplayText: 'Cell phone' }
    ]
}

or, if the values and displayed texts are identical:

PhoneType: {
    title: 'Phone type',
    options: ['1','2','3','4']
}

Disabled options

You can disable options (like for regular select options). Note: a selected property is not supported - which option is selected always follows the value of the record (or the defaultValue in a create form):

PhoneType: {
    title: 'Phone type',
    options: [
        { Value: '1', DisplayText: 'Home phone' },
        { Value: '2', DisplayText: 'Office phone', disabled: true },
        { Value: '3', DisplayText: 'Cell phone' }
    ]
}

Option groups

Option groups are supported by adding the "Group" property

PhoneType: {
    title: 'Phone type',
    options: [
       { Value: '1', DisplayText: 'Cat A', Group: 'Animals' },
       { Value: '2', DisplayText: 'Cat B', Group: 'Animals' },
       { Value: '3', DisplayText: 'Item X', Group: 'Things' },
    ]
}

Defining an Array with optional extra data-attributes:

PhoneType: {
    title: 'Phone type',
    options: [
        { Value: '1', DisplayText: 'Home phone', Data: {'extra_attr1': 'value1', 'extra_attr2': 'value2' } },
        { Value: '2', DisplayText: 'Office phone' },
        { Value: '3', DisplayText: 'Cell phone' }
    ]
}

These data-values will be added as data-attributes to the <option> elements of the select (they are not applied to radio buttons).

Defining a URL

PhoneType: {
    title: 'Phone type',
    options: '/Demo/GetPhoneTypes.php'
}

In this case an ajax request is made to the mentioned url. The server response should obey the following layout (with optional extra data-values):

{
    "Result": "OK",
    "Options": [
        { "DisplayText": "Home phone", "Value": "1" },
        { "DisplayText": "Office phone", "Value": "2" },
        { "DisplayText": "Cell phone", "Value": "3", "Data": {"extra_attr1": "value1", "extra_attr2": "value2" } }
    ]
}

A php example to create this:

    $stmt = $pdo->prepare($sql);
    $stmt->execute($params);
    $rows = $stmt->fetchAll(PDO::FETCH_ASSOC);
    $enhancedRows = array_map(function($row) {
        return [
            'Value' => $row['Value'],
            'DisplayText' => $row['DisplayText'],
            'Data' => [
                'extra_attr1' => $row['extra_attr1'],
                'extra_attr2' => $row['extra_attr2']
            ]
        ];
    }, $rows);

    header('Content-Type: application/json');
    echo json_encode([
        'Result' => 'OK',
        'Options' => $enhancedRows
    ]);

Defining a Function

The function either returns an option list (array) or an url where options can be fetched:

PhoneType: {
    title: 'Phone type',
    options: function (data) {
        if (data.source == 'table') {
            return '/Demo/GetPhoneTypes.php?UserType=0';
        }
        return '/Demo/GetPhoneTypes.php?UserType=' + data.record.UserType;
    }
}

For optimization, FTable caches all option lists based on the URL and serves options from local cache if you use the exactly same URL. You can clear the cache if you call data.clearCache() method in your function.

IMPORTANT: FTable also uses this function to show the related field in the table for each shown record. This is because your record contains Value of the field, not DisplayText and FTable needs to show display text (instead of value) in the table. So, when data.source=='table', returning different URLs causes more than one download to list records in the table. This may be a major performance problem. So, as shown the sample above, return URL of all options while rendering the table (data.source=='table') and return filtered options in edit/create forms (if you need).

You may want to return the data from server with an AJAX request. The function may be asynchronous: FTable awaits the returned promise (result = await field.options(data)), so you can simply return a fetch() promise or use async function (data) {...}. See demo and fetch async option.

All possible options:

  • data.source: Can be 'table', 'create', 'edit' or 'search'.
  • data.record: The related record.
  • data.dependedValues: Values of depended fields (if dependsOn is used).
  • data.clearCache(): This method is used to clear the cache for the currently returning URL. So, you can ensure that your options will be re-downloaded.
  • data.form: Reference to the create/edit form (as DOM element). It is only present while handling a dependsOn change, not on the initial render of the form.

placeholder

  • Type: text
  • Default: None
  • Description: Allows an extra placeholder in the input field: for text-like inputs it is used as the placeholder attribute, for a select an empty first option with this text is prepended (and it is used as the text of the SnapSelect placeholder for multi-selects). It is not used for checkbox/radio fields.

searchable

  • Type: Boolean
  • Default: True
  • Description: Indicates whether this column shows a search form in the toolbar if 'toolbarsearch' is set.

searchAttributes

  • Type: text
  • Default: none
  • Description: like inputAttributes , but only for the searchbar select-field. If not specified, inputAttributes will be used if present

searchDateFormat

  • Type: text
  • Default: none
  • Description: like dateFormat , but only for the searchbar date-field. If not specified, dateFormat will be used if present

searchOptions

  • Type: same forms as options
  • Default: none
  • Description: like options , but only for the searchbar select-field. If not specified, options will be used if present. Note: it is only used when the search input is actually a select (see searchType); a field without a type only becomes a searchbar select when it has options.

searchPlaceholder

  • Type: text
  • Default: None
  • Description: Allows an extra placeholder in the searchbar input field. If not specified, the placeholder value will be taken, and if that's empty a default is used: "Search..." for text inputs, "Type or select..." for datalists and the multiselect placeholder for multi-selects (date search fields fall back to an empty placeholder).

searchType

  • Type: String
  • Default: empty (value of "type" is taken)
  • Description: the search type of a column is taken from the field type by default, but this allows to change that (so you can search via text on a select-field for example). Possible values are the same as type ('text', 'date', 'checkbox', 'select', 'datalist', ...).

sorting

  • Type: Boolean
  • Default: true
  • Description: Indicates whether this column can be used to sort the table.

title

  • Type: String
  • Default: None
  • Description: The column header in the table and label in the forms for this field.

tooltip

  • Type: String
  • Default: None
  • Description: The column html title which is shown as a tooltip when hovering over it.

type

  • Type: String
  • Default: 'text'
  • Description: The data type for this field. Possible values:
    • 'password': Shows a password input.
    • 'textarea': Shows a textarea.
    • 'date': Shows a date picker. If fdatepicker is not installed/loaded, a html5 datepicker is used. If a field is type date and fdatepicker is installed, you can use the field option dateFormat: Format of date. See fdatepicker formats
    • 'radio': Shows a radio button list, see options.
    • 'select': Shows a dropdown, see options. Also see inputAttributes and/or searchAttributes to add extra html attributes to the created select field (like "multiple", and data- attributes to configure the optional SnapSelect).
    • 'checkbox': Shows a checkbox. If a field is checkbox, you can define additional field options:
      • 'values': Values for checked/unchecked states. Example: { '0' : 'Passive', '1' : 'Active' }. First value is for unchecked state, second value is for checked state.
      • 'label': By default, a checkbox's text changes when user changes the state of the checkbox. If you want to fix the text, you can set the label option for this field (string).
    • 'hidden': Renders the field as a hidden input in the create/edit forms (no label, no visible input). Use visibility or list to control whether the column shows in the table. You may want to use the option defaultValue with hidden types, so the given default value is automatically set as value for the hidden field when the form is created.
    • 'file': Shows a file input.
    • 'range','week','datetime-local',...: any valid html5 input-type
    • 'datalist': this also needs the 'options' for its values
mydatalist: {
    title: 'My Datalist input',
    type: 'datalist', 
    options: ['Option 1', 'Option 2', 'Option 3']
}

visibility

  • Type: String
  • Default: 'visible'
  • Description: Controls the visibility of the column. Possible values:
    • 'fixed': Always visible (cannot be hidden by the user).
    • 'visible': Visible by default (can be hidden by the user).
    • 'hidden': Hidden by default (can be shown by the user).
    • 'separator': indicates this column is only used as a separator title in the column visibility menu (when right-clicking on the column headers)

width

  • Type: Percentage
  • Default: none - all visible columns get an equal share (100% / number of visible columns)
  • Description: The width of the column in the table (e.g., '30%'). Ensure all column widths add up to 100%. If you resize a column with the mouse, the calculated widths are stored in your user preferences.

SnapSelect (optional dependency)

SnapSelect (@liedekef/snapselect) is an optional library that replaces a plain <select> with a modern dropdown (search, tags, select-all, clear button, ajax, ...). FTable has no hard dependency on it: FTable only enhances fields where the select is created with the multiple attribute, and only when SnapSelect is loaded. Everything else (single selects, the page-size select, ...) stays a native <select>.

FTable works without SnapSelect; nothing breaks if it is absent.

Installing

Load SnapSelect's CSS and JS before you create the FTable instance (its global SnapSelectClass is what FTable looks for):

<link rel="stylesheet" href="/path/to/snapselect/dist/css/snapselect.min.css">
<script src="/path/to/snapselect/dist/js/snapselect.min.js"></script>

Or with npm: npm install @liedekef/snapselect and import @liedekef/snapselect/dist/css/snapselect.min.css + the js file from dist/js/snapselect.min.js.

Which selects get transformed

Only selects FTable builds through its multi-select wrapper are enhanced (_buildMultiSelect()):

  • a create/edit form field of type 'select' (or a field with options) whose inputAttributes contain multiple:
Tags: {
    title: 'Tags',
    options: '/Demo/GetTagOptions',
    inputAttributes: "multiple data-live-search=true data-select-all-option=true"
}
  • the searchbar select of a column whose searchAttributes (or inputAttributes) contain multiple:
Tags: {
    title: 'Tags',
    options: '/Demo/GetTagOptions',
    searchAttributes: "multiple data-live-search=true"
}

Without SnapSelect these are plain native <select multiple> elements (wrapped in a div.ftable-multiselect-wrap), so your page keeps working.

Configuring SnapSelect per field

SnapSelect reads its configuration from data- attributes on the <select> element, and FTable copies everything from inputAttributes / searchAttributes onto that element. Supported attributes include:

Attribute Meaning
multiple turns the field into a multi-select (this is what triggers SnapSelect)
data-live-search show a search box inside the dropdown (true/false)
data-placeholder placeholder text - FTable fills this from the field placeholder (or the multiSelectPlaceholder message) automatically
data-select-all-option add a "Select All" entry (multi-select only)
data-select-optgroups clicking an optgroup label selects/deselects the whole group
data-max-selections maximum number of selected values
data-show-clear-button show a clear ("x") button
data-close-on-select close the dropdown after picking an option
data-default-text text shown when nothing is selected

Other option properties (Data on options, option groups, disabled) keep working, because SnapSelect is built on top of the real <select> - the change events FTable listens for are still fired on that element.

Accessing the SnapSelect instance

The instance is stored on the select element as select._snapselect, so you can call SnapSelect's own API (e.g. clear(), setPlaceholder(), refresh()) on it. FTable itself uses _snapselect.clear() when you press the search Reset button.

fTable Documentation

Getting Started

API reference

Tips

Examples

Clone this wiki locally