GridPanel

The GridPanel is a DataPanelLeaf controller and as such inherits all its base class' capabilities. For example, you can put ToolViews in a GridPanel.

By default, the grid panel is used by the List controller as the main data display area and by the Form controller to display detail records. It consists of a standard data grid linked to a ViewTable (see DataView) and a toolbar with standard operations (such as add, view/edit, delete, and refresh) and optional custom actions.

The grid may be either a plain grid or a grouped grid with a drill-down feature, as required.

Fields and columns

The grid has a column for each field in the ViewTable it is linked to. The type of each column depends on the underlying field's data type.

You can add fields from referenced models through the dot syntax (ReferenceName.FieldName:), in which case you must also provide an alias to be used as field name (ReferenceName.FieldName: AliasName).

Example:

<ViewTable>:
  Fields:
    Id:
      IsVisible: False
    Name:
    Referenced.Name: RefName

Column order equals the order of view table fields, unless a layout definition is provided.

Cell tooltip on truncated content

Cells have a fixed maximum width and truncate long text with an ellipsis (…). When a cell is truncated, hovering it shows the full value as a native browser tooltip. The tooltip appears only when the text is actually clipped: if the column is wide enough to display the whole value, no tooltip is shown. Widening the column via the drag handle removes the tooltip once the content becomes fully visible; narrowing a column below the content width restores it. Boolean checkboxes and HTMLMemo cells are excluded (they contain non-textual content).

Manual column resize

Every column header has a thin drag handle on its right edge (visible on hover as an accent-colored strip). Click and drag horizontally to widen or narrow a single column while the other columns keep their autosized width. If the total width exceeds the visible area, a horizontal scrollbar appears at the bottom of the grid so the off-screen columns stay reachable.

While dragging, the col-resize cursor (the two-headed arrow with a vertical bar) is kept visible everywhere on the page, so it does not flip back to the regular pointer when the mouse passes over column titles or rows. A click generated at the end of the drag does not trigger a sort on the dragged column.

The resize is ephemeral: widths are not saved anywhere. Closing and re-opening the grid restores all columns to their autosized defaults.

Column sorting

Clicking a column header sorts the grid by that column. An arrow icon indicates the current sort direction:

• First click on a column: sorts ascending (↑ arrow)
• Click again on the same column: sorts descending (↓ arrow)
• Click a different column: sorts ascending by the new column (replaces previous sort)

The sort state persists across page navigation (when using PagingTools) and filter changes.

Multi-column sort

Hold Ctrl (or Cmd on macOS, or Shift) while clicking a column header to add it as an additional sort key instead of replacing the current one:

• Ctrl/Cmd/Shift + click on a new column: adds it as secondary (or tertiary, etc.) sort key, ascending
• Ctrl/Cmd/Shift + click on a column already in the sort list: toggles its direction (asc ↔ desc)
• Plain click on any column: clears the multi-column state and resorts by that single column only

When more than one sort key is active, each involved header also shows a small position number (1, 2, 3…) next to the arrow, matching the precedence order passed to the database ORDER BY clause.

Initial sort order

By default, the grid has no initial sort order. To define a default sort order, use SortFieldNames in the MainTable/Controller node:

MainTable:
  Model: ACTIVITY
  Controller:
    SortFieldNames: ACTIVITY_DATE

The first field in SortFieldNames is highlighted in the grid header with an ascending arrow on initial load. When the user clicks a column, the user's choice overrides the initial sort.

SortFieldNames accepts multiple space-separated field names for multi-field sorting (e.g. SortFieldNames: LAST_NAME FIRST_NAME), but only the first field shows the sort indicator.

Sort arrows

Sort arrows are Material Design SVG icons (arrow_upward / arrow_downward) rendered via CSS pseudo-elements. They automatically adapt to the current theme (light or dark) using currentColor.

Grid layouts

Grid layouts are yaml files stored under Metadata\Views\Layouts, and by default they are searched for using a naming convention. A layout called <ViewName>_Grid.yaml is automatically used by this controller to render a view's MainTable. You can also explicitly specify a layout (useful for sharing layouts among similar views) in the Controller/Grid/Layout parameter.

A grid layout controls:

• Which fields are visible and in what order
• Optional per-column DisplayLabel, DisplayWidth (in characters), Align, and HideLabel overrides

Here is an example of a grid layout:

Field: DESCRIPTION
  DisplayWidth: 30
Field: PHASE
Field: EMPLOYEE
Field: ROLE
Field: TYPE
Field: ACTIVITY_DATE
  DisplayWidth: 12
Field: START_TIME
Field: END_TIME
Field: DURATION
  Align: right
Field: STATUS

Layout properties per field:

Property	Type	Description
DisplayLabel	String	Override the column header label
DisplayWidth	Integer	Column width in characters (ch units)
Align	String	Column alignment (left, center, right)
HideLabel	Boolean	If True, the column header is empty

Row colors

Grid rows can be colored based on data values. See How to customize grid row colors for all available options, including:

• Fixed column colors via Color or CSS field properties
• Pattern-based colors via Colors subnodes with regex matching
• RowClassProvider — a JavaScript function that returns a CSS class for each row based on field values (compatible with Kitto^x 1 API)

Grouping

To display records in collapsible groups, use the dedicated GroupingList controller instead of a standard GridPanel inside a List controller.

The GroupingList controller loads all records (no paging), groups them by a configurable field, and renders collapsible group headers with expand/collapse toggles. It inherits all features from the List controller (filters, toolbar, standard actions).

Type: Data
Controller: GroupingList

MainTable:
  Model: ACTIVITY
  Controller:
    Grouping:
      FieldName: TYPE
      StartCollapsed: True
      ShowCount: True
        ItemName: activity
        PluralItemName: activities
      SortFieldNames: TYPE ACTIVITY_DATE

See the GroupingList controller documentation for the full list of configuration options and examples.