GridPanel

The GridPanel is the grid presenter: it shows the records of a view table as a paged, sortable table with a toolbar of standard actions. It is a DataPanelLeaf controller and as such inherits all its base class' capabilities, such as ToolViews.

You rarely name it in YAML. It is what a List controller shows in its Center when no CenterController is declared, and what the Form controller uses to display detail records. You name it when you want a grid beside another presenter (TasKitto, ActivityBarChart):

Type: Data
Controller: List
  CenterController: ChartPanel
    Chart:
      # ...chart config...
  WestController: GridPanel
    Width: 500
    Split: True
MainTable:
  IsReadOnly: True
  Model: ACTIVITY_BY_TYPE

Hosted in a List, the grid takes from it what belongs to the list of data: the filter panel (rendered by the List above its content), the standard action flags and the lookup context. What follows describes what the grid itself draws. The grid may be either a plain grid or, through the GroupingList controller, a grouped grid with collapsible headers.

Toolbar

Above the table the grid renders its toolbar: Add, Duplicate, Edit, Delete, View, Refresh, the optional Help button, then the custom ToolViews declared under MainTable/Controller/ToolViews. Which standard buttons appear is decided by the hosting List (flags, read-only view table, user permissions). Buttons that act on a record are enabled once a row is selected.

Double-click to open

Double-clicking a row opens the record form:

• If the Edit action is visible and allowed for the current user, double-click opens the form in edit mode.
• Otherwise, if the View action is visible, double-click opens the form in view mode.
• If neither action is available, double-click has no effect.

The form opens as a dialog, or in the side panel when the List hosts the form of the current record. In a lookup dialog a double click picks the row instead. This behavior is automatic and applies to the GroupingList controller as well.

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. Sorting is interactive only in the plain grid: the GroupingList uses the fixed order given by SortFieldNames.

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.

Paging

Whether the grid pages its rows server-side, and how many per page, is decided by PagingTools and PageRecordCount under MainTable/Controller, with defaults driven by the model's IsLarge flag. See AutoOpen and PagingTools. Paging concerns the grid only: a chart or a calendar beside it always plots all the filtered records.

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, a GridPanel variant, instead of the plain grid.

The GroupingList controller loads all records (no paging), groups them by a configurable field, and renders collapsible group headers with expand/collapse toggles. It keeps the toolbar, the column layouts and the standard actions of the grid, and the filters of the hosting List.

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.

See also

• List — the host: composing presenters, filters, standard actions
• DataPanelLeaf — what all data panels share (ToolViews, SortFieldNames, DefaultFilter)
• Form — the record form opened from the grid