Overview

wtoolbox API

WtoolboxService is the framework's static service bag in WUIC: it gathers the PrimeNG, Angular and WUIC services that metadata callbacks (toolbar actions, row buttons, validation, before/after save, etc.) use to interact with the UI and the backend without having to declare dependencies.

All metadata callbacks receive wtoolbox as the last parameter in scope (see Callback cookbook for the signature of each type). The APIs described here are the only ones available: the framework does not expose anything else as wtoolbox.<x>. If a missing capability is needed, it has to be added to the framework, not invented client-side.

Exposed services

All are public static on WtoolboxService (and therefore on wtoolbox inside a callback).

`wtoolbox.messageNotificationService` — Toast

PrimeNG MessageService. Used for toasts at the bottom right.

Snippet 1js

wtoolbox.messageNotificationService.add({
  severity: 'success',  // 'success' | 'info' | 'warn' | 'error'
  summary: 'Done',
  detail: '5 records updated'
});

The HTML embedded in summary/detail is sanitized and rendered (e.g. <span style='color:red'>Record</span> is shown in red).

`wtoolbox.confirmationService` — Raw confirm (PrimeNG)

PrimeNG ConfirmationService. Do not call it directly from callbacks: use the wrapper `wtoolbox.confirm()` which returns a clean Promise<boolean>.

`wtoolbox.dialogService` — Custom modal dialogs

PrimeNG DialogService. Opens custom Angular components as modals.

Snippet 2js

// Opens an Angular component as a modal (the framework uses it internally for
// upload, parametric-dialog, etc.). For "input form" dialogs use promptDialog().
const ref = wtoolbox.dialogService.open(MyComponent, {
  header: 'Title',
  width: '60vw',
  data: { /* @Input passed to the component */ }
});

It does not have a .confirm(...) method: for confirmations use wtoolbox.confirm(...).

`wtoolbox.dataService` — Data provider

DataProviderService. Wraps the framework CRUD (insert/update/delete/read via MetaService.AsmxCrud* on a route). Toolbar actions usually call custom REST endpoints directly; use dataService when you need a standard operation on the current route or on another metadata route.

`wtoolbox.translationService` — i18n

TranslationManagerService. Runtime translations.

Snippet 3js

const ok = wtoolbox.translationService.instant('OK');  // synchronous string

For new strings you need keys in _wuic_translations + invalidate; see Interface translations.

`wtoolbox.errorHandler` — GlobalHandler

Used by the framework for errors.client.* types. In userland callbacks it is almost never needed: a throw or Promise.reject inside a callback is already caught and shown as an error dialog.

`wtoolbox.http` — HttpClient

Angular HttpClient configured with withCredentials: true for calls to the WUIC backend.

Snippet 4js

const res = await wtoolbox.http.post(
  wtoolbox.appSettings.global_root_url + 'my-endpoint',
  { id: 42 }
).toPromise();

> Real pattern from the codebase (scaffolding toolbar action):

Snippet 5js

> wtoolbox.isBusy.next(true);
> var postResults = await wtoolbox.http.post(
>   wtoolbox.appSettings.global_root_url + 'scaffolding.scaffoldDB',
>   { connName: record.connection.value }
> ).toPromise();
> wtoolbox.isBusy.next(false);
>

State observables

`wtoolbox.isBusy: BehaviorSubject<boolean>`

Global app spinner. isBusy.next(true) turns it on, isBusy.next(false) turns it off. Use it before/after long server calls in toolbar actions.

Snippet 6js

wtoolbox.isBusy.next(true);
try {
  const r = await wtoolbox.http.get('/api/foo').toPromise();
  // ...
} finally {
  wtoolbox.isBusy.next(false);
}

`wtoolbox.menuUpdated: BehaviorSubject<boolean>`

Notifies the main menu that its structure must be reloaded. Used by the framework after scaffolding/permission changes.

Runtime configuration

`wtoolbox.appSettings`

Object with the runtime configuration exposed on the client side. Main keys:

wtoolbox.appSettings.global_root_url — backend base URL (e.g. http://localhost:5000/api/Meta/)
wtoolbox.appSettings.meta_url — Meta API base URL
wtoolbox.appSettings.api_url — custom controller API base URL
...

Main static methods

`wtoolbox.confirm(payload): Promise<boolean>`

Shows a confirmation dialog with localized OK/Cancel labels. This is the only canonical API to ask the user for confirmation in a callback (DO NOT use window.confirm, DO NOT use wtoolbox.dialogService.confirm which does not exist).

Payload: Confirmation (PrimeNG) with at least header and message.

Snippet 7js

const ok = await wtoolbox.confirm({
  header: 'Archive',
  message: 'Archive the 5 selected records? This operation cannot be undone.',
  icon: 'pi pi-exclamation-triangle'
});
if (!ok) return;
// ... proceed

Returns true if the user clicks OK, false if Cancel or close.

`wtoolbox.promptDialog(title, fields, width?, height?, customValidation?): Promise<any>`

Opens a dialog with a custom form to ask the user for structured input. More powerful than confirm (multiple typed fields, lookups, validation).

Snippet 8js

const result = await wtoolbox.promptDialog(
  'Import CSV',
  [
    { name: 'file', caption: 'CSV File', type: 'upload', required: true },
    { name: 'separator', caption: 'Separator', type: 'text', value: ';' },
    { name: 'has_header', caption: 'First row = header', type: 'boolean', value: true }
  ]

Supported fields[].type values: text, number, boolean, date, dropdown, upload, code_editor. For typed lookups use route (lookupRoute/lookupValueField/lookupDesField).

`wtoolbox.uploadDialog(opts): Promise<any>`

Wrapper for the dedicated file upload dialog.

`wtoolbox.uuidv4()` / `wtoolbox.getTimestamp()`

Utility generators. uuidv4() returns a v4 GUID string. getTimestamp() returns the ISO string of the current moment.

`wtoolbox.myFunctions`

Extensible map where the host app can register its own custom functions reusable from callbacks. Pattern:

Snippet 9js

// app boot (e.g. WuicTest app.component.ts):
WtoolboxService.myFunctions['utility'] = new MyUtilityClass();
// metadata callback:
wtoolbox.myFunctions.utility.doSomething();

Canonical patterns

Case	API
Toast info/success/warn/error	`wtoolbox.messageNotificationService.add({severity, summary, detail})`
User confirmation	`await wtoolbox.confirm({header, message})`
Custom input form	`await wtoolbox.promptDialog(title, fields)`
Spinner during a server call	`wtoolbox.isBusy.next(true)` ... `wtoolbox.isBusy.next(false)`
GET server	`await wtoolbox.http.get(url).toPromise()`
POST server	`await wtoolbox.http.post(url, body).toPromise()`
Runtime translation	`wtoolbox.translationService.instant('key')`
Generate UUID	`wtoolbox.uuidv4()`
App-specific functions	`wtoolbox.myFunctions.<name>.<method>()`

Known anti-patterns

Native browser APIs: window.confirm(), window.alert(), window.prompt() → use wtoolbox.confirm() / wtoolbox.promptDialog() (rule 12 in AGENTS): the framework guarantees localization, theming and correct stacking.
`wtoolbox.dialogService.confirm(...)` → does not exist. dialogService has .open(componentClass, config) for custom modals; for confirmation use wtoolbox.confirm().
`datasource.refresh()` → does not exist. To reload the grid after an action: await datasource.fetchData().

Overview

wtoolbox API

Exposed services

wtoolbox.messageNotificationService — Toast

wtoolbox.confirmationService — Raw confirm (PrimeNG)

wtoolbox.dialogService — Custom modal dialogs

wtoolbox.dataService — Data provider

wtoolbox.translationService — i18n

wtoolbox.errorHandler — GlobalHandler

wtoolbox.http — HttpClient

State observables

wtoolbox.isBusy: BehaviorSubject<boolean>

wtoolbox.menuUpdated: BehaviorSubject<boolean>