Custom UI Hooks

Generated reference for the iPrintessApi methods tagged #ai-api:custom-ui in printess-editor.d.ts. Custom types referenced below (parameter and return shapes) are documented on the Types reference.

closeDialog

closeDialog(): void

Closes the dialog

Returns: void

closeMobileOverlay

closeMobileOverlay(): void

Closes the currently open mobile overlay, in most cases the Form-Field overlay. Does nothing on desktop or when no mobile overlay is open.

Returns: void

disableDialogButtons

disableDialogButtons(): void

Disables all buttons of the dialog opened with openDialog()

Returns: void

enableDialogButtons

enableDialogButtons(): void

Enables all buttons of the dialog opened with openDialog()

Returns: void

getResourcePath

getResourcePath(): string

retrieves root path for images

Returns: string

gl

gl(translationKey: string, ...params: Array<string | number>): string

Returns a translation as string to display the ui in different languages

Returns: string

hideProgress

hideProgress(): void

hides progress overlay

Returns: void

mountFormFieldPanel

mountFormFieldPanel(formFieldName: string, container: HTMLDivElement): string | undefined

Mounts the panel-script bound to a Form Field of dataType = "panel-script" into container. The script runs once with api, form, html, render in scope, calls await api.openPanel() to obtain the container, and manages its own re-renders / internal state from there on (mirroring the api.openDialog() pattern). Returns undefined on success, or a human-readable error string on failure.

Returns: string | undefined

openDialog

openDialog(options: IGenericDialogOptions): Promise<HTMLDivElement>

Helper function for Panel-Ui Shows a dialog with headline and ok / cancel buttons. Returns a container to render your own content in.

Returns: Promise<HTMLDivElement>

openPanel

openPanel(): Promise<HTMLDivElement>

Inside a panel_* script body, returns the mount container the panel should render into. Mirrors openDialog() without buttons or headline. Must be called while a panel script is being invoked by the host; throws otherwise.

Returns: Promise<HTMLDivElement>

querySelector

querySelector(selectors: string): HTMLElement | null

retrieves any element inside the printess shadow root In script Dialogs ONLY USE this method to find your Elements

Returns: HTMLElement | null

readStateFromFormField

readStateFromFormField<T = unknown>(fieldName: string): T | undefined

Companion to writeStateToFormField — reads and JSON-parses the value back. Returns the parsed state, or undefined when the field does not exist, is empty, or is not valid JSON. Never throws; safe to call eagerly when a panel mounts.

Returns: T | undefined

showProgress

showProgress(message: string): void

Shows simple progress overlay. The fallback for a script that has to report progress with no dialog or panel open - a surface locks itself instead.

Returns: void

writeStateToFormField

writeStateToFormField(fieldName: string, state: unknown): Promise<string | undefined>

Persists JSON-serialisable state into a hidden (admin-visibility) text-area Form Field, so a panel_* script can restore its UI on tab change OR on a full template reload.

If fieldName does not yet exist, a Form Field is created on the fly: dataType string, uiControl text-area, visibility admin (invisible to the buyer). If it already exists, the value is overwritten and the schema is left alone — pick a unique name per panel.

Returns undefined on success, or a human-readable error string on failure.

Returns: Promise<string | undefined>