Skip to main content

Catalog and Columns

A table card is authored as a JSON5 catalog in the body of <@card type="datatables">. The chrome parses it, lifts it into the view contract and stamps the current contract versions (see Contract versions). You never hand-author the version numbers.

<@card type="datatables" id="pets" title="Pets">
{
dataUrl: '/console/pets/data',
dataMode: 'server',
defaultOrder: [[0, 'asc']],
columns: [
{ key: 'name', label: 'Name', searchType: 'text' },
{ key: 'status', label: 'Status', searchType: 'enum' },
{ key: 'price', label: 'Price', searchType: 'numeric', searchOperators: ['eq', 'gt', 'lt', 'between'] }
]
}
</@card>

Catalog keys​

dataUrl and columns are required; a catalog missing either fails the render with an IllegalArgumentException naming the card. Each column is an object.

KeyMeaning
dataUrlSame-origin URL the table fetches its rows from. Must be a path, not an absolute cross-origin URL.
columns[].key (or data)The row-data property this column reads.
columns[].label (or title)The header text.
columns[].searchTypeMakes the column searchable. One of the SearchType wire tokens below. A column without it is not searchable.
columns[].searchOperatorsOptional allow-list narrowing the operators offered for the column.
columns[].customOperatorsOptional [{name, help}] list of extra operators, with the help text the header popup shows.
defaultOrder, ribbon, dataMode, rowType, pollIntervalMs, columnConfig, cleanAddress, primaryCopied verbatim onto the view metadata when present.

The dataMode: "server" setting selects server-side processing, driven by juneau-datatables.js. The host must compose DataTablesMixin; see the module table.

The data endpoint behind dataUrl is an ordinary REST operation that answers a DataTables request. See DataTables Server-Side Processing for the endpoint and BeanQuery for the query language it executes.

The standard ribbon​

Ribbons.standard() builds the ribbon most tables want, in a fixed slot order, each item with a stable id:

SlotIdGroupNotes
SearchsearchsearchRibbons.search(); the table search box, placed in the ribbon.
Createcaller'sentityAdded with create(RibbonItem...).
Filterscaller'sfilterAdded with filter(RibbonItem...).
Exportexportexportexport("excel", "pdf") adds optional buttons next to copy and CSV.
Copy linklinkexportRibbons.linkButton(); copies the page link with the current view state.
Collapse allcollapseviewingHidden when the table has no row detail.
ColumnscolumnsviewingRibbons.columnSettings(); opens the column chooser.
ResetresetviewingHidden when the table has no columnConfig.
RefreshrefreshpagerefreshId(String) renames it.

without(String id) drops a slot and build() returns the List<RibbonItem> for TableSpec.ribbon(List). An item whose slot is hidden leaves no handle on the page. The canonical group order is search, entity, filter, export, viewing, page, status.

When a ribbon carries a columnSettings or linkButton item, the ribbon claims that control and the table's own auto-mounted button defers, so the page never shows two. Every ribbon item needs an id. An item without an explicit icon gets one by fallback. An action item uses its icon(...) name when given, else the neutral default for its type; an option uses its explicit icon, then a keyword hint taken from its id, then the first glyph of a fixed list that no sibling in the same group already shows. A publish item defaults to a push glyph. The excel and pdf buttons need the datatables-export toolkit pack in addition to datatables-buttons.

Search types and operators​

Column (in org.apache.juneau.console.views) pairs a column name with a SearchType and an optional SearchOperatorSet. The search types come from org.apache.juneau.commons.beanquery.SearchType:

searchTypeMatches
textCase-insensitive contains.
idCase-insensitive contains, intended for identifiers.
numericExact number; range operators and relative offsets such as -24h.
versionPrefix match on dotted versions.
timestampExact instant, with range operators and relative offsets.
enumOne value, case-insensitive.
booleantrue or false.

When a column names no operator set it inherits the table-level set, SearchOperatorSet.standard() by default. Column.effectiveOperators() reports the resolved list, and Column.searchMeta() produces the search block that goes on the wire (the token plus each operator with its help text).

Column price = Column.create("price")
.label("Price")
.searchType(SearchType.NUMERIC);

Field format​

FieldFormat says how a text value is painted into a slot. It is the main sanitization choice for long-form text, used by regions and detail fields.

ConstantWire tokenBehavior
TEXTtexttextContent. The default and omitted from the wire.
MARKDOWNmarkdownParsed as markdown and copied node by node through an allowlist. Never innerHTML.
SANITIZED_HTMLsanitizedHtmlRich HTML the caller has already sanitized; painted through a wider second allowlist.

SANITIZED_HTML is not a raw-HTML sink. The runtime parses the value into an inert document and copies only allowlisted elements and attributes, so event-handler attributes, style and srcdoc cannot survive. The contract is still caller-sanitizes-first. See Security Model.

Field span​

FieldSpan is a closed vocabulary (ONE, the default, and FULL, every column the grid is currently rendering) that sets how many grid columns a detail field occupies. It maps to a framework class; an author never supplies a CSS value.

Authoring surface for actions and selection​

Row actions, selection and bulk mutation are documented on their own page. Note that the catalog lift copies only the keys in the table above. The action, selection and bulk beans are the wire-contract types for those features; check that page for how they reach a page today.