UIBootgrid

The UIBootgrid system is a wrapper around Tabulator and provides a generic table system that is reusable on all pages requiring data listing and manipulation.

Setup

To get started, see Using grids module & plugin. The example will show you how to get started with a minimal grid setup and how this front-end code ties to the controller layer.

Basic Layout

Since the controller layer defines standardized output and expects standardized input, it’s possible to construct and feed a grid by simply defining a set of endpoints as explained in the setup:

$("#{{formGridAddress['table_id']}}").UIBootgrid(
    {
        search:'/api/gridexample/settings/search_item/',
        get:'/api/gridexample/settings/get_item/',
        set:'/api/gridexample/settings/set_item/',
        add:'/api/gridexample/settings/add_item/',
        del:'/api/gridexample/settings/del_item/',
        toggle:'/api/gridexample/settings/toggle_item/',
        info:'/api/gridexample/settings/info'
    }
);

You can use the browser developer tool to inspect the request/response structures of each operation. For example, the search endpoint looks like this:

Request:

{
    "current": 1,
    "rowCount": 50,
    "sort": {}
}

Response:

{
    "rows": [
        {
            "uuid": "3b4e949d-443b-4127-a709-1e41589db462",
            ...
        },
        ...
    ],
    "rowCount": 1,
    "total": 1,
    "current": 1
}

Note

info endpoints are not used very often (and can safely be omitted), these are mainly intended as simple trigger to display an info dialog.

Configuration Reference

The UIBootgrid initialization object starts with the CRUD methods as stated above, but the whole structure contaions a lot of options to modify the behavior to fit your purpose.

The top-level options are layed out as follows:

config
├── search
├── get
├── set
├── add
├── del
├── toggle
├── info
├── options
│   ├── ...
│   ├── ...
│   └── ...
├── commands
│   ├── ...
│   └── ...
├── tabulatorOptions
    ├── ...
    └── ...

options

General settings for bootgrid behavior

Property	Type	Default	Description
datakey	string	"uuid"	Defines the property in the data that is used for indexing into the grid. Since most model data is uniquely identified through a UUID, this property defaults to uuid. However, in some situations you may wish to override this if the data uses a different key.
disableScroll	boolean	false	Disables in-grid vertical scrolling behavior. Setting this to true means all rows will be rendered if not constrained by pagination, so be aware of the performance impact if your grid contains many rows.
sorting	boolean	true	Whether sorting should be enabled. Sorting is triggered through header clicks.
rowCount	array	[50, 100, 200, 500, 1000, true]	An array of numbers that defines the selection of row counts a user can select. The special value true, means “all rows”.
formatters	object	Internal formatters	Formatters for values in cells. See options.formatters.
headerFormatters	object	{}	Formatters for the headers of columns. See options.headerFormatters.
statusMapping	object	{}	A key-value pair representing status colors. For example: statusMapping: { 0: "fw-pass", 1: "fw-nat", 2: "fw-block", } To use this, each row must contain a status property set to one of the keys defined in the status mapping. UIBootgrid will automatically add the value as a class to the cell element. The values must be valid classes defined in CSS. This is mainly used to give rows a specific background color based on their status.
sorters	object	Internal sorters	Specify one or more custom sorter functions indexed by key. To instruct a column to use this sorter, set the sorter property through the grid_view tag as explained in Define dialog items. These sorters are only applied if ajax: false, meaning that all sorting logic happens locally.
requestHandler	function	null	Request handler callback function that’s executed before the AJAX call. The function expects 1 parameter: params and must return this same parameter. This parameter is an object that contains all data to be sent to the endpoint. With this function you may modify/override the data sent to the endpoint before it’s sent.
responseHandler	function	null	Response handler callback function that’s executed after AJAX response. This function expects 1 parameter: response and must return this same parameter. This parameter contains the response from the called endpoint. You may use this function to modify/override the response before it’s used by the grid system.
resetButton	boolean	true	Determines if the grid reset button should be rendered. The grid locally persists certain changes by default, such as column resizes, sorting behavior etc. This button clears the persistence and resets the grid to all defaults.
searchSettings	object	{delay: 1000}	Allows modifying search behaviour of the grid. Currently only “delay” is defined and set to 1000ms by default. Delay is the amount of time waiting before reloading the grid after search.
navigation	boolean	true	If the action bar, pagination and footer should be rendered.
ajax	boolean	true	If disabled, ignores any CRUD endpoint defined. Use the replace(rows) or append(rows) functions to add data to the grid yourself. If disabled, any sorting, filtering or pagination will happen locally, as all data is expected to be present in the grid. You can use the sorters to define sorting logic yourself. If enabled, uses the defined CRUD enpoints to fetch/filter/sort and modify the data.
ajaxConfig	object	See description	Ajax configuration used in all ajax calls. The defaults are: { method: "POST", dataType: "json", headers: { "Content-type": "application/json;charset=utf8" } } Override for advanced purposes.
responsive	boolean	false	If this grid is allowed to split longer lines into newlines, creating variable height grid rows. Use this if the cell content should always be visible, otherwise, the content will be cut off with an ellipsis and dynamically assigned a tooltip so hovering over the data will show the full content.
onBeforeRenderDialog	function	null	function handler which will be called before an edit dialog is being displayed, can be used to change the otherwise static dialogs. Should return a $.Deferred() object. (e.g. return (new $.Deferred()).resolve();)
virtualDOM	boolean	false	Enable or disable the virtual rendering mode of the grid. See the Tabulator docs. In essence this option makes sure that not all rows are rendered by default, but are rendered on the fly as they are needed when the user scrolls down/up. This makes it possible to render an extremely large amount of rows with very little performance impact. When using this options, keep in mind that each row may not be available in the DOM yet at any given time for direct referencing in code. Therefore, the proper onRendered callbacks should be used if you wish to refer to this element directly. See options.formatters and commands.
selection	boolean	true	Whether individual rows should be selectable through a checkbox in a left-frozen column.
multiSelect	boolean	true	Whether multiple rows may be selected for actions (delete-selected, enable-selected, disable-selected). Only relevant if selection: true
stickySelect	boolean	false	Ignores multiSelect. Enable this if selecting a row should disable the selection of another row, forcing exactly one row to be selected at all times. This is often used in master-detail views, where one row corresponds to the entries in another grid. Only relevant if selection: true
rowSelect	boolean	false	Whether rows should be selectable by clicking in any of the row cells. Keep in mind that in UX terms, this makes it difficult for users to select values in a grid for copy+pasting purposes.
batchToggle	boolean	true	Enable/disable the batching of the enable/disabled-selected actions. Batching involves taking all of the datakey strings of the selected rows and splitting these up into batchToggleSize-length chunks, and firing one toggle request per batch. The request contains all datakey strings as a single comma-separate parameter. Therefore, the controller should be capable of dealing with these keys (toggleBase). Set this to false only if your controller endpoint is not capable of dealing with multiple values in one request.
batchToggleSize	number	40	Default maximum batch side for batchToggle. This number roughly corresponds to the length of a single UUID * 40 to keep the length of a URL below its maximum. Adjust this number if the datakey is not a UUID.
batchDelete	boolean	true	Enable/disable the batching of the delete-selected action. Batching involves taking all of the datakey strings of the selected rows and splitting these up into batchDeleteSize-length chunks, and firing one delete request per batch. The request contains all datakey strings as a single comma-separate parameter. Therefore, the controller should be capable of dealing with these keys. Set this to false only if your controller endpoint is not capable of dealing with multiple values in one request.
batchDeleteSize	number	40	Default maximum batch side for batchDelete. This number roughly corresponds to the length of a single UUID * 40 to keep the length of a URL below its maximum. Adjust this number if the datakey is not a UUID.
triggerEditFor	string	null	Set this value to a datakey value (such as a UUID) to trigger the edit dialog of this particular row. This is used in cases where we are referred to from a different page to load both the grid and immediately open the right entity for editing. If we came from a different page, the edit URL parameter will be set to the datakey value. This parameter can be fetched through getUrlHash('edit'). In most cases, if triggering an edit on referral is necessary, getUrlHash('edit') should be used. If the referrer sets a different URL parameter, adjust your logic accordingly.
initialSearchPhrase	string	null	Same behaviour as triggerEditfor, but for a search phrase value. If set, the grid will load with the search value set to this string so the controller can filter on it. The standardized method to get this value is getUrlHash('search').
static	boolean	false	Disables persistent storage and resizable columns so the dimensions of the grid are predictable at all times.
bottomReserveElement	string | Element | JQuery object	'.grid-bottom-reserve''	If there is an element below the grid that should be visible at all times (no page scrollbar), you can specify this element here so the grid height calculation takes the height of this element into account.

options.formatters

Formatters are functions that are executed for each cell whose column has a formatter specified and determine the value that is presented to the user in the cell. Formatters allow you to manipulate the data fetched from the controller into a format that is more easily digestable for a user.

The formatters option is an object that contains key - function pairs, where each key corresponds to the formatter value in the grid form as explained in Define dialog items.

For example:

formatters: {
    myformatter: function (column, row, onRendered) {
        return row[column.id];
    }
}

The above example simply returns the value of the row without modifications.

The column parameter is an object that contains the id and the visibility status of the column.

The row parameter is an object that contains the data for this row.

The onRendered parameter is a callback function that allows you to execute a function when the cell has been rendered. For example:

formatters: {
    myformatter: function (column, row, onRendered) {
        onRendered((cell) => {
            console.log(`grid cell has been rendered. cell data: ${cell.getData()}`);
        })
        return row[column.id];
    }
}

This is useful if you want to bind event handlers to the rendered DOM element, or do work if the cell contains more complex objects such as graphs that are initialized asynchronously.

The callback function expects a single parameter, cell, which you can access to get the cell object

options.headerFormatters

Functionally equivalent to options.formatters, but applied to the column header value instead. By default it’s not necessary to specify a headerFormatter tag in the grid_view tag of a form, as the keys match to the row keys. For example:

headerFormatters: {
    enabled: function(column) {
        return '<i class="fa-solid fa-fw fa-check-square" data-toggle="tooltip" title="{{ lang._('Enabled') }}"></i>';
    }
}

The above example will match on the enabled row key and return an icon with a tooltip showing the translated value of the column title.

The function expects only a single parameter, column, which is an object containing id, visible, title.

commands

The Commands column is a special column that is situated frozen on the right side of the grid to ease access regardless of scroll position. This column contains buttons that are linked to actions that can be defined/extended in this configuration section.

Besides the commands defined in the commands column, there are also command buttons placed below the grid which are linked to actions that are not related to one grid row specifically, such as add or delete-selected. These buttons can also be defined in the command structure, but with the footer property set to true.

The following commands are built-in by default and are rendered automatically based on their respective CRUD endpoint requirements:

• add. Requires get, set.

• edit. Requires get, set.

• delete. Requires del.

• copy. Requires get, sets.

• info. Requires info,

• toggle. Requires toggle.

• enable-selected. Requires toggle (See batchToggle option).

• disable-selected. Requires toggle (See batchToggle option).

• delete-selected. Requires del (See batchDelete option).

You may override a specific property of the above built-in commands, as the commands object is deeply merged, e.g.:

edit: {
    sequence: 200
}

Will preserve all edit command options, but change the sequence from its default of 100 to 200.

Extra commands can be defined in the top-level commands object. The structure of a command starts with a unique key and contains an object with the following schema:

Property	Type	Required	Description
method	function	No	A function that is executed on command click. Function signature is (event, cell). The cell object is passed in only if footer is false.
title	string | function	No	Translated title to be shown as a tooltip. If the title depends on state, this property can also be a function. If it’s a function, the Cell object is passed as a parameter.
requires	array	No	An optional array of strings that define if this command depends on one or more CRUD actions. For example, the default add command depends on get and set, otherwise the form logic tied to this action wouldn’t be able to get the structure needed to construct the form, nor would it be able to call the right endpoint once “save” has been clicked. If any of the required endpoints are missing, the button isn’t rendered.
sequence	number	No	A number to control how the button is ordered amongst the other buttons.
footer	boolean	No	Whether this command should be rendered in the footer or as part of a row.
primary	boolean	No	Whether this command should be rendered as part of the primary button container. Only relevant when footer is true.
classname	string	Yes	Icon class added to the <span> inside the button element.
filter	function	No	A function that, if defined, must return true or false and determines if this command should be rendered. The Cell object is only passed in if footer is false.
onRendered	function	No	A function that runs after the element including event bindings have been rendered. This allows the caller to override the behavior of the command. The element is bound to the function and can be access through $(this), but the full Cell object is passed in as a parameter as well, but only if footer is false. This function has priority over method. This function can be used to bind the rendered command DOM element to other system components, such as $.SimpleFileUploadDlg.

There are default commands built-in to the UIBootgrid framework that work in tandem with the default controller actions to facilitate basic CRUD behavior.

For advanced use cases, you can also call the built-in command methods directly. For an example, see the Unbound overrides template

tabulatorOptions

Any option set here will be passed directly to Tabulator. Refer to their docs.

Methods

Methods on UIBootgrid can be called through the JQuery bootgrid API:

$('#<grid-id>').bootgrid('<method>', ...params);

append(rows)

Appends rows to the grid. This is a lot slower than replace(rows). Since most of the sorting/filtering logic happens remotely, replace should be the preferred method to manipulate data in the grid.

replace(rows)

Replaces all data in the grid by rows. Use this function if ajax: false to set data in the grid.

getTable()

Gets the Tabulator grid instance bound to this UIBootgrid.

clear()

Clears any data in the grid.

reload()

Reload the grid. Triggers a new AJAX request. Always use this

getRowCount()

Gets currently selected row count

getSelectedRows()

Gets the datakey values of the currently selected rows

getCurrentRows()

Gets all datakey values of all rows in the table

getCurrentPage()

Gets current paginated page.

destroy()

Destroy the grid

setColumns(columns)

Enable the visibility of columns. The columns parameter expects an array of column IDs.

unsetColumns(columns)

Disable the visibility of columns. The columns parameter expects an array of column IDs.

search(value, event)

Search for value in the grid (triggering an AJAX request if ajax: true).

select(ids)

Programatically select rows. Expects an array of datakey strings.

getSearchPhrase()

Get current search phrase.

setPersistence(value)

Enable or disable grid persistence (column setup in local storage). Expects a boolean.

Other components

If an apply button is rendered on the page through $.SimpleActionButton, :UIBootgrid will automatically signal to that element to prompt the user to apply if something in the grid changed, e.g. when a row has been edited. Internally it does this by simply calling $(document).trigger("settings-changed");.