Skip to main content

Datatable View Settings

The View Settings dialog lets a user tailor a datatable view (the juneau-console-views table card) and keep those choices across reloads. This page covers the dialog's tabs, how settings persist and are applied, the Sort tab, auto-refresh, the per-column search announcer and the Copy link button. For the catalog keys that configure a view see Rich Table Views; for the page-state store and the ?state= URL codec see View Settings and Shareable Links.

Dialog tabs​

The dialog has four tabs: View (columns: visibility, order, label, format), Search (which columns take part in the search box), Sort and Options. The tabs follow the WAI-ARIA tabs pattern: each tab carries aria-selected and aria-controls, only the active tab is in the Tab order, and Left, Right, Home and End move between tabs. Every per-row control (visible, move up/down, label, format and so on) has an aria-label that names its column.

Restricting the tabs​

A view can show fewer tabs with columnConfig.tabs in its catalog:

{ "columnConfig": { "tabs": ["columns", "sort"] } }

The names are columns, search, sort and options; columns is the tab shown on screen as View. An empty or unknown list falls back to all four tabs. Settings that belong to a hidden tab are not read from, applied from or written to the stored settings for that view.

Persistence​

Apply writes one settings blob per table into the page-state store (browser localStorage by default). The blob carries a schemaVersion, currently 2. When the stored blob has a different (older, newer or missing) schemaVersion, or the sort is in the old string-array form, the runtime deletes it, falls back to the catalog defaults and shows a one-time notice ("your saved settings were reset"). It never tries to migrate a blob it does not recognise.

A stored blob is used only by tables whose catalog has columnConfig; it is ignored for any other table.

Settings are applied on load​

Stored settings take effect when the page loads, not only when the dialog is opened. On the first draw the runtime restores the View (visible columns, order, labels, formats), Search membership, Sort, and the Options (page size, wrap, density, auto-refresh), each gated on the tabs the view exposes. A column a user hid stays hidden after a reload, in both client and server data modes. The dialog itself opens seeded from the restored settings, so pressing Apply without touching anything does not overwrite them with the catalog defaults.

Sort tab​

The Sort tab is an ordered priority list. Each entry names a column and a direction (Asc or Desc); the first entry is the primary sort key. The draft starts from the view's defaultOrder, so an untouched Apply keeps the default order instead of persisting an ascending sort over every column. Sort is stored as a list of {column, direction} entries.

Options tab and auto-refresh​

Besides page size, wrap and density, the Options tab has an Auto-refresh choice: Off (the default), 30 seconds, 1 minute, 5 minutes or 15 minutes. It is stored as autoRefreshMs (0 for Off), and a blob written before the option existed reads as Off.

Auto-refresh re-draws the table from the server using the same path as the manual refresh. It does not run while:

  • the View Settings dialog is open,
  • a row-detail region is open,
  • a request is already in flight, or
  • the browser tab is hidden.

The timer is cleared when the table is torn down or re-initialised.

Behavior change

The suspension check used by polling, isPollSuspended, now also returns true while the View Settings dialog is open. A view declared with pausePollingWhileEditing therefore pauses its polling while the dialog is open.

Every header cell of a searchable column has a search icon that opens a small popover (it replaces the old ribbon-level columnSearchToggle button). The popover shows a one-line help text for the column's SearchType.

The table has a polite aria-live region that announces results to screen readers. When the popover is dismissed with text that has not been applied, it announces "Search for 'x' not applied." so the typed text is not lost silently.

The Copy link button sits beside the settings gear. It copies the shareable ?state= URL described in View Settings and Shareable Links and announces "Link copied." or, if the clipboard is unavailable or denied, "Could not copy link."

The button is shown when the table is primary: true, or when it is the only top-level view table on the page. Set primary: false to hide it for a table, or copyLink: false to hide only the button. It is not rendered when juneau-urlstate.js is not loaded. When a page opens with ?state=, the tab is found by matching the value against the data-juneau-strip-tab attribute of the page's tab elements; a value that matches no tab is ignored.

See also​