Functions for Grids and Grid Content

General Remarks

The commands described in this page refer to grids, grid rows, grid columns, and grid cells. This section explains what that is.

Grids

A grid (in DBM) is a rectangular display of data. The main GUI of DBM has five grids. Not all grids can be displayed simultaneously, and the user can hide all but one of them.

In the grid commands, DBM’s grids are identified by self describing names: TABLES, ENTRIES, GROUP_MEMBERS, COLLECTION_MEMBERS, SEARCH_RESULT. The name MAIN is an alias for ENTRIES.

Rows

A grid row is a horizontal section of the grid. Rows contain different data of one item, e.g. of from a table or a table entry. Rows are numbered, starting with 0 at the top.

A grid may contain more rows than are visible on the screen. To see hidden rows, you can scroll the grid vertically. This does not change row numbers. In other words, then you scroll the grid down one row, row 0 becomes invisible, and the top-most visible row is number 1.

Most grids have a fixed row across their top which never scrolls out. This is called the header row. The functions described here do not access the header row.

Columns

A grid column is a vertical section of the grid. For all rows of a grid, a column contains the same type of data, e.g. the name or the length of the item. Like rows, columns are numbered, starting with 0 on the left end, and like rows, scrolling (horizontally in this case) doesn’t change column numbers.

The header row contains a title of each row. Titles are usually localized or are even read from the configuration file.

In addition, each column has a name and a numeric ID. The name is not localized nor configurable; for custom columns, the ID depends on the order in which the custom columns are configured.

The commands that access grid columns or cells can use the column position (number), the ID, the name, or the title.

Cells

A cell is the cross section of a row and a column, and it contains a specific information about an item, e.g. the creation date of a table entry.

Modifying the Grid

DefineGridColumns procedure

Add or removes columns to/from the grid, changes the order of grid columns, or changes the widths of columns.

Synopsis

This procedure removes the “Album” column from the main (“ENTRIES”) grid, adds the “Group” column in the leftmost position, and moves the “Title” column one position left.

CODE

DefineGridColumns(grid, column_operation1, column_operation2, ...)

Parameters

Name	Required?	Type	Documentation
`grid`	yes	string: one of `ENTRIES` `MAIN` `TABLES`	Selects the grid to which the operation applies. `MAIN` is an alias for `ENTRIES`.
`column_op`...	no	string	Defines the column operation(s).

The procedure can perform several column operations at once. They are performed in the order of the parameters. Each column_op parameter specifies one operation.

The syntax of each column_op is: <column_id>:<operation>[:<position>]

<column_id> is a column index (0-based), an internal (technical) field name, or a (localized or configured) GUI field name.

<operation> is one of HIDE SHOW SIZE MOVE.

The meaning of <position> depends on the <operation>:

The HIDE operation does not allow a <position>.
For the SHOW operation, the position can be _FIRST or _LAST to indicate that the new column should be inserted at the left or right end of the grid, or it can be the index or internal or GUI name of the column before which the new column should appear.
For the MOVE operation, the position is mandatory, and it must be one of _FIRST _LAST _LEFT _RIGHT to indicate the destination or direction of movement, or the index or internal or GUI name of the column before which the column should be placed.
For the SIZE operation, position is the column width in pixels. If missing, the column is resized to its default width.

Returns

Nothing.

Example

CODE

DefineGridColumns(entries, album:hide, group:show:_first, title:move:_left);

Removes the “Album” column from the main (“ENTRIES”) grid, adds the “Group” column in the leftmost position, and moves the “Title” column one position left.

Retrieving General Information

GetGridColumnCount function

Retrieves the number of columns which are currently displayed in the specified grid.

Synopsis

CODE

%count = GetGridColumnCount(grid)

Parameters

Name	Required?	Type	Documentation
`grid`	yes	string (a valid grid name)	Selects the grid to which the operation applies.

Returns

The number of columns as a non-negative number.

Example

CODE

%tables = GetRidColumnCount(tables)

Retrieves the number of columns currently displayed in the TABLES grid.

GetGridRowCount function

Retrieves the number of rows which are currently displayed in the specified grid.

Synopsis

CODE

%count = GetGridRowCount(grid)

Parameters

Name	Required?	Type	Documentation
grid	yes	string (a valid grid name)	Selects the grid to which the operation applies.

Returns

The number of rows as a non-negative number.

Example

CODE

%tables = GetRidRowCount(tables)

Retrieves the number of rows currently displayed in the TABLES grid.

GetGridColumnXXX_byYYY functions

This section describes several functions which retrieve various information about a grid column.

XXX can be one of Id, Name, Title, Position, Width, Sort, and describes the data to retrieve.

YYY is one of Id, Position, Name, Title, Any, and describes how the column is identified.

For built-in fields, the field ID is a positive number. For custom fields, it is the technical name, like “CUSTOM/MYDATAFIELD”.

Synopsis

CODE

%title = GetGridColumnTitle_byPosition(ENTRIES, 3)
%position = GetGridColumnPosition_byName(ENTRIES, Number)

Parameters

Name	Required?	Type	Documentation
grid	yes	string (a valid grid name)	Selects the grid to which the operation applies.
identifier	yes	depends (see remarks)	Identifies the column.

Returns

The requested detail, depending on the XXX part of the command name:

XXX	returned value
Id	The field ID, or -1 if this is not a valid field for this grid
Name	The field name, or an empty string if this is not a valid field for this grid
Title	The column title, or an empty string if this is not a valid field for this grid
Position	The column number (starting with 0 at the left end), or -1 if the field is not configured into a grid column
Width	The width of the column in pixels, or -1 if the field is not configured into a grid column
Sort	Whether the column sorts ascending or descending; the result is `"ASC"` or `"DESC"` or `"UNDEF"`

Remarks

The identifier parameter identifies the column as follows:

YYY	identifier
Position	The column number.
Id	The field ID of the column.
Name	The field name of the column.
Title	The column title.
Any	The field ID, field name, or column title.

Data which is not contained in the grid’s current configuration (but could be configured into the grid) can also be queried if the request is made by Id, Name, Title, or Any. A request by Position is only possible for data which is contained in a grid column.

Accessing the Data

GetGridFieldContent function

Retrieves the content if a grid cell.

Synopsis

CODE

%content = GetGridFieldContent(grid, row, column, raw)

Parameters

Name	Required?	Type	Documentation
grid	yes	string	Selects the grid to which the operation applies. `MAIN` is an alias for `ENTRIES`.
row	yes	non-negative integer or special string	0-based row index
column	yes	string or non-negative integer	0-based column index, or internal (technical) field name, or GU (localized) column title
raw	no	string	`RAW` or something else

The function works even if the column parameter specifies a field that is not contained in any grid column.

If the raw parameter is present and contains the string RAW (in any combination of upper and lower case), then some fields produce a different type of output. Typically, RAW yields an internal form (in most cases, an integer number), and the opposite ("cooked") yields a textual form. For example, definition values have an integer raw value and a name string as cooked value.

Returns

The returned value is a string or a number, depending on the field content and on the value of the parameter.

Example

CODE

%content = GetGridFieldContent(MAIN, 3, RefNo)

Retrieves the reference number from the 4th row of DBM’s MAIN grid (row 4 has row index 3).

Remarks

Aside from built-in and custom fields which can be configured into columns, the GetGridFieldContent function knows the following pseudo field names which have no corresponding ID or title values:

Pseudo field	Description
`_Groups`	Returns a (possibly empty) JSON array which contains the reference numbers of all groups of which the entry is a member.
`_Parent`	For the `GROUP_MEMBERS` or `COLLECTION_MEMBERS` grids, the reference number of the group or collection being shown.
`_Members`	For groups and collections, returns a JSON array of group or collection members; otherwise, returns an empty JSON array. The array consists of the reference numbers or, in the case of a collection, of string like `"MyTable\223"`, indicating the table and reference number.
`_Members_Full`	For groups and collections, returns a JSON array of group or collection members; otherwise, returns an empty JSON array. The array contains the complete metadata of each member.
`_XML`	Returns the complete metadata in XML format.
`_JSON`	Returns the complete metadata in JSON format.

SetGridCookie procedure

A cookie is a small portion of text. Each grid cookie is assigned to a specific grid, and can be identified by a name. Call SetGridCookie to set a cookie, and GetGridCookie to retrieve it.

Synopsis

CODE

SetGridCookie($grid, $name, $value)

Parameters

Name	Required?	Type	Documentation
grid	yes	string	Selects the grid to which the operation applies. `MAIN` is an alias for `ENTRIES`.
name	yes	string	The cookie’s name.
value	no	string	The value of the cookie. If this parameter is omitted, the cookie is deleted if it exists.

Returns

SetGridCookie doesn't return a value.

GetGridCookie function

Retrieves the value of a cookie that was set by SetGridCookie.

Synopsis

CODE

%cookie = GetGridCookie(MAIN, MY_COOKIE)

Parameters

Name	Required?	Type	Documentation
grid	yes	string	Selects the grid to which the operation applies. `MAIN` is an alias for `ENTRIES`.
name	yes	string	The cookie’s name.

Returns

The value stored in the cookie, or an empty string if the cookie doesn’t exist.

Selecting Grid Rows

GetGridSelection function

Retrieves the current selection from a grid.

Synopsis

CODE

%selected = GetGridSelection(ENTRIES, Force_Array)

Parameters

Name	Required?	Type	Documentation
grid	yes	string

Returns

A string which contains a JSON array containing the row numbers of all selected rows. This array can be empty (if nothing is selected), or have just one element (if a single row is selected).

GridCanMultiSelect function

Indicates whether a grid can select multiple rows at the same time.

Synopsis

CODE

%can_multi = GridCanMultiSelect(SEARCH_RESULTS)

Parameters

Name	Required?	Type	Documentation
`grid`	yes	string	The grid to operate on.

Returns

0 if the grid can contain select at most one selected row at a time.
1 if the grid can contain any number of selected rows.

GridAddSelect procedure

Extends the selection in a grid.

Synopsis

CODE

GridAddSelect(ENTRIES, 4) // Selects row 4 and leaves the rest of the selection intact
GridAddSelect(ENTRIES, "[8, 10]") // Selects rows 8 and 10 and leaves the rest of the selection intact

Parameters

Name	Required?	Type	Documentation
`grid`	yes	string	The grid to operate on.
`rows`	yes	any	The rows to select.

Returns

Nothing.

Remarks

The rows parameter either contains a single number, or a string which holds a JSON array with row numbers.

This function is partially superseded by SelectInGrid.

GridSelect procedure

Defines a new selection in a grid.

Synopsis

CODE

GridSelect(ENTRIES, 4) // Selects row 4 and deselects all other lines.
GridAddSelect(ENTRIES, "[8, 10]") // Selects rows 8 and 10 and deselects all other lines.

Parameters

Name	Required?	Type	Documentation
`grid`	yes	string	The grid to operate on.
`rows`	yes	any	The rows to select.

Returns

Nothing.

Remarks

The rows parameter either contains a single number, or a string which holds a JSON array with row numbers.

This function is partially superseded by SelectInGrid.

GridUnselect procedure

Shrinks the selection in a grid.

Synopsis

CODE

GridUnselect(ENTRIES, 4) // Deselects row 4 and leaves the rest of the selection intact
GridUnselect(ENTRIES, "[8, 10]") // Deselects rows 8 and 10 and leaves the rest of the selection intact

Parameters

Name	Required?	Type	Documentation
`grid`	yes	string	The grid to operate on.
`rows`	yes	any	The rows to deselect.

Returns

Nothing.

Remarks

The rows parameter either contains a single number, or a string which holds a JSON array with row numbers.

This function is partially superseded by SelectInGrid.

GridUnselectAll procedure

Removes the selection in a grid.

Synopsis

CODE

GridUnselectAll() // Deselects all selected rows

Parameters

Name	Required?	Type	Documentation
`grid`	yes	string	The grid to operate on.

Returns

Nothing.

Remarks

This function is partially superseded by SelectInGrid.

SelectInGrid function

Selects or deselects lines in a grid.

Synopsis

SelectInGrid(main, all, toggle) SelectInGrid(entries, 1, 4, add) SelectInGrid(main, remove, "1-4")

CODE

SelectInGrid(main, replace, 3, 5)
SelectInGrid(main, all, toggle)
SelectInGrid(entries, 1, 4, add)
SelectInGrid(main, remove, "1-4")

Parameters

Name	Type	Required	Description
`grid`	string	yes	Specifies the rid in which entries should be selected
`mode`	string	no	The operation mode (see below)
`range`	see below	yes	The lines to operate on (see below)

Note that mode and range parameters can swap their positions.

Returns

The string “OK”.

Remarks

The range of lines can be specified as one or as two parameters:
- One integer like 8 means "just this line".
- Two integers like 5,8 means "lines 5 through 8, both ends including".
- A string comprised of two integers separated by a dash, e.g. "6-10", means "lines 6 through 10, both ends including". Note that in this form, the parameter must be enclosed in double quotation marks "...".
- The strings all and none mean "all lines" or "no lines", resp.
The mode parameter is one of these: ADD, REMOVE, TOGGLE, or REPLACE. The default value is REPLACE.
- ADD adds the specified range of lines to the existing selection.
- REMOVE removes (deselects) the specified range of lines.
- TOGGLE toggles the selection state of the specified lines.
- REPLACE deselects all lines, then defines the new selection. If the range is none, then no lines are selected.
The order of parameters is a bit variable. grid must come first, but mode can be second or last parameter, with range taking the second or third position, or, when using two integers, the second and third, or the third and fourth positions.