DomainGrid

Defined in: js-api/src/ui/domains/domains-grid.ts:165

An editable grid over one domain table.

const grid = await DG.DomainGrid.create(grok.dapi.domains.table('grit.issue'),
  {query: {filter: 'status = "open"'}});
grok.shell.newView('Issues', [grid.root]);

DomainGrid.create is the one-await form from a bare client; the constructor is SYNCHRONOUS on a prefetched context and the rows load inside the grid (DomainGrid.ready resolves when they have).

What it composes:

• the platform's grid decoration — the registered ObjectHandler for the table gets to customize the grid (captions, ref cells showing display names, name column first, system columns hidden), exactly as in the built-in Domain View;
• a DomainFrameEditor as THE writer of the editing state: in-grid edits are tracked, validated, highlighted (amber) and marked (red, with the message in the tooltip), and saved as ONE transaction;
• permission gating from DomainTableCapabilities: no canEdit means a read-only grid, no canInsert means no Add row, no canDelete means no Delete row, and columns the caller cannot write stay read-only.

Capabilities are SNAPSHOT when the grid is built. A later grant change (or a grok.dapi.domains.invalidateUiCaches()) affects only grids created after it — an existing grid keeps the gating it was born with; rebuild it to pick the new permissions up.

Refreshing is the CALLER's decision: DomainFrameEditor.refresh rebuilds and discards pending edits by design — check DomainFrameEditor.isDirty first (this class rebinds the grid to whatever the editor rebuilds).

Extends

• Widget

Implements

• IEditorHost

Constructors

Constructor

new DomainGrid(source, options?): DomainGrid

Defined in: js-api/src/ui/domains/domains-grid.ts:184

SYNCHRONOUS over a prefetched context (the rows load afterwards — see ready), or over an editor the caller already owns (a detail grid of a master-detail page, sharing one save — forEditor).

Parameters

Parameter	Type
source	DomainFrameEditor | IDomainTableContext
options?	DomainGridOptions

Returns

DomainGrid

Overrides

Widget.constructor

Properties

Property	Modifier	Type	Default value	Description	Inherited from	Defined in
_functions	protected	Func[]	[]	-	Widget._functions	js-api/src/widgets/base.ts:277
_properties	protected	Property[]	[]	-	Widget._properties	js-api/src/widgets/base.ts:276
_root	protected	HTMLElement	undefined	-	Widget._root	js-api/src/widgets/base.ts:275
dart	public	any	undefined	-	Widget.dart	js-api/src/widgets/base.ts:280
editor	readonly	DomainFrameEditor	undefined	-	-	js-api/src/ui/domains/domains-grid.ts:167
factory	public	Func | null	null	Constructor function. No parameters, returns [Widget].	Widget.factory	js-api/src/widgets/base.ts:273
grid	readonly	Grid	undefined	-	-	js-api/src/ui/domains/domains-grid.ts:166
isDetached	public	boolean	false	-	Widget.isDetached	js-api/src/widgets/base.ts:281
props	public	any	undefined	-	Widget.props	js-api/src/widgets/base.ts:278
subs	public	Subscription[]	undefined	-	Widget.subs	js-api/src/widgets/base.ts:279
temp	public	any	undefined	Contains auxiliary information	Widget.temp	js-api/src/widgets/base.ts:270
WIDGET_ACTION_NAMESPACE	readonly	"DomainUi"	'DomainUi'	Namespace every widget-action Func is registered under — what keeps Save from colliding with another package's Save.	-	js-api/src/ui/domains/domains-grid.ts:553
WIDGET_ACTION_TAGS	readonly	"domain-ui,widget-action"	'domain-ui,widget-action'	Tags every widget-action Func carries: domain-ui marks the origin, widget-action the calling convention (one widget input).	-	js-api/src/ui/domains/domains-grid.ts:557

Accessors

aiDescription

Get Signature

get aiDescription(): string | null

Defined in: js-api/src/widgets/base.ts:340

A short AI-facing briefing: what this widget is, what its functions do, and how the assistant should approach it (e.g. which getFunctions entries to call first). Shown to the AI assistant as part of the workspace context.

Returns

string | null

Set Signature

set aiDescription(x): void

Defined in: js-api/src/widgets/base.ts:341

Parameters

Parameter	Type
x	string | null

Returns

void

Inherited from

Widget.aiDescription

---

children

Get Signature

get children(): Widget<any>[]

Defined in: js-api/src/widgets/base.ts:362

Parent widget up the DOM tree, or null.

Returns

Widget<any>[]

Inherited from

Widget.children

---

dataFrame

Get Signature

get dataFrame(): DataFrame

Defined in: js-api/src/ui/domains/domains-grid.ts:247

The frame the grid shows — replaced whenever the editor refreshes.

Returns

DataFrame

---

editable

Get Signature

get editable(): boolean

Defined in: js-api/src/ui/domains/domains-grid.ts:250

Whether in-grid editing is on (the requested mode AND the table's canEdit).

Returns

boolean

---

editors

Get Signature

get editors(): DomainFrameEditor[]

Defined in: js-api/src/ui/domains/domains-grid.ts:253

IEditorHost: the pending batch a hosting page answers for.

Returns

DomainFrameEditor[]

Every editor whose pending changes this object answers for. Read on demand: an editor that appears after the widget was constructed must show up here.

Implementation of

IEditorHost.editors

---

isDirty

Get Signature

get isDirty(): boolean

Defined in: js-api/src/ui/domains/domains-grid.ts:256

Whether anything in the grid is unsaved.

Returns

boolean

---

parent

Get Signature

get parent(): Widget<any> | null

Defined in: js-api/src/widgets/base.ts:359

Parent widget up the DOM tree, or null.

Returns

Widget<any> | null

Inherited from

Widget.parent

---

ready

Get Signature

get ready(): Promise<this>

Defined in: js-api/src/ui/domains/domains-grid.ts:264

Resolves when the first query has run — or when it FAILED, in which case the grid shows the reason and this still resolves (a rejected promise nobody awaits is an unhandled rejection). Idempotent: every call returns the same promise; a grid built on a caller's editor is ready at once.

Returns

Promise<this>

---

root

Get Signature

get root(): HTMLElement

Defined in: js-api/src/widgets/base.ts:366

Widget's visual root.

Returns

HTMLElement

Set Signature

set root(r): void

Defined in: js-api/src/widgets/base.ts:367

Parameters

Parameter	Type
r	HTMLElement

Returns

void

Inherited from

Widget.root

---

type

Get Signature

get type(): string

Defined in: js-api/src/ui/domains/domains-grid.ts:244

The platform type name — what Widget discovery and a page's nested status key on.

Returns

string

Overrides

Widget.type

Methods

addRow()

addRow(): number

Defined in: js-api/src/ui/domains/domains-grid.ts:453

Appends a row prefilled with the grid's defaults and puts the cursor on it; -1 when the editor refused (a save is in flight).

Returns

number

---

apply()

apply(properties): Widget

Defined in: js-api/src/widgets/base.ts:318

Parameters

Parameter	Type	Description
properties	object	-

Returns

Widget

Inherited from

Widget.apply

---

deleteRow()

deleteRow(): boolean

Defined in: js-api/src/ui/domains/domains-grid.ts:463

Marks the current row for deletion; false when there is no current row.

Returns

boolean

---

detach()

detach(): void

Defined in: js-api/src/ui/domains/domains-grid.ts:267

Releases the subscriptions of both the grid and its editor.

Returns

void

Overrides

Widget.detach

---

discard()

discard(): void

Defined in: js-api/src/ui/domains/domains-grid.ts:477

Drops the pending batch.

Returns

void

---

getDartProperties()

getDartProperties(): any[]

Defined in: js-api/src/widgets/base.ts:347

Returns

any[]

Inherited from

Widget.getDartProperties

---

getFunctions()

getFunctions(): Func[]

Defined in: js-api/src/ui/domains/domains-grid.ts:512

The actions this caller may perform, as REAL platform Funcs from the shared vocabulary — permission-gated exactly like the toolbar buttons.

Returns

Func[]

Overrides

Widget.getFunctions

---

getProperties()

getProperties(): Property[]

Defined in: js-api/src/widgets/base.ts:329

Returns all properties of this widget.

Returns

Property[]

Inherited from

Widget.getProperties

---

getWidgetStatus()

getWidgetStatus(): IWidgetStatus

Defined in: js-api/src/ui/domains/domains-grid.ts:493

What a grid reports about itself: its parts, how much is pending, and the first blocking error. Deliberately NO per-cell inputs — a grid's machine surface is its status, its functions and its dataFrame, which is a first-class platform object already.

Returns

IWidgetStatus

Overrides

Widget.getWidgetStatus

---

onEvent()

onEvent(eventId?): Observable<any>

Defined in: js-api/src/widgets/base.ts:415

Observes events with the specified eventId. Override in subclasses to provide actual events.

Parameters

Parameter	Type	Default value
eventId	string | null	null

Returns

Observable<any>

Inherited from

Widget.onEvent

---

onFrameAttached()

onFrameAttached(dataFrame): void

Defined in: js-api/src/widgets/base.ts:353

Parameters

Parameter	Type
dataFrame	DataFrame

Returns

void

Inherited from

Widget.onFrameAttached

---

onPropertyChanged()

onPropertyChanged(property): void

Defined in: js-api/src/widgets/base.ts:345

Gets called when viewer's property is changed.

Parameters

Parameter	Type	Description
property	Property | null	or null, if multiple properties were changed.

Returns

void

Inherited from

Widget.onPropertyChanged

---

refresh()

refresh(): Promise<void>

Defined in: js-api/src/ui/domains/domains-grid.ts:481

Re-runs the query — WITHOUT a prompt: refreshing IS discarding, and the gate belongs to whoever owns the page (see DomainFrameEditor.refresh).

Returns

Promise<void>

---

save()

save(): Promise<boolean>

Defined in: js-api/src/ui/domains/domains-grid.ts:474

Writes the pending batch as one transaction.

Returns

Promise<boolean>

---

sourceRowsChanged()

sourceRowsChanged(): void

Defined in: js-api/src/widgets/base.ts:351

Returns

void

Inherited from

Widget.sourceRowsChanged

---

sub()

sub(subscription): void

Defined in: js-api/src/widgets/base.ts:311

Registers a subscription to an external event.

Parameters

Parameter	Type	Description
subscription	Subscription	-

Returns

void

Inherited from

Widget.sub

---

toDart()

toDart(): any

Defined in: js-api/src/widgets/base.ts:303

Returns

any

Inherited from

Widget.toDart

---

actionFuncName()

static actionFuncName(caption): string

Defined in: js-api/src/ui/domains/domains-grid.ts:643

A function name for [caption]: identifier characters only, so an action called 'Edit...' registers as Edit.

Parameters

Parameter	Type
caption	string

Returns

string

---

addRowFunc()

static addRowFunc(): Func

Defined in: js-api/src/ui/domains/domains-grid.ts:613

Appends an empty row to a grid's pending batch (prefilled with the grid's defaults); false when the widget cannot insert.

Returns

Func

---

create()

static create(client, options?): Promise<DomainGrid>

Defined in: js-api/src/ui/domains/domains-grid.ts:231

Builds the grid: resolves the table's registry metadata and capabilities, runs the query, attaches the editor and decorates the grid through the table's registered handler.

Parameters

Parameter	Type
client	DomainTableClient
options?	DomainGridOptions

Returns

Promise<DomainGrid>

---

decorate()

static decorate(grid, table, dataFrame?): void

Defined in: js-api/src/ui/domains/domains-grid.ts:315

Customizes [grid] the way the platform customizes every grid over [table]'s rows: column captions, reference cells showing display names, the name column first, system and ~ columns hidden.

Decoration goes through the handler that WINS dispatch for the table, which is safe for plain handlers — one that does not override renderGrid falls through to the platform meta from the JS side too.

Which is not a one-liner, because forEntity resolves plenty of handlers that must NOT be decorated through. It applies the collapse rule of the built-in Domain View (DomainView.refreshGrid) branch for branch — with the Dart one widened, since the Dart rule names DomainRowMeta while every Dart meta reaches JS as one wrapping proxy:

• a DART meta collapses — the resolved proxy may be the inert GENERIC 'DomainRow' fallback (no per-table meta registered, e.g. a session with domain databases not enabled), whose renderGrid early-returns into a raw grid; a registered per-table meta decorates identically to own anyway;
• a JS handler WITHOUT a real renderGrid collapses — the base method is a no-op the platform marks isPlatformDefault;
• everything else wins, INCLUDING a plugin handler that claims the table through isApplicable under a type of its own.

own's inherited renderGrid reaches the per-table meta regardless of registration, so the collapse never loses decoration.

Parameters

Parameter	Type
grid	Grid
table	string
dataFrame?	DataFrame

Returns

void

---

deleteRowFunc()

static deleteRowFunc(): Func

Defined in: js-api/src/ui/domains/domains-grid.ts:622

Marks the widget's current row for deletion (the save writes it).

Returns

Func

---

discardFunc()

static discardFunc(): Func

Defined in: js-api/src/ui/domains/domains-grid.ts:592

Drops the widget's pending changes.

Returns

Func

---

find()

static find(root): Widget<any> | null

Defined in: js-api/src/widgets/base.ts:299

Finds existing widget from its visual root.

Parameters

Parameter	Type
root	Element

Returns

Widget<any> | null

Inherited from

Widget.find

---

forEditor()

static forEditor(editor, options?): DomainGrid

Defined in: js-api/src/ui/domains/domains-grid.ts:238

Builds the grid over an editor the caller already owns (a detail grid of a master-detail form sharing one save).

Parameters

Parameter	Type
editor	DomainFrameEditor
options?	DomainGridOptions

Returns

DomainGrid

---

fromRoot()

static fromRoot(root): Widget

Defined in: js-api/src/widgets/base.ts:421

Creates a new widget from the root element.

Parameters

Parameter	Type
root	HTMLElement

Returns

Widget

Inherited from

Widget.fromRoot

---

getAll()

static getAll(): Widget<any>[]

Defined in: js-api/src/widgets/base.ts:294

Returns all currently active widgets.

Returns

Widget<any>[]

Inherited from

Widget.getAll

---

refreshFunc()

static refreshFunc(): Func

Defined in: js-api/src/ui/domains/domains-grid.ts:632

Re-reads the widget's rows from the server (through the unsaved-changes gate of whatever owns it).

Returns

Func

---

resetFunc()

static resetFunc(): Func

Defined in: js-api/src/ui/domains/domains-grid.ts:602

Puts the widget back to the values it was opened with.

Returns

Func

---

saveFunc()

static saveFunc(): Func

Defined in: js-api/src/ui/domains/domains-grid.ts:585

Writes the widget's pending changes (one transaction per editor); resolves to whether everything landed.

Returns

Func

---

widgetActionFunc()

static widgetActionFunc(name, run, description): Func

Defined in: js-api/src/ui/domains/domains-grid.ts:566

The widget-action Func called [name], registering it on first use.

Idempotent by qualified name (DomainUi:<name>): the first registration wins and every later call returns the same Func, so a library bundled into several packages registers one vocabulary, not one per bundle.

Parameters

Parameter	Type
name	string
run	(widget) => Promise<boolean>
description	string

Returns

Func