Le proprietà del controllo
Control
Ogni controllo utilizza la classe astratta Control come base per personalizzare proprietà e comportamenti.
In base al tipo di controllo alcune proprietà sono pertinenti e partecipano al caricamento, alla gestione e al salvataggio dei dati.
Il dato Json viene recuperato dal database attraverso FormStore e processato da FormService per creare un'istanza Form con la collezione Controls di elementi Control declinati nelle varie classi concrete (TextBox, Label, DropDownList e così via).
Ecco il ciclo di vita del form durante la fase di lettura dei dati:
Ed ecco la fase di scrittura:
Le proprietà di Control
Control mette a disposizione delle classi concrete una serie di proprietà mappate sui relativi campi Json. Vediamo quali sono.
| Proprietà | Descrizione |
|---|---|
| Name | Il nome univoco del controllo nel form. |
| Type | Il tipo di controllo. |
| Group | Il gruppo del controllo per applicare eventi cumulativi come nascondere un intero set di controlli. |
Title | Il titolo del controllo localizzato per le culture disponibili nell'istanza DataWeb. Almeno en-US è richiesta. |
| DataField | Il nome del campo nella base dati. |
DataSubField | Se è impostato e il campo DataType è Structured, allora imposta il valore di questo controllo come nodo di una struttura Json e la salva in DataField. |
| DataType | Il tipo di dato per validazione, formattazione, salvataggio e gestione nativa. |
DataSourceMode | Permette di impostare la sorgente dati per i controlli che propongono un elenco di valori, come DropDownList o CheckBoxList. In caso di valore List i dati sono presi da una lista DataWeb; in caso di valore ControlClass i dati sono presi dal metodo implementato nella classe derivata GetListValuesAsync. |
| DataSource | Il nome della sorgente dati. In caso di DataSourceMode List è il nome della lista DataWeb. |
| IsLateDataBinding | Specifica se il recupero dei dati avviene al caricamento del form o solo all'esecuzione di un evento di un altro controllo. Si utilizza per creare caricare dati specifici in base al valore di un controllo precedente. |
DefaultValueMode | Permette di impostare il valore predefinito. In caso di Value i dati sono presi da DefaultValue; in caso di valore ControlClass i dati sono presi dal metodo implementato nella classe derivata GetDefaultValueAsync. |
DefaultValue | Indica in formato stringa il valore predefinito da applicare al controllo quando si crea un nuovo item. |
| IsVersionLinked | Se attivo, al salvataggio il valore del controllo sarà replicato in tutte le versioni dell'item. |
| IsLocalization | Se attivo, abilita la traduzione del valore durante la fase di traduzione automatica |
IsVisible | Specifica se il controllo è visibile o nascosto. |
IsReadOnly | Specifica se il controllo è in sola lettura. |
IsRequired | Specifica se il controllo è richiesto. |
RegularExpression | Permette di impostare una RegEx di validazione del dato. Vale solo per DataType String. |
MaxLength | Permette di impostare una lunghezza massima per il valore. Vale solo per DataType String. |
StylePath | Indica uno stile dedicato per i controli di gestione Html. |
FormName | Specifica il nome del form da utilizzare per i controlli con strutture Json nidificate. |
ListControlNames | Specifica i valori in tabella per i controlli con strutture Json nidificate. |
FileTagName | Specifica il tag per distinguere il file caricato nel repository dei documenti. |
FileTypes | Specifica i tipi di file supportati dal controllo di upload file. |
FileMaxSize | Specifica la dimensione massima in Byte del file caricato con il controllo di upload file. |
FileMaxCount | Indica quanti file possono essere processati contemporanealmente dal controllo di upload file. |
CustomControlComponent | Permette di specificare un componente Vue.js personalizzato per il controllo. |
CustomControlOptions | Permette di specificare delle opzioni personalizzate per il controllo in formato Json. |
ControlClass | Definisce la classe concreta del controllo. Se non viene specificata, viene automaticamente impostata quella di default di Type. |
IsVisibleRoles | Imposta dei permessi di visualizzazione sul controllo in base ai ruoli dell'utente e al valore di VisibleRoles. |
VisibleRoles | Contiene i ruolo abilitati alla visualizzazione del controllo. |
Actions | Contiene le azioni impostate sul controllo come l'aggiornamento dei dati o la navigazione a un'altra sezione. |
Events | Contiene gli eventi impostati sul controllo per cambiare il comportamento (DataSource, IsVisible, IsRequired) di altri controlli dipendenti |
Gli hook di Control
Control mette a disposizione una serie di metodi personalizzabili che vengono eseguiti durante il ciclo di vita del controllo.
| Hook | Descrizione |
|---|---|
GetDefaultValueAsync | Permette di impostare un comportamento personalizzato per il recupero del valore predefinito del controllo. |
| ProcessOnTranslateAsync | Permette di impostare un comportamento personalizzato durante la fase di traduzione automatica del valore |
ProcessOnGetValueAsync | Permette di impostare un comportamento personalizzato durante la fase di recupero del dato. Questo hook consente ad esempio di trasformare un valore prima che venga visualizzato. |
GetListValuesAsync | Permette di impostare un set di dati personalizzato. |
ValidateAsync | Permette di personalizzare la validazione del dato con ad esempio un controllo sulla base dati |
ProcessOnSaveDataAsync | Permette di impostare un comportamento personalizzato durante la fase di salvataggio del dato. Questo hook consente ad esempio di processare un valore prima che venga salvato eventualmente coinvolgendo altri campi per aggiornamenti multipli. |
IsUpdateDataAsync | Indica se il dato è aggiornabile o meno nel database. In caso negativo, il controllo non viene considerato durante la fase di salvataggio del dato. |
ProcessActionAsync | Permette di personalizzare il comportamento all'esecuzione di un'azione lato server sul controllo come l'invio di una notifica o l'esecuzione di un processo. |
I metodi di supporto Control
Questi metodi sono utilizzati nelle implementazioni predefinite degli hook e possono tornare utili nelle versioni personalizzate.
| Metodo | Descrizione |
|---|---|
GetControlDefaultValue | Recupera il valore predefinito dal campo DefaultValue gestendone la conversione nel tipo nativo e la gestione del formato booleano. |
ValidateControlIsRequired | Verifica che il valore sia presente in base al DataType del controllo |
ValidateControlDataType | Valida il formato del dato inserito in modo che rispetti il DataType del controllo |
SanitizeControlValue | Rimuove tutti i tag Html dal valore inserito |
AddActionUpdateData | Aggiunge un'azione di aggiornamento dei dati del controllo |
| AddActionSetNavigation | Aggiunge un'azione di navigazione a una sezione DataWeb |
AddActionSetRemoteAction | Aggiunge un'azione di esecuzione di un'azione lato server |
AddActionSetLocalAction | Aggiunge un'azione di esecuzione di un'azione lato client |
AddEventSetIsVisible | Aggiunge un evento di visibilità per un controllo o per un gruppo di controlli |
AddEventSetIsRequired | Aggiunge un evento di valore richiesto per un controllo o per un gruppo di controlli |
AddEventSetDataSourceParameter | Aggiunge un evento di aggiornamento dati per un controllo o per un gruppo di controlli |