Overview

Metadata

Operational guide to the framework metadata with focus on client-side and server-side application effects.

Scope

Types covered: table, column, menu, custom actions, table/column authorizations, table/column styles, condition groups.
UI origin: forms opened from the metadata-editor (menus Metadati and Metadati correlati).
Runtime transport: MetaService.* endpoints via AsmxProxy.

Screenshot Reference (Metadata Editor)

metadata-editor-table: table metadata form.
metadata-editor-columns: column metadata form (insert/edit).
metadata-editor-custom-actions: table custom actions form.
metadata-editor-auth-table: table authorizations form.
metadata-editor-auth-column: column authorizations form.
metadata-editor-styles-table: table styles form.
metadata-editor-styles-column: column styles form.
metadata-editor-condition-groups: condition groups form.
metadata-menu-management: metadata menu management list.

Runtime Flow

MetaService.getTableMetadata: loads table + columns + metadata relations.
MetaService.getFlatRecordData: uses metadata to compose queries, filters, sorting, and paging.

Contextual Metadata-editor

The contextual metadata-editor allows you to quickly open and edit metadata directly from the operating context (current grid/form/action), without having to manually navigate through all the technical routes of the metadata menu.

Goal: reduce the number of steps for targeted interventions on table, column, and related configurations.
Practical advantage: the focus stays on the entity in use, with quick access to the most frequent options.
Recommended use: incremental maintenance during functional testing and UI/runtime tuning.

Reference Screenshots

manual__metadata_context_editor__01.png: opening the contextual editor and quick access to metadata sections.
manual__metadata_context_editor__02.png: operational detail of the contextual flow with guided editing.

Table Metadata (`_metadati__tabelle`)

Routing and storage

md_route_name: datasource logical route. Client: builds URL/hash route and datasource binding. Server: metadata/table lookup and query generation.
md_nome_tabella: physical table/view name. Client: transparent in UI. Server: main SQL target.
md_schema_name: DB schema. Client: no direct impact. Server: qualifies the SQL object.
md_conn_name: metadata connection name. Client: no direct impact. Server: connection selection (e.g. DataSQLConnection).
md_db_name: target database. Client: no direct impact. Server: query/scaffolding routing.

CRUD operations and UI

md_editable: enables record editing. Client: edit buttons/modal. Server: update logic gate.
md_insertable: enables record insertion. Client: add button/insert form. Server: insert logic gate.
md_deletable: enables record deletion. Client: delete command visible/usable. Server: delete logic gate.
md_detail_action: enables detail view. Client: detail action in grid. Server: no direct SQL effect.
md_clonable: enables cloning. Client: clone button. Server: clone logic + optional cloneDefinition.
md_inline_edit: inline editing in grid. Client: cell/row editor. Server: same sync/update pipeline.
md_edit_popup: edit in popup. Client: UX choice modal vs inline. Server: unchanged.

Query, filters, paging

md_server_side_operations: delegates sorting/filtering/paging to the server. Client: sends FilterInfo, SortInfo, PageInfo. Server: composes dynamic query.
md_pageable: enables pagination. Client: pager active. Server: applies limit/offset or cursor policy.
md_pagesize: default page size. Client: pager initial value. Server: TOP/OFFSET or batch cursor.
md_sortable: enables sorting in UI. Client: sortable headers. Server: ORDER BY only if requested/allowed.
md_default_filter: initial filter. Client: preloads filter. Server: merges into WHERE clause.
md_disabilita_filtri: disables filter panel. Client: hides filter bar. Server: reduces available runtime filters.
md_show_record_count: requests total record count. Client: page X of Y. Server: COUNT(*) (or alternative policy via props bag).

Templates and rendering

md_gridview_template: list rendering template. Client: grid layout override. Server: unchanged.
md_rowTemplate: row template. Client: custom row rendering. Server: unchanged.
md_filter_template: filter area template. Client: custom filter UX. Server: unchanged.
md_detail_template: detail template. Client: detail rendering. Server: unchanged.
md_edit_template: edit template. Client: edit form rendering. Server: unchanged.
md_ui_grid_conditional_template_condition: alternative template condition. Client: conditional class/template. Server: unchanged.

Security and audit

md_grant_by_default: default route visibility. Client: influences UI access combined with auth. Server: authorization fallback.
md_record_restriction_key_user_field_list: field(s) for record restriction. Client: user data in filter payload. Server: applies restrictions by user/role.
md_user_id_field_name: owner user field. Client: no direct effect. Server: ownership filter.
md_logging_enable: logging active. Client: unchanged. Server: populates audit fields.
md_logging_*_field_name: audit field mapping. Client: invisible unless columns are exposed. Server: automatic value population.
md_has_logic_delete: logical delete. Client: same delete UX. Server: flag update instead of physical delete.

`md_props_bag` (extra JSON)

endpoint: source override (odata/webservice/meta). Client: data-provider uses custom endpoint. Server: changes I/O path.
parameters: dynamic request parameters. Client: mapping from filters/route/user context. Server: receives resolved parameters.
archetypes.*: archetype-specific options (list, map, scheduler, tree, spreadsheet, carousel, chart, form). Client: specific rendering/behavior. Server: unchanged.
groupInfo: client/server grouping. Client: group UI and aggregated headers. Server: GROUP BY query if requested.
aggregates: aggregate definitions. Client: footer/KPI. Server: aggregate select.
changeTracking: enables client-side change tracking. Client: dirty-state/pending cue. Server: unchanged.
client_side_crud: forces client-side CRUD. Client: buffering/local model. Server: batch or deferred sync.
queryOptimization.enabled: enables query optimization policy. Client: adapts pager/total handling. Server: optimized query branch.
queryOptimization.countPolicy: exact | skipWhenPaged | never | cursor. Client: total pages/next-prev handling. Server: count strategy/cursor.
queryOptimization.sqlServerHint: none | recompile. Client: no impact. Server: SQL hint (OPTION (RECOMPILE) when requested).

Deep Clone With relatedRoutes (cloneDefinition)

Inline snippet: md_props_bag.cloneDefinition.relatedRoutes: [{"relatedRoute":"orders_rows","relatedIdField":"order_id"}].
Client runtime: when md_clonable = true, the clone also passes related routes to dataSrv.clone(...).
Server runtime: MetaService.CloneRecord receives relatedRouteToClone and can clone parent + children in a single flow.
Typical use: orders + order rows, headers + details, wizard master/detail.

Dynamic Route Parameters (parameters + customizationCallback)

Inline snippet: md_props_bag.parameters: [{"Name":"lang","Type":"string","enabled":true,"value":"{{currentUser.lingua.id}}","customizationCallback":"param.mc_show_in_filters=true;"}].
Client runtime: parameters are converted to parameterInfo (runtime filter fields) with visibility/editability driven by the parameter.
Server runtime: resolved values enter the route pipeline (getFlatRecordData) along with filterInfo/sortInfo/pageInfo.
Practical note: customizationCallback allows adapting parameter field behavior without frontend hardcoding.

Assisted Lookup in the Metadata-editor

Recommended inline flow: suggestLookup2 -> suggestLookupDefaultFilter -> getLookupListByRoute/getSeletClauseByLookupHierarchy.
Client runtime: the contextual editor automatically populates the main mc_ui_lookup_* fields and suggests filter/hierarchical consistency.
Server runtime: suggestions rely on MetaService.* endpoints for lookup routes and select clauses.
For lookup widget details see Widget Lookup; for contextual lookup/TS code see Widget Code Editor.
For the metadata-driven notification scenario see also Notifications (md_props_bag.notifications.triggerRules node).

Column Metadata (`_metadati__colonne`)

Identity and presentation

mc_nome_colonna: logical field name. Client: field binding in editor/grid/filter. Server: select/update field mapping.
mc_real_column_name: physical DB name. Client: normally transparent. Server: actual SQL mapping.
mc_display_string_in_view: list caption. Client: column header. Server: no direct impact.
mc_display_string_in_edit: form caption. Client: editor label. Server: no direct impact.
mc_ordine: display order. Client: field/column order. Server: metadata ordering.
mc_ui_column_type: editor type (text, number_*, date, datetime, lookupByID, upload, button, etc.). Client: editor/view widget selection. Server: parsing/filter semantics.

Visibility and behavior

mc_hide_in_list: hides in grid. Client: column not rendered. Server: may remain in query if needed.
mc_hide_in_edit: hides in edit form. Client: field not editable via form. Server: possible update from callback.
mc_hide_in_detail: hides in detail. Client: invisible in detail view. Server: unchanged.
mc_hide_in_export: excludes from export. Client: export without field. Server: filtered export select.
mc_hide_in_service: excludes from exposed services. Client: unchanged. Server: reduced API serialization.
mc_show_in_filters: shows filter in UI. Client: field appears in filter bar. Server: enables criteria on column.
mc_disable_sorting: disables column sorting. Client: header not sortable. Server: blocks ORDER BY on field.

Validation and defaults

mc_default_value: static default. Client: prefill on insert. Server: fallback when value is missing.
mc_default_value_callback: dynamic default. Client: executes callback at runtime. Server: no direct effect.
mc_validation_required: required flag. Client: error before save. Server: additional validation if applicable.
mc_validation_type: validation type (email, url, ...). Client: standard validation rules. Server: not mandatory, depends on endpoint.
mc_validation_pattern: custom regex. Client: pattern check. Server: optional.
mc_validation_custom_callback: custom callback. Client: custom validation logic. Server: unchanged.

Lookup and relations

mc_ui_lookup_entity_name: lookup metadata route. Client: lookup datasource. Server: join/expand lookup when requested.
mc_ui_lookup_dataValueField: lookup id field. Client: value binding. Server: id filter/relation.
mc_ui_lookup_dataTextField: lookup description field. Client: combo/grid text. Server: lookup text select.
mc_ui_lookup_filter: base lookup filter. Client: restricts combo options. Server: WHERE on lookup route.
mc_serverside_operations: server-side lookup operations. Client: paginated search. Server: on-demand lookup paging/filter.
mc_ui_pagesize: lookup page size. Client: lookup combo page size. Server: lookup query limit.
mc_logic_allow_navigation: enables link from cell to related route. Client: clickable anchor. Server: unchanged.

Custom logic and performance

mc_suggest_value_callback: suggest callback. Client: populates suggest/input helper. Server: executed in the callback runtime pipeline.
mc_selection_changing_custom_function: pre-change hook. Client: intercepts value change before commit. Server: unchanged.
mc_selection_changed_custom_function: post-change hook. Client: cascading reactions in form. Server: unchanged.
mc_logic_converter_read_callback: read converter. Client: value format/normalization. Server: unchanged.
mc_logic_converter_write_callback: write converter. Client: transformation before save. Server: normalized payload.
mc_custom_select_clause: custom select. Client: requires consistent rendering handling. Server: modifies SQL select.
mc_custom_join: custom join. Client: expands available data. Server: modifies query FROM/JOIN.
mc_props_bag: extra field configuration. Client: advanced editors/JSON schema/suggest. Server: custom rule support.

Upload and button

isImageUpload, isDBUpload, isMultipleUpload: upload strategy. Client: upload widget preview/multi file. Server: blob/path persistence.
allowed_file_types, max_file_size: upload limits. Client: pre-upload file validation. Server: final validation.
customUploadHandlerPath: custom upload handler. Client: custom endpoint. Server: dedicated upload pipeline.
mc_button_caption: custom column-type button label. Client: action button caption. Server: unchanged.
mc_button_action: button action callback. Client: action execution on click. Server: optional custom API call.
mc_button_visibility_condition: conditional button visibility. Client: show/hide action per record. Server: unchanged.

Menu Metadata (`_metadati__menu`)

Main properties

mm_id: menu item id. Client: tree/menu identity and DnD ordering. Server: PK for update/reorder/nest/remove.
mm_parent_id: parent menu. Client: hierarchical structure. Server: persisted nesting.
mm_ordine: visual order. Client: deterministic menu order. Server: reorder update.
mm_display_string_menu: UI label. Client: menu item text. Server: presentation metadata.
mm_uri_menu: associated route/url. Client: hash route navigation. Server: no direct SQL.
md_id: link to metadata route. Client: menu->feature relation. Server: also used in route authorization checks.
mm_is_visible_by_default: default visibility. Client: item visible unless restricted. Server: fallback if no specific rule exists.
mm_icon: menu icon. Client: icon rendering. Server: presentation metadata.
mm_props_bag: menu JSON extensions. Client: custom menu behavior. Server: optional.

Table Custom Actions (`_Metadati_Custom_Actions_Tabelle`)

Id: action id. Client: menu/action list key. Server: PK.
md_id: target table. Client: actions tied to the current route. Server: filter by metadata route.
button_caption: button text. Client: action toolbar/row label. Server: presentation metadata.
button_template: button template. Client: custom action rendering. Server: unchanged.
button_image: button icon/image. Client: UI iconography. Server: unchanged.
tooltip: action hint. Client: hover help. Server: unchanged.
action_callback: execution callback. Client: invoked on click. Server: can trigger endpoint calls.
disable_callback: enable/disable callback. Client: dynamic enable/disable. Server: unchanged.
md_action_type: action type (toolbar/row/context). Client: action position. Server: functional mapping. Values supported by the 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 — opens a file picker (XLS/XLSX/CSV); the backend (UploadHandlerCustom + metaQuery.UploadToDynamicTable) creates/populates a SQL table with dynamic columns derived from the file headers, then runs a stored procedure with @TableName, @UserId, @RowCount. Suggester params: target_table (SQL table name), target_stored (stored name), target_mode (replace = DROP + CREATE + INSERT, default; truncate = CREATE IF NOT EXISTS + TRUNCATE + INSERT; append = CREATE IF NOT EXISTS + INSERT).

ordine: visual priority. Client: action ordering. Server: order persistence.

Table Authorizations (`_Metadati_Utenti_Autorizzazioni_Tabelle`)

muat_id: rule id. Client: rule selection/edit. Server: PK.
md_id: target table. Client: current route scope. Server: rule filter.
ruolo_id: target role. Client: rule per role. Server: enforcement by role.
utente_id: target user. Client: per-user override. Server: enforcement by user.
muat_view: view permission. Client: route/menu hidden if denied. Server: data access block.
muat_edit: edit permission. Client: edit buttons disabled/hidden. Server: update block.
muat_insert: insert permission. Client: hide add/new. Server: insert block.
muat_delete: delete permission. Client: hide delete. Server: delete block.
muat_override_record_restriction: record restriction override. Client: can change dataset visibility. Server: bypasses record-level restrictions.

Column Authorizations (`_Metadati_Utenti_Autorizzazioni_Colonne`)

muac_id: rule id. Client: rule selection/edit. Server: PK.
mc_id: target column. Client: field-level scope. Server: field permission filter.
ruolo_id: target role. Client: per-role policy. Server: field enforcement.
utente_id: target user. Client: per-user override. Server: user enforcement.
muac_editable: field editability. Client: field readonly/disabled. Server: field update hardening.
muac_validation_required: required override. Client: contextual field validation. Server: data semantic consistency.

Table Styles (`_Metadati_UI_Stili_Tabelle`)

must_id: style rule id. Client: rule tracking. Server: PK.
md_id: target table. Client: grid route scope. Server: route rule filter.
must_attribute_name: CSS class to apply. Client: class added to the row. Server: metadata.
must_attribute_value: JS callback/condition that returns a boolean. Client: decides whether to apply the class. Server: metadata (no SQL evaluation).

Column Styles (`_Metadati_UI_Stili_Colonne`)

musc_id: column style rule id. Client: rule tracking. Server: PK.
musc_attribute_name: style class/attribute. Client: cell/column style. Server: metadata.
musc_attribute_value: static value. Client: direct style/attribute application. Server: metadata.
musc_attribute_value_callback: dynamic callback. Client: conditional style per record/cell. Server: metadata.

Condition Groups / Items / Actions

CG_Id: condition group. Client: logical rule cluster. Server: conditional metadata structure.
CI_Id: single condition. Client: runtime formula/operator evaluation. Server: used in business policies.
CAG_Id: conditional action group. Client: action bucket linked to conditions. Server: execution orchestration.
CAI_Id: action item. Client: runtime action triggers. Server: can affect API-side update/flow.
FK_*: relationship keys between group/item/action. Client: consistent navigation in the editor. Server: metadata relational integrity.

Cross-cutting Client/Server Effects

Client:
dynamic component rendering (list, form, map, chart, etc.) from metadata.
UI enable/disable states consistent with authorizations.
custom validations and callbacks in edit/filter/grid.