Overview

Metadata

Guida operativa ai metadati del framework con focus su effetti applicativi lato client e lato server.

Scope

Tipi coperti: tabella, colonna, menu, custom actions, autorizzazioni tabella/colonna, stili tabella/colonna, condition groups.
Origine UI: form aperti dal metadata-editor (menu Metadati e Metadati correlati).
Trasporto runtime: endpoint MetaService.* via AsmxProxy.

Screenshot Reference (Metadata Editor)

metadata-editor-table: form metadata tabella.
metadata-editor-columns: form metadata colonna (insert/edit).
metadata-editor-custom-actions: form azioni custom tabella.
metadata-editor-auth-table: form autorizzazioni tabella.
metadata-editor-auth-column: form autorizzazioni colonna.
metadata-editor-styles-table: form stili tabella.
metadata-editor-styles-column: form stili colonna.
metadata-editor-condition-groups: form condition groups.
metadata-menu-management: lista gestione menu metadata.

Flusso Runtime

MetaService.getTableMetadata: carica tabella + colonne + relazioni metadata.
MetaService.getFlatRecordData: usa metadata per comporre query, filtri, sort e paging.

Metadata-editor Contestuale

Il metadata-editor contestuale permette di aprire e modificare rapidamente i metadati direttamente dal contesto operativo (griglia/form/azione corrente), senza dover navigare manualmente tra tutte le route tecniche del menu metadati.

Obiettivo: ridurre i passaggi per interventi mirati su tabella, colonna e configurazioni collegate.
Vantaggio pratico: il focus resta sull'entita in uso, con accesso rapido alle opzioni piu frequenti.
Uso consigliato: manutenzione incrementale durante test funzionali e tuning UI/runtime.

Screen riferimento

manual__metadata_context_editor__01.png: apertura editor contestuale e accesso rapido alle sezioni metadata.
manual__metadata_context_editor__02.png: dettaglio operativo del flusso contestuale con modifica guidata.

Metadati Tabella (`_metadati__tabelle`)

Routing e storage

md_route_name: route logica del datasource. Client: costruisce URL/hash route e binding datasource. Server: lookup metadata/tabella e query generation.
md_nome_tabella: nome tabella/view fisica. Client: trasparente in UI. Server: target SQL principale.
md_schema_name: schema DB. Client: nessun impatto diretto. Server: qualifica oggetto SQL.
md_conn_name: nome connection metadata. Client: nessun impatto diretto. Server: selezione connessione (es. DataSQLConnection).
md_db_name: database target. Client: nessun impatto diretto. Server: instradamento query/scaffolding.

Operativita CRUD e UI

md_editable: abilita edit record. Client: pulsanti/modale edit. Server: gate logico update.
md_insertable: abilita insert record. Client: pulsante aggiungi/form insert. Server: gate logico insert.
md_deletable: abilita delete record. Client: comando elimina visibile/usabile. Server: gate logico delete.
md_detail_action: abilita vista dettaglio. Client: azione detail in grid. Server: nessun effetto SQL diretto.
md_clonable: abilita clone. Client: pulsante clone. Server: logica clone + eventuale cloneDefinition.
md_inline_edit: edit inline in griglia. Client: editor in cella/riga. Server: stessa pipeline sync/update.
md_edit_popup: edit in popup. Client: scelta UX modal vs inline. Server: invariato.

Query, filtri, paging

md_server_side_operations: delega sort/filter/paging al server. Client: invia FilterInfo, SortInfo, PageInfo. Server: compone query dinamica.
md_pageable: abilita paginazione. Client: pager attivo. Server: applica limit/offset o cursor policy.
md_pagesize: dimensione pagina default. Client: valore iniziale pager. Server: TOP/OFFSET o batch cursor.
md_sortable: abilita sort in UI. Client: header sortabili. Server: ORDER BY solo se richiesto/consentito.
md_default_filter: filtro iniziale. Client: pre-carica filtro. Server: merge nel WHERE.
md_disabilita_filtri: disabilita pannello filtri. Client: hide filter bar. Server: riduce filtri runtime disponibili.
md_show_record_count: richiede totale record. Client: pagina X di Y. Server: COUNT(*) (o policy alternativa via props bag).

Template e rendering

md_gridview_template: template rendering list. Client: override layout griglia. Server: invariato.
md_rowTemplate: template riga. Client: rendering row custom. Server: invariato.
md_filter_template: template area filtri. Client: UX filtri custom. Server: invariato.
md_detail_template: template dettaglio. Client: rendering detail. Server: invariato.
md_edit_template: template edit. Client: rendering form edit. Server: invariato.
md_ui_grid_conditional_template_condition: condizione template alternativo. Client: classe/template condizionale. Server: invariato.

Sicurezza e audit

md_grant_by_default: default visibilita route. Client: influenza accesso UI combinato con auth. Server: fallback autorizzativo.
md_record_restriction_key_user_field_list: campo/i per record restriction. Client: dati utente nel payload filtro. Server: applica restrizioni per utente/ruolo.
md_user_id_field_name: campo utente proprietario. Client: nessun effetto diretto. Server: filtro ownership.
md_logging_enable: logging attivo. Client: invariato. Server: popola campi audit.
md_logging_*_field_name: mapping campi audit. Client: invisibile salvo colonne esposte. Server: valorizzazione automatica.
md_has_logic_delete: delete logica. Client: stessa UX delete. Server: update flag invece di delete fisico.

`md_props_bag` (extra JSON)

endpoint: override sorgente (odata/webservice/meta). Client: data-provider usa endpoint custom. Server: cambia path I/O.
parameters: parametri dinamici request. Client: mapping da filtri/route/user context. Server: riceve parametri risolti.
archetypes.*: opzioni specifiche archetype (list, map, scheduler, tree, spreadsheet, carousel, chart, form). Client: rendering/behavior specifici. Server: invariato.
groupInfo: grouping client/server. Client: UI gruppi e header aggregati. Server: query group by se richiesto.
aggregates: definizioni aggregati. Client: footer/KPI. Server: select aggregata.
changeTracking: abilita tracciamento modifiche client. Client: dirty-state/pending cue. Server: invariato.
client_side_crud: forza CRUD client-side. Client: buffering/modello locale. Server: sync batch o differita.
queryOptimization.enabled: abilita policy ottimizzazione query. Client: adatta pager/total handling. Server: branch query optimized.
queryOptimization.countPolicy: exact | skipWhenPaged | never | cursor. Client: gestione total pages/next-prev. Server: count strategy/cursor.
queryOptimization.sqlServerHint: none | recompile. Client: nessun impatto. Server: hint SQL (OPTION (RECOMPILE) quando richiesto).

Clone Profondo Con relatedRoutes (cloneDefinition)

Snippet inline: md_props_bag.cloneDefinition.relatedRoutes: [{"relatedRoute":"orders_rows","relatedIdField":"order_id"}].
Runtime client: quando md_clonable = true, il clone passa anche le route correlate a dataSrv.clone(...).
Runtime server: MetaService.CloneRecord riceve relatedRouteToClone e puo clonare padre + figli in un unico flusso.
Uso tipico: ordini + righe ordine, testate + dettagli, wizard master/detail.

Parametri Dinamici Route (parameters + customizationCallback)

Snippet inline: md_props_bag.parameters: [{"Name":"lang","Type":"string","enabled":true,"value":"{{currentUser.lingua.id}}","customizationCallback":"param.mc_show_in_filters=true;"}].
Runtime client: i parameters vengono convertiti in parameterInfo (campi filtro runtime) con visibilita/editabilita guidata dal parametro.
Runtime server: i valori risolti entrano nella pipeline route (getFlatRecordData) insieme a filterInfo/sortInfo/pageInfo.
Nota pratica: customizationCallback consente di adattare comportamento campo parametro senza hardcode frontend.

Lookup Assistito Nel Metadata-editor

Flusso inline consigliato: suggestLookup2 -> suggestLookupDefaultFilter -> getLookupListByRoute/getSeletClauseByLookupHierarchy.
Runtime client: l'editor contestuale compila in automatico i principali mc_ui_lookup_* e propone filtri/coerenza gerarchica.
Runtime server: i suggerimenti si appoggiano agli endpoint MetaService.* per route lookup e select clause.
Per il dettaglio widget lookup vedi Widget Lookup; per codice contestuale lookup/TS vedi Widget Code Editor.
Per lo scenario notifiche metadata-driven vedi anche Notifications (nodo md_props_bag.notifications.triggerRules).

Metadati Colonna (`_metadati__colonne`)

Identita e presentazione

mc_nome_colonna: nome logico campo. Client: binding field in editor/grid/filter. Server: mapping select/update field.
mc_real_column_name: nome fisico DB. Client: normalmente trasparente. Server: mapping SQL reale.
mc_display_string_in_view: caption in lista. Client: header colonna. Server: nessun impatto diretto.
mc_display_string_in_edit: caption in form. Client: label editor. Server: nessun impatto diretto.
mc_ordine: ordine visualizzazione. Client: ordine campi/colonne. Server: ordinamento metadata.
mc_ui_column_type: tipo editor (text, number_*, date, datetime, lookupByID, upload, button, ecc.). Client: selezione widget editor/view. Server: semantica parsing/filtri.

Visibilita e comportamento

mc_hide_in_list: nasconde in grid. Client: colonna non renderizzata. Server: puo restare in query se necessario.
mc_hide_in_edit: nasconde in form edit. Client: campo non editabile via form. Server: possibile update da callback.
mc_hide_in_detail: nasconde in dettaglio. Client: invisibile in detail. Server: invariato.
mc_hide_in_export: esclude export. Client: export senza campo. Server: select export filtrata.
mc_hide_in_service: esclude da servizi esposti. Client: invariato. Server: serializzazione API ridotta.
mc_show_in_filters: mostra filtro UI. Client: campo appare filter bar. Server: abilita criteria su colonna.
mc_disable_sorting: disabilita sort colonna. Client: header non ordinabile. Server: blocco ORDER BY su campo.

Validazione e default

mc_default_value: default statico. Client: prefill su insert. Server: fallback in assenza valore.
mc_default_value_callback: default dinamico. Client: esegue callback lato runtime. Server: nessun effetto diretto.
mc_validation_required: obbligatorieta. Client: errore prima save. Server: validazione ulteriore se prevista.
mc_validation_type: tipo validazione (email, url, ...). Client: regole standard validation. Server: non obbligatorio, dipende endpoint.
mc_validation_pattern: regex custom. Client: controllo pattern. Server: opzionale.
mc_validation_custom_callback: callback custom. Client: validation logic custom. Server: invariato.

Lookup e relazioni

mc_ui_lookup_entity_name: route metadata lookup. Client: datasource lookup. Server: join/expand lookup quando richiesto.
mc_ui_lookup_dataValueField: campo id lookup. Client: value binding. Server: filtro/relazione id.
mc_ui_lookup_dataTextField: campo descrizione lookup. Client: testo combo/grid. Server: select testo lookup.
mc_ui_lookup_filter: filtro lookup base. Client: restringe opzioni combo. Server: WHERE su route lookup.
mc_serverside_operations: operazioni lookup server-side. Client: ricerca paginata. Server: paging/filter on-demand lookup.
mc_ui_pagesize: page size lookup. Client: size pagina combo lookup. Server: limit query lookup.
mc_logic_allow_navigation: abilita link da cella a route correlata. Client: anchor clickable. Server: invariato.

Logica custom e performance

mc_suggest_value_callback: callback suggest. Client: popolamento suggest/input helper. Server: eseguito nel runtime callback pipeline.
mc_selection_changing_custom_function: hook pre-change. Client: intercetta cambio valore prima commit. Server: invariato.
mc_selection_changed_custom_function: hook post-change. Client: reazioni a cascata lato form. Server: invariato.
mc_logic_converter_read_callback: converter in lettura. Client: format/normalizzazione valore. Server: invariato.
mc_logic_converter_write_callback: converter in scrittura. Client: trasformazione prima save. Server: payload normalizzato.
mc_custom_select_clause: select custom. Client: richiede gestione rendering coerente. Server: modifica select SQL.
mc_custom_join: join custom. Client: espande dati disponibili. Server: modifica FROM/JOIN query.
mc_props_bag: extra configurazione campo. Client: editor avanzati/schema json/suggest. Server: supporto regole custom.

Upload e button

isImageUpload, isDBUpload, isMultipleUpload: strategia upload. Client: widget upload preview/multi file. Server: persistenza blob/path.
allowed_file_types, max_file_size: limiti upload. Client: validazione file pre-upload. Server: validazione finale.
customUploadHandlerPath: handler upload custom. Client: endpoint custom. Server: pipeline upload dedicata.
mc_button_caption: label bottone custom column-type. Client: caption action button. Server: invariato.
mc_button_action: callback azione bottone. Client: esecuzione azione su click. Server: eventuale chiamata API custom.
mc_button_visibility_condition: visibilita condizionale bottone. Client: show/hide action per record. Server: invariato.

Menu Metadata (`_metadati__menu`)

Proprieta principali

mm_id: id voce menu. Client: tree/menu identity e DnD ordering. Server: PK update/reorder/nest/remove.
mm_parent_id: parent menu. Client: struttura gerarchica. Server: nesting persistito.
mm_ordine: ordine visuale. Client: menu order deterministico. Server: update reorder.
mm_display_string_menu: label UI. Client: testo voce menu. Server: metadato presentazione.
mm_uri_menu: route/url associata. Client: navigazione hash route. Server: nessun SQL diretto.
md_id: collegamento a route metadata. Client: relazione menu->feature. Server: usato anche in controlli autorizzativi route.
mm_is_visible_by_default: visibilita default. Client: voce visibile salvo restrizioni. Server: fallback se manca regola specifica.
mm_icon: icona menu. Client: rendering icona. Server: metadato presentazione.
mm_props_bag: estensioni JSON menu. Client: behavior custom menu. Server: opzionale.

Azioni Custom Tabella (`_Metadati_Custom_Actions_Tabelle`)

Id: id azione. Client: chiave menu/action list. Server: PK.
md_id: tabella target. Client: azioni legate alla route corrente. Server: filtro per route metadata.
button_caption: testo bottone. Client: label action toolbar/row. Server: metadato presentazione.
button_template: template bottone. Client: rendering custom action. Server: invariato.
button_image: icona/immagine bottone. Client: UI iconografia. Server: invariato.
tooltip: hint azione. Client: hover help. Server: invariato.
action_callback: callback esecuzione. Client: invocata su click. Server: puo innescare chiamate endpoint.
disable_callback: callback abilitazione. Client: enable/disable dinamico. Server: invariato.
md_action_type: tipo azione (toolbar/row/contesto). Client: posizione azione. Server: mapping funzionale. Valori supportati dal suggester (MetaService.suggestTableActionCallback):

- 0 navigation, 1 method.call (AsmxProxy), 2 generate.file, 3 export (xls/pdf), 4 call.stored,

- 5 approve, 6 parametric.dialog, 7 client sync, 8 client async, 9 show route payload,

- 10 upload — apre un file picker (XLS/XLSX/CSV), il backend (UploadHandlerCustom + metaQuery.UploadToDynamicTable) crea/popola una tabella SQL con colonne dinamiche derivate dagli header del file, poi esegue una stored procedure passando @TableName, @UserId, @RowCount. Parametri suggester: target_table (nome tabella SQL), target_stored (nome stored), target_mode (replace = DROP + CREATE + INSERT, default; truncate = CREATE IF NOT EXISTS + TRUNCATE + INSERT; append = CREATE IF NOT EXISTS + INSERT).

ordine: priorita visuale. Client: ordering azioni. Server: persistenza ordine.

Autorizzazioni Tabella (`_Metadati_Utenti_Autorizzazioni_Tabelle`)

muat_id: id regola. Client: selezione/edit regola. Server: PK.
md_id: tabella target. Client: scope route corrente. Server: filtro regole.
ruolo_id: ruolo target. Client: regola per ruolo. Server: enforcement by role.
utente_id: utente target. Client: override per utente. Server: enforcement by user.
muat_view: permesso visualizzazione. Client: route/menu nascosti se negato. Server: blocco accesso dati.
muat_edit: permesso modifica. Client: pulsanti edit disabilitati/nascosti. Server: blocco update.
muat_insert: permesso inserimento. Client: hide add/new. Server: blocco insert.
muat_delete: permesso cancellazione. Client: hide delete. Server: blocco delete.
muat_override_record_restriction: override record restriction. Client: puo cambiare visibilita dataset. Server: bypass restrizioni record-level.

Autorizzazioni Colonna (`_Metadati_Utenti_Autorizzazioni_Colonne`)

muac_id: id regola. Client: selezione/edit regola. Server: PK.
mc_id: colonna target. Client: scope field-level. Server: filtro permessi campo.
ruolo_id: ruolo target. Client: policy per ruolo. Server: enforcement campo.
utente_id: utente target. Client: override utente. Server: enforcement utente.
muac_editable: editabilita campo. Client: field readonly/disabled. Server: hardening update campo.
muac_validation_required: required override. Client: validazione campo contestuale. Server: coerenza semantica dati.

Stili Tabella (`_Metadati_UI_Stili_Tabelle`)

must_id: id regola stile. Client: tracking regola. Server: PK.
md_id: tabella target. Client: scope grid route. Server: filtro regole route.
must_attribute_name: classe CSS da applicare. Client: classe aggiunta alla riga. Server: metadato.
must_attribute_value: callback/condizione JS che ritorna boolean. Client: decide se applicare la classe. Server: metadato (no valutazione SQL).

Stili Colonna (`_Metadati_UI_Stili_Colonne`)

musc_id: id regola stile colonna. Client: tracking regola. Server: PK.
musc_attribute_name: classe/attributo stile. Client: stile cella/colonna. Server: metadato.
musc_attribute_value: valore statico. Client: applicazione diretta stile/attributo. Server: metadato.
musc_attribute_value_callback: callback dinamico. Client: stile condizionale per record/cella. Server: metadato.

Condition Groups / Items / Actions

CG_Id: gruppo condizione. Client: cluster logico regole. Server: struttura metadati condizionali.
CI_Id: singola condizione. Client: valutazione runtime formula/operatore. Server: usata in policy di business.
CAG_Id: gruppo azioni condizionali. Client: bucket azioni collegate a condizioni. Server: orchestrazione esecuzione.
CAI_Id: action item. Client: trigger azioni runtime. Server: puo influire su update/flow lato API.
FK_*: chiavi di relazione tra group/item/action. Client: navigazione coerente nell’editor. Server: integrita relazionale metadata.

Effetti Trasversali Client/Server

Client:
rendering dinamico componenti (list, form, map, chart, ecc.) da metadata.
abilitazioni/disabilitazioni UI coerenti con autorizzazioni.
validazioni e callback custom in edit/filter/grid.