Overview

wtoolbox API

WtoolboxService è il service bag statico del framework WUIC: raccoglie i servizi PrimeNG, Angular e WUIC che i callback metadata (azioni di toolbar, button di riga, validation, before/after save, ecc.) usano per interagire con la UI e il backend senza dover dichiarare dipendenze.

Tutti i callback metadata ricevono wtoolbox come ultimo parametro nello scope (vedi Callback cookbook per la signature di ogni tipo). Le API descritte qui sono le uniche disponibili: il framework non espone altro come wtoolbox.<x>. Se servisse una capability non presente, va aggiunta nel framework, non inventata client-side.

Service esposti

Tutti sono public static su WtoolboxService (e quindi su wtoolbox dentro un callback).

`wtoolbox.messageNotificationService` — Toast

PrimeNG MessageService. Usato per i toast in basso a destra.

Snippet 1js

wtoolbox.messageNotificationService.add({
  severity: 'success',  // 'success' | 'info' | 'warn' | 'error'
  summary: 'Fatto',
  detail: '5 record aggiornati'
});

L'HTML embedded in summary/detail viene sanitizzato e renderizzato (es. <span style='color:red'>Record</span> mostra in rosso).

`wtoolbox.confirmationService` — Conferma raw (PrimeNG)

PrimeNG ConfirmationService. Non chiamarlo direttamente dai callback: usa il wrapper `wtoolbox.confirm()` che ritorna una Promise<boolean> pulita.

`wtoolbox.dialogService` — Dialog modali custom

PrimeNG DialogService. Apre componenti Angular custom come modali.

Snippet 2js

// Apre un componente Angular come modale (il framework lo usa internamente per
// upload, parametric-dialog, ecc.). Per dialog "input form" usa promptDialog().
const ref = wtoolbox.dialogService.open(MyComponent, {
  header: 'Titolo',
  width: '60vw',
  data: { /* @Input passati al componente */ }
});

Non ha metodo .confirm(...): per le conferme usa wtoolbox.confirm(...).

`wtoolbox.dataService` — Data provider

DataProviderService. Wrapping del CRUD framework (insert/update/delete/read via MetaService.AsmxCrud* su una route). Le toolbar action di solito chiamano direttamente endpoint REST custom; usa dataService quando ti serve un'operazione standard sulla route corrente o su un'altra route metadata.

`wtoolbox.translationService` — i18n

TranslationManagerService. Traduzioni runtime.

Snippet 3js

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

Per stringhe nuove servono chiavi in _wuic_translations + invalidate; vedi Traduzioni interfaccia.

`wtoolbox.errorHandler` — GlobalHandler

Usato dal framework per i tipi errors.client.*. Nei callback userland non serve quasi mai: una throw o Promise.reject in un callback viene già catturata e mostrata come error dialog.

`wtoolbox.http` — HttpClient

Angular HttpClient configurato con withCredentials: true per le chiamate al backend WUIC.

Snippet 4js

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

> Pattern reale dal 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>`

Spinner globale dell'app. isBusy.next(true) lo accende, isBusy.next(false) lo spegne. Da usare prima/dopo chiamate server lunghe in toolbar action.

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>`

Notifica al menu principale che la struttura va ricaricata. Usato dal framework dopo scaffolding/permission changes.

Configurazione runtime

`wtoolbox.appSettings`

Oggetto con la configurazione runtime esposta lato client. Chiavi principali:

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

Metodi statici principali

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

Mostra un dialog di conferma con label localizzate OK/Cancel. Questa è l'unica API canonica per chiedere conferma dall'utente in un callback (NON usare window.confirm, NON wtoolbox.dialogService.confirm che non esiste).

Payload: Confirmation (PrimeNG) con almeno header e message.

Snippet 7js

const ok = await wtoolbox.confirm({
  header: 'Archivia',
  message: 'Archiviare i 5 record selezionati? Operazione non reversibile.',
  icon: 'pi pi-exclamation-triangle'
});
if (!ok) return;
// ... procedi

Ritorna true se l'utente clicca OK, false se Cancel o chiude.

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

Apre un dialog con un form custom per chiedere input strutturati all'utente. Più potente di confirm (più campi tipizzati, lookup, validation).

Snippet 8js

const result = await wtoolbox.promptDialog(
  'Importa CSV',
  [
    { name: 'file', caption: 'File CSV', type: 'upload', required: true },
    { name: 'separator', caption: 'Separatore', type: 'text', value: ';' },
    { name: 'has_header', caption: 'Prima riga = header', type: 'boolean', value: true }
  ]

Tipi fields[].type supportati: text, number, boolean, date, dropdown, upload, code_editor. Per lookup tipizzati usa route (lookupRoute/lookupValueField/lookupDesField).

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

Wrapper per il dialog upload file dedicato.

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

Generatori utility. uuidv4() ritorna un GUID v4 string. getTimestamp() ritorna ISO string del momento corrente.

`wtoolbox.myFunctions`

Map estendibile dove l'app host può registrare proprie funzioni custom riusabili dai callback. Pattern:

Snippet 9js

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

Pattern canonici

Caso	API
Toast info/success/warn/error	`wtoolbox.messageNotificationService.add({severity, summary, detail})`
Conferma utente	`await wtoolbox.confirm({header, message})`
Input form custom	`await wtoolbox.promptDialog(title, fields)`
Spinner durante chiamata server	`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()`
Traduzione runtime	`wtoolbox.translationService.instant('key')`
Genera UUID	`wtoolbox.uuidv4()`
Funzioni app-specific	`wtoolbox.myFunctions.<nome>.<metodo>()`

Anti-pattern noti

Native browser API: window.confirm(), window.alert(), window.prompt() → usa wtoolbox.confirm() / wtoolbox.promptDialog() (regola 12 di AGENTS): il framework garantisce localizzazione, theme, stacking corretto.
`wtoolbox.dialogService.confirm(...)` → non esiste. dialogService ha .open(componentClass, config) per modali custom; per la conferma usa wtoolbox.confirm().
`datasource.refresh()` → non esiste. Per ricaricare la grid dopo un'azione: await datasource.fetchData().

Vedi anche

Callback cookbook — ricettario callback per tipo (toolbar action, row action, validation, ecc.).
Custom actions — workflow operativo creazione toolbar/row action.
Datasource — getSelectedRows, getSelectedKeys, fetchData.

Overview

wtoolbox API

Service esposti

wtoolbox.messageNotificationService — Toast

wtoolbox.confirmationService — Conferma raw (PrimeNG)

wtoolbox.dialogService — Dialog modali custom

wtoolbox.dataService — Data provider

wtoolbox.translationService — i18n

wtoolbox.errorHandler — GlobalHandler

wtoolbox.http — HttpClient