Building Apps

App navigation

QAppMetaData groups registered tables, processes, and nested apps. It is metadata, not a Java annotation. With a registered person table, this fragment adds a navigation group:

import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;

qInstance.addApp(new QAppMetaData()
   .withName("people")
   .withLabel("People")
   .withIcon(new QIcon().withName("person"))
   .withChild(qInstance.getTable("person")));

Dashboard behavior

The Material Dashboard renders record lists, forms, record views, and process screens from metadata. Which actions are available depends on backend capabilities, permissions, and table settings. Hiding a navigation item is not an authorization rule: enforce access in backend permission metadata and session security keys.

Widgets are registered in the instance and referenced by name. Backend renderers supply data for the matching frontend widget type. QQQ 4.0 uses Material Dashboard 0.41.0; the frontend is versioned separately.

Next frontend Copy preview

This describes the unreleased Next frontend implementation under acceptance. The pinned Quickstart uses Material Dashboard 0.41.0 and does not provide this Base/Full Copy flow. See release status for published versions.

Base is the default: prepare a new root record from its editable, visible values. Choose Full explicitly to include declared associations recursively. In the 4.0 sample, Base copies a Person; Full also prepares new pets and pet notes. Edit the root and child drafts, then use one Save to submit the tree. Switching modes retains draft edits; Base submits no associations.

Full requires the applicable READ and INSERT grants at each copied table, complete readable source values, and active metadata for the associated tables. A known empty group stays empty; an absent or unreadable required group fails the copy instead of silently dropping children. Inherited primary keys and parent-assigned relationship fields are omitted; provide fresh manual keys when required. Unreadable password values start blank and require new values. Normal INSERT defaults, normalization and customizers apply, so this is not an exact persisted-value clone. Named aliases produce independent copies of each path.

The backend allows at most 64 child-record levels; the Next frontend also limits a copy to 1,000 descendants. Exceeding a limit fails instead of silently dropping records. One Save does not guarantee atomic rollback: a later native error, validation failure or incomplete returned result can follow partial writes. Check persisted records before retrying a failed copy.

See the app reference and widget guide.