DOCSMarshal /JS

$().dmProfileInsert()

Questo Componente mostra la maschera di inserimento di un profilo.

Il seguente codice mostra come costruire la maschera passandole dei parametri ed ottenerne l'istanza per invocare successivamente dei metodi; 

<div id="container"></div>
<script>
    // costruisco la maschera
    $('#container').dmProfileInsert({
        ...oggetto contenente i parametri...
    });
    // ottengo l'istanza della maschera
    let mask = $('#container').dmProfileInsert('instance');
    ...
    // in un secondo momento, ad esempio rispondendo ad un evento, chiamo un metodo della maschera
    mask.close();
</script>

Elenco parametri

Elenco metodi

Descrizione parametri

archiveAndContinueButtonCaption

Type: String
Default: null

Consente di forzare l'etichetta del bottone "Archive and Continue".

archiveButtonCaption

Type: String
Default: null

Consente di forzare l'etichetta del bottone "Archive".

classTypeExternalId

Type: String
Default: null

Se questo parametro è impostato all'ExternalId di una classe, allora la maschera di inserimento permetterà di inserire un profilo in quella specifica classe.

classTypeId

Type: Int
Default: null

Se questo parametro è impostato all'ID di una classe, allora la maschera di inserimento permetterà di inserire un profilo in quella specifica classe.

customTemplates

Type: List<CustomTemplateOptions>
Default: []

Consente di iniettare nella maschera dei template da utilizzare nei CustomItem.
Ogni oggetto CustomTemplateOptions deve definire le seguenti due proprietà:

  • externalId
    Specifica l'ExternalId di questo template. Questo valore dovrà corrispondere alla proprietà "Template ExernalId" nella configurazione del CustomItem.
  • template
    Specifica una funzione Javascript responsabile del rendering del template.
    Questa funzione verrà chiamata per ogni CustomItem che referenzia questo template tramite il suo ExternalId.
    La funzione può opzionalmente ritornare una stringa, o un elemento HTML, o un elemento jQuery, che verranno inseriti come contenuto del CustomItem. In alternativa la funzione dovrà costruire il contenuto nell'elemento passato come parametro "container".
    La funzione riceve in ingresso un unico parametro con le seguenti proprietà:
    • container
      L'elemento jQuery che conterrà il CustomItem. Il contenuto può essere costruito direttamente in questo oggetto. È garantito che questo oggetto sia figlio della pagina nel momento in cui il template viene invocato.
    • hide
      Un callback che consente di nascondere questa istanza di CustomItem.
    • show
      Un callback che consente di mostrare questa istanza di CustomItem.
    • toggle
      Un callback che consente di mostrare/nascondere questa istanza di CustomItem.
    • id
      Un ID stringa che identifica univocamente questa istanza di CustomItem all'interno della maschera.
    • makeFocusable
      Un callback che consente di rendere il CustomItem capace di ricevere focus.
      Ovvero: se il CustomItem è contenuto in tab non selezionati, allora vengono selezionati tutti i tab così che il CustomItem diventi visibile.
    • mask
      L'istanza della maschera. Tramite questo oggetto è possibile interagire con la maschera utilizzanto la normale API.
    • onDispose
      Consente di registrare un callback che verrà invocato quando il CustomItem verrà distrutto.
    • onMessage
      Consente di registrare un callback che verrà invocato quando viene inviato un messaggio a questo CustomItem.
    • sendMessage
      Consente al CustomItem di inviare messaggi alla maschera.
    • sessionId
      Indica il SessionId da utilizzare per la comunicazione verso le API di DocsMarshal.
    • templateArgument
      Questo oggetto ha il valore che è stato configurato nella proprietà "Args" del CustomItem.
    • templateExternalId
      Indica l'ExternalId utilizzato per referenziare questo template.
    • templateState
      Un oggetto vuoto all'interno del quale è possibile scrivere informazioni che devono persistere al rebuild del CustomItem.

dmAfterInsertRedirect

Type: String
Default: null

Indica che in seguito all'inserimento del profilo deve essere effettuato un redirect all'URL specificato.

dmAfterInsertReturnProfileInfo

Type: Bool
Default: false

Indica che la funzionalità di dmAfterInsertRedirect deve aggiungere ai parametri di GET le informazioni riguardanti i valori dei campi del profilo inserito.
Se questo parametro ha valore "false" allora verrà passato in GET solamente l'ObjectId del profilo inserito.

domainExternalId

Type: String
Default: null

Prevalorizza il campo di sistema Domain del profilo.

domainId

Type: Int
Default: null

Prevalorizza il campo di sistema Domain del profilo.

dynAssExternalId

Type: String
Default: null

Vedi dynAssObjectId.

dynAssId

Type: Guid
Default: null

Vedi dynAssObjectId.

dynAssObjectId

Type: Guid
Default: null

Questo parametro, utilizzato in accoppiata con dynAssId o dynAssExternalId, consente di inserire un profilo in Dynamic Association rispetto al profilo di partenza indicato.
La classe di inserimento sarà la classe di destinazione della Dynamic Association, e tutti i campi di legame configurati nella Dynamic Association saranno automaticamente prevalorizzati.

editableFieldExternalIds

Type: String
Default: null

Indica che solamente alcuni campi devono essere modificabili.
Il valore di questo campo deve essere una stringa con gli ExternalId dei campi concatenati tramite il carattere ";".
Se questo campo viene valorizzato, allora tutti i campi che non compaiono nell'elenco passeranno in modalità sola lettura.

fieldOptions

Type: List<FieldOptions>
Default: []

Indica delle opzioni per modificare il valore, l'apparenza o il comportamento dei campi.
Ogni oggetto FieldOptions può definire le seguenti proprietà:

  • fieldId / fieldExternalId
    Indica su quale campo dovrà operare questa regola.
  • presenterType
    Modifica il Presenter con cui visualizzare il campo.
  • stringSize
    Se il campo è di tipo String, consente di specificare una StringSize più restrittiva.
  • precision
    Se il campo è di tipo Decimal, consente di sovrascriverne la configurazione Precision.
  • scale
    Se il campo è di tipo Decimal, consente di sovrascriverne la configurazione Scale.
  • allowNull
    Sovrascrive la nullabilità del campo.
  • label
    Modifica l'etichetta del campo.
  • readOnly
    Definisce se il campo è in sola lettura.
  • elementId
    Specifica un ID che deve essere impostato all'elemento HTML in cui verrà costruito il campo.
  • value
    Imposta un valore iniziale da dare al campo.
  • properties
    Modifica le Presenter Properties del campo.
    Il valore di questa opzione deve essere un oggetto le cui chiavi sono gli ExternalId delle PresenterProperties da modificare, e i valori sono i valori della relative proprietà.
  • validationRules
    Un array di regole di validazione da applicare a questo campo.
    Vedi la relativa documentazione.

focusOnLoad

Type: Bool
Default: true

Indica che il focus deve essere portato al primo campo della maschera non appena la maschera viene aperta.

hideMaskAfterComplete

Type: Bool
Default: true

Indica se la maschera deve essere distrutta in seguito al submit della maschera.
Se questa proprietà ha valore "false" allora la maschera rimarrà aperta in seguito al submit e conserverà tutti i valori inseriti, consentendo immediatamente di eseguire un altro submit.

idMask

Type: Guid
Default: null

Indica l'ID della maschera aggiuntiva da utilizzare.

idTaskOperation

Type: Guid
Default: null

Se questo parametro è impostato all'ID di una TaskOperation allora la maschera visualizzata sarà costruita sulla base della configurazione della task operation.

insertCompletedMessage

Type: String
Default: null

Indica un messaggio che deve essere mostrato all'utente dopo che l'inserimento è stato eseguito con successo.

insertCompletedMessageFieldExternalId

Type: String
Default: null

Vedi insertCompletedMessageObjectId

insertCompletedMessageObjectId

Type: Guid
Default: null

Indica un messaggio che deve essere mostrato all'utente dopo che l'inserimento è stato eseguito con successo.
Il testo del messaggio verrà recuperato dal profilo indicato da questo ObjectId, leggendo il campo il cui ExternalId è indicato da insertCompletedMessageFieldExternalId

interfaceLanguageCode

Type: String
Default: null

Consente di forzare la lingua utilizzata per la scelta dei language labels dei campi.

interfaceLanguageId

Type: Int
Default: null

Consente di forzare la lingua utilizzata per la scelta dei language labels dei campi.

languageCode

Type: String
Default: null

Prevalorizza il campo di sistema Language del profilo. Utilizzabile solamente se la classe corrente ha il flag ManageContentByLanguage.

languageId

Type: Int
Default: null

Prevalorizza il campo di sistema Language del profilo. Utilizzabile solamente se la classe corrente ha il flag ManageContentByLanguage.

maskExternalId

Type: String
Default: null

Indica l'ExternalId della maschera aggiuntiva da utilizzare.

objectIdToClone

Type: Guid
Default: null

Se questo parametro è impostato all'ObjectId di un profilo esistente allora la maschera visualizzata farà inserire un "clone" di quel profilo, ovvero l'inserimento verrà fatto nella stessa classe e tutti i campi saranno prevalorizzati con gli stessi valori del profilo indicato.

objectStateExternalId

Type: String
Default: null

Prevalorizza il campo di sistema ObjectState del profilo.

objectStateId

Type: Int
Default: null

Prevalorizza il campo di sistema ObjectState del profilo.

onAfterInsert

Type: Function

Questo evento viene invocato dopo che è stato eseguito l'inserimento del profilo.
Questo evento è asincrono: è possibile ritornare una promessa dal callback, e l'elaborazione non proseguirà fino a che la promessa non è stata risolta.

Al callback viene passato un oggetto con le seguenti proprietà:

  • mask
    L'istanza della maschera.
  • objectId
    L'ObjectId del profilo inserito.
  • protocolCode
    Il ProtocolCode del profilo inserito. Questo campo è valorizzato solamente se la classe in cui si è fatto inserimento ha configurato un Automatic Register.
  • isArchiveAndContinue
    Un booleano che consente di distinguere le operazioni di "Archive" dalle operazioni di "Archive and Continue".

onBeforeInsert

Type: Function

Questo evento viene invocato prima che venga eseguito l'insert del profilo.
Questo evento è asincrono: è possibile ritornare una promessa dal callback, e il profilo non verrà inserito fino a che la promessa non è stata risolta.
Questo evento è cancellabile: ritornando il valore "false" dal callback è possibile bloccare il comportamento di default del componente, ovvero l'inserimento del profilo.

Al callback viene passato un oggetto con le seguenti proprietà:

  • mask
    L'istanza della maschera.

onContentReady

Type: Function

Questo evento viene invocato quando la maschera ha terminato di costruire il proprio contenuto. Da questo momento in poi la maschera è pronta all'utilizzo, ed è concesso accedere a tutte le sue API.

Al callback viene passato un oggetto con le seguenti proprietà:

  • mask
    L'istanza della maschera.

onCustomButtonClick

Type: Function

Questo evento viene invocato quando viene cliccato un Custom Button.

Al callback viene passato un oggetto con le seguenti proprietà:

  • mask
    L'istanza della maschera.
  • event
    L'istanza del DOM Event che ha causato questo evento.
    Tramite questa proprietà è possibile capire ad esempio le coordinate del mouse, o se era premuto il bottone CTRL.
  • button
    Un oggetto che rappresenta i metadati del Custom Button premuto. Tramite questo oggetto è possibile capire esattamente quale bottone è stato premuto, e comportarsi di conseguenza.
    Questo oggetto ha le seguenti proprietà: id, externalId, label, alignment

onError

Type: Function

Questo evento viene invocato quando si verifica un'eccezione nel funzionamento della maschera, ad esempio nel caricamento della maschera o nel salvataggio del profilo.
Questo evento è cancellabile: ritornando il valore "false" dal callback è possibile bloccare il comportamento di default del componente, ovvero la visualizzazione di un alert di errore.

Al callback viene passato un oggetto con le seguenti proprietà:

  • mask
    L'istanza della maschera.
  • error
    Una istanza di Error o una stringa che descrive l'errore verificatosi.

onFieldValueChanged

Type: Function

Questo evento viene invocato quando viene modificato il valore di un campo.
Alcuni esempi di situazioni che possono causare lo scatenamento di questo evento sono le seguenti:

  • L'utente ha modificato un campo tramite il relativo presenter
  • È stato modificato il valore di un campo tramite API o tramite EZ
  • Una formula di valore ha aggiornato il valore di un campo
  • È stato settato il valore di un campo tramite il parametro fieldOptions
  • È stata eseguita una source association

Al callback viene passato un oggetto con le seguenti proprietà:
  • mask
    L'istanza della maschera.
  • field
    Un oggetto che rappresenta i metadati del campo modificato (Id, ExternalId, FieldType, PresenterType, AllowNull, ...).
  • value
    Il nuovo valore del campo.
  • previousValue
    Il valore che il campo aveva prima della modifica.

onMessage

Type: Function

Questo evento viene invocato quando viene lanciato un messaggio nel sistema di messaggi della maschera.
È possibile utilizzare il sistema dei messaggi per consentire ai Custom Item di comunicare tra di loro oppure con EZ. Tramite questo evento anche del codice custom può intercettare i messaggi lanciati dei Custom Item.
Al callback viene passato un oggetto con le seguenti proprietà:

  • mask
    L'istanza della maschera.
  • type
    Il tipo di evento.
  • data
    Degli eventuali dati aggiuntivi associati all'evento.
  • sender
    Se il messaggio è stato inviato da un Custom Item, allora questa proprietà indica l'ID di quel Custom Item.

popup

Type: Bool
Default: false

Se il parametro ha valore "true" allora la maschera verrà mostrata in un popup.
Se il parametro ha valore "false" allora la maschera verrà costruita all'interno del contenitore indicato dal contesto jQuery.

popupOptions

Type: PopupOptions
Default: null

Consente di personalizzare la dimensione, posizione e comportamento del popup all'interno del quale la maschera verrà visualizzata. Questo parametro ha effetto solamente se popup ha valore "true".

requiredMark

Type: String
Default: *

Indica quale è il carattere (o stringa) che contrassegna i campi obbligatori (showRequiredMark).

sessionId

Type: Guid
Default: null

Indica il SessionId della sessione da utilizzare per autenticarsi a DocsMarshal.

showArchiveAndContinueButton

Type: Bool
Default: true

Indica se mostrare il bottone "Archive and Continue", che consente di inserire il profilo corrente e aprire immediatamente la maschera di update del profilo inserito.

showRequiredMark

Type: Bool
Default: true

Indica se i campi obbligatori devono essere contrassegnati da un apposito carattere (requiredMark).

useLabelsFromLayout

Type: Bool
Default: false

Indica che le etichette dei campi devono essere quelle definite manualmente nel layout della maschera. Questo flag disabilita la funzionalità dei Language Labels.

validators

Type: List<ValidatorConfig>
Default: []

Definisce dei validatori per la maschera.
Vedi la relativa documentazione.
Se la validazione deve essere fatta su un singolo campo, è consigliato utilizzare il parametro "validationRules" in fieldOptions.

Descrizione metodi, parametri e valori di ritorno

mask.addValidatorToFieldByExternalId(externalId, rule)

Consente di aggiungere dinamicamente una Validation Rule ad un campo.

Il parametro externalId indica l'ExternalId del campo a cui aggiungere la Validation Rule.
Il parametro rule indica la Validation Rule. Consultare la documentazione per il parametro fieldOptions.validationRules per i dettagli sulla struttura dell'oggetto.

mask.addValidatorToFieldById(id, rule)

Consente di aggiungere dinamicamente una Validation Rule ad un campo.

Il parametro id indica l'Id del campo a cui aggiungere la Validation Rule.
Il parametro rule indica la Validation Rule. Consultare la documentazione per il parametro fieldOptions.validationRules per i dettagli sulla struttura dell'oggetto.

mask.addValidatorToMask(options)

Consente di aggiungere dinamicamente un validator alla maschera.

Il parametro options indica le opzioni del Validator. Consultare la documentazione per il parametro validators per i dettagli sulla struttura dell'oggetto.

mask.close()

Chiude la maschera.
Se la maschera era aperta in un popup allora il popup verrà chiuso, altrimenti tutto il contenuto della maschera verrà distrutto e il contenitore verrà lasciato vuoto.

mask.endLoading()

Nasconde l'indicatore di caricamento custom.

mask.focusFirstField()

Porta il focus sul primo campo della maschera che può ricevere il focus.

await mask.focusFieldByExternalId(externalId)

Porta il focus su un campo.

Il parametro externalId indica l'ExternalId del campo su cui spostare il focus.

await mask.focusFieldById(id)

Porta il focus su un campo.

Il parametro id indica l'Id del campo su cui spostare il focus.

await mask.focusItemById(id)

Porta il focus su un mask item.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

mask.getDomain()

Ritorna un oggetto che rappresenta il Dominio correntemente selezionato.
L'oggetto ritornato contiene le seguenti proprietà: Id, Name, ExternalId.

mask.getFieldAllowNullByExternalId(externalId)

Questa funzione ritorna un booleano che indica se il campo specificato accetta il valore nullo.
Il valore ritornato tiene conto di eventuali modifiche a runtime apportate tramite API.

Il parametro externalId indica l'ExternalId del campo.

mask.getFieldAllowNullById(id)

Questa funzione ritorna un booleano che indica se il campo specificato accetta il valore nullo.
Il valore ritornato tiene conto di eventuali modifiche a runtime apportate tramite API.

Il parametro id indica l'Id del campo.

await mask.getFieldDataSourceValueById(id, valueMemberValue, colName)

Qualora il campo abbia un presenter con una DataSource, questo metodo consente di leggere singoli valori dalla DataSource configurata sul campo.
I requisiti per l'utilizzo di questo metodo sono che il campo abbia configurata una DataSource ed un ValueMember. Non è necessario che il campo sia visibile in maschera.
Questo metodo può essere utilizzato anche per leggere colonne della DataSource che non vengono mostrate dal presenter.

Ad esempio:
ipotizziamo che sul campo di tipo Guid RefIdCliente è impostato un presenter ComboBox con una DataSource "Elenco Clienti" che ha le colonne ObjectId, RagioneSociale e PIVA. Il ValueMember è la colonna ObjectId, mentre il DisplayMember è la colonne RagioneSociale.
Il metodo getFieldDataSourceValueById consente di accedere anche alla colonna PIVA del cliente selezionato o di un qualsiasi altro cliente presente nella data source.

Il parametro id indica l'Id del campo su cui è configurata la Data Source.
Il parametro valueMemberValue serve per identificare la "riga" desiderata della DataSource, quindi deve essere il valore del ValueMember per quella riga.
Il parametro colName serve per identificare la "colonna" desiderata della DataSource, quindi deve essere il nome della colonna come configurato nella DataSource.

await mask.getFieldDataSourceValueByExternalId(externalId, valueMemberValue, colName)

Qualora il campo abbia un presenter con una DataSource, questo metodo consente di leggere singoli valori dalla DataSource configurata sul campo.
I requisiti per l'utilizzo di questo metodo sono che il campo abbia configurata una DataSource ed un ValueMember. Non è necessario che il campo sia visibile in maschera.
Questo metodo può essere utilizzato anche per leggere colonne della DataSource che non vengono mostrate dal presenter.

Ad esempio:
ipotizziamo che sul campo di tipo Guid RefIdCliente è impostato un presenter ComboBox con una DataSource "Elenco Clienti" che ha le colonne ObjectId, RagioneSociale e PIVA. Il ValueMember è la colonna ObjectId, mentre il DisplayMember è la colonne RagioneSociale.
Il metodo getFieldDataSourceValueByExternalId consente di accedere anche alla colonna PIVA del cliente selezionato o di un qualsiasi altro cliente presente nella data source.

Il parametro externalId indica l'ExternalId del campo su cui è configurata la Data Source.
Il parametro valueMemberValue serve per identificare la "riga" desiderata della DataSource, quindi deve essere il valore del ValueMember per quella riga.
Il parametro colName serve per identificare la "colonna" desiderata della DataSource, quindi deve essere il nome della colonna come configurato nella DataSource.

mask.getFieldValueByExternalId(externalId)

Legge il valore di un campo.

Il parametro externalId indica l'ExternalId del campo.

Attenzione: se è utilizzata la funzionalità loadOnlyVisibleFields allora la maschera non conosce il valore di tutti i campi. Se è necessario accedere al valore di un campo che non è in maschera, allora se ne può forzare il caricamento tramite i parametri fieldIdsToLoad e fieldExternalIdsToLoad.

Il valore ritornato è correttamente tipicizzato in base al FieldType con i seguenti casi limite, dovuti alla mancanza di un opportuno tipo dati nativo in Javascript:

  • Se il campo è di tipo MultiLanguage allora il valore è un array di oggetti in cui, per ogni lingua, vengono riportati i seguenti campi: code (il LanguageCode), id (il LanguageId), name (il LanguageName) e value (il valore di questo campo per questa lingua);
  • Se il campo è di tipo ByteArray allora il valore è un oggetto che descrive il file contenuto.

mask.getFieldValueById(id)

Legge il valore di un campo.

Il parametro id indica l'Id del campo.

Attenzione: se è utilizzata la funzionalità loadOnlyVisibleFields allora la maschera non conosce il valore di tutti i campi. Se è necessario accedere al valore di un campo che non è in maschera, allora se ne può forzare il caricamento tramite i parametri fieldIdsToLoad e fieldExternalIdsToLoad.

Il valore ritornato è correttamente tipicizzato in base al FieldType con i seguenti casi limite, dovuti alla mancanza di un opportuno tipo dati nativo in Javascript:

  • Se il campo è di tipo MultiLanguage allora il valore è un array di oggetti in cui, per ogni lingua, vengono riportati i seguenti campi: code (il LanguageCode), id (il LanguageId), name (il LanguageName) e value (il valore di questo campo per questa lingua);
  • Se il campo è di tipo ByteArray allora il valore è un oggetto che descrive il file contenuto.

await mask.getFieldValueDisplayMemberByExternalId(externalId)

Qualora il campo abbia un presenter con un DisplayMember, questo metodo consente di ritornare il valore del DisplayMember per il valore correntemente selezionato nel campo.
I requisiti per l'utilizzo di questo metodo sono che il campo abbia configurata una DataSource ed un DisplayMember . Non è necessario che il campo sia visibile in maschera.

Ad esempio:
se sul campo di tipo Guid RefIdCliente è impostato un presenter ComboBox il cui ValueMember è ObjectId e il cui DisplayMember è RagioneSociale, allora utilizzando il metodo getFieldValueDisplayMemberByExternalId è possibile leggere la Ragione Sociale del cliente selezionato.
Leggendo il valore del campo utilizzando getFieldValueByExternalId invece si leggerebbe l'ObjectId del cliente selezionato.

Il parametro externalId indica l'ExternalId del campo.

await mask.getFieldValueDisplayMemberById(id)

Qualora il campo abbia un presenter con un DisplayMember, questo metodo consente di ritornare il valore del DisplayMember per il valore correntemente selezionato nel campo.
I requisiti per l'utilizzo di questo metodo sono che il campo abbia configurata una DataSource ed un DisplayMember . Non è necessario che il campo sia visibile in maschera.

Ad esempio:
se sul campo di tipo Guid RefIdCliente è impostato un presenter ComboBox il cui ValueMember è ObjectId e il cui DisplayMember è RagioneSociale, allora utilizzando il metodo getFieldValueDisplayMemberById è possibile leggere la Ragione Sociale del cliente selezionato.
Leggendo il valore del campo utilizzando getFieldValueById invece si leggerebbe l'ObjectId del cliente selezionato.

Il parametro id indica l'Id del campo.

await mask.getFieldValueDisplayMembersByExternalId(externalId)

Questo metodo è analogo a getFieldValueDisplayMemberByExternalId, con l'unica differenza che qualora il campo abbia valori multipli (ComboBox Token, ComboBox CheckBox, ...) allora questo metodo ritorna un array contenente tutti i Display Member.

await mask.getFieldValueDisplayMembersById(id)

Questo metodo è analogo a getFieldValueDisplayMemberById, con l'unica differenza che qualora il campo abbia valori multipli (ComboBox Token, ComboBox CheckBox, ...) allora questo metodo ritorna un array contenente tutti i Display Member.

mask.getItemAllowNullById(id)

Questa funzione ritorna un booleano che indica se il mask item specificato accetta il valore nullo.
Il valore ritornato tiene conto di eventuali modifiche a runtime apportate tramite API.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

mask.getItemIdByExternalId(externalId, itemType)

Ricerca un elemento nella maschera in base al suo ExternalId e ne ritorna l'Id.
L'Id può essere poi utilizzato con i metodi di manipolazione della maschera (setItemUrlById, focusItemById, setItemLabelById, toggleItemEnableById, ...).
Il parametro externalId indica l'ExternalId del mask item: può essere l'ExternalId di un campo aggiuntivo, oppure un ExternalId assegnato tramite il MaskDesigner ad un oggetto di maschera come un CustomButton, un Link, ...
Il parametro opzionale itemType consente di ricercare solamente gli elementi del tipo indicato. Il parametro è di tipo stringa e può assumere uno dei seguenti valori:

  • CustomButton
  • CustomItem
  • DynAss
  • Field
  • GroupBox
  • Label
  • LayoutGroup
  • Link
  • ScrollView
  • Separator
  • SubmitButtons
  • TabbedGroup
  • TabNavigation
  • TextBox
  • ValidationSummary
  • RangeSlider

mask.getItemUrlById(id)

Ritorna l'URL a cui sta puntando un Link.
Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

mask.getItemValueById(id)

Ritorna il valore corrente di un mask item.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.
I mask item che consentono la lettura del valore sono i seguenti:
  • TextBox: permette di leggere il valore del Text Box

mask.getMaskType()

Ritorna una stringa rappresentante il tipo di maschera: Insert, Update o View.

mask.getObjectState()

Ritorna un oggetto che rappresenta l'ObjectState correntemente selezionato.
L'oggetto ritornato contiene le seguenti proprietà: Name, ExternalId, Description, Id, AllowForceOverWrite, AllowForceRevision, EnableDocumentVersioning, EnableProfileVersioning, GridBackColor, GridForeColor.

mask.getLanguage()

Ritorna un oggetto che rappresenta la lingua correntemente selezionata.
L'oggetto ritornato contiene le seguenti proprietà: Id, LanguageCode, LanguageName.

mask.getProfileValues(excludeUnchanged)

Ritorna un oggetto che contiene i valori di tutti i campi del profilo.
L'oggetto ritornato ha le seguenti proprietà:
  • objectId
  • classTypeId
  • classTypeExternalId
  • domainId
  • domainExternalId
  • objectStateId
  • objectStateExternalId
  • languageId
  • languageCode
  • fields
La proprietà "fields" è un array di oggetti, uno per ogni campo aggiuntivo, con le seguenti proprietà:
  • id: l'Id del campo
  • externalId: l'ExternalId del campo
  • type: il FieldType del campo
  • presenterType: il PresenterType del campo
  • value: il valore attuale del campo
  • originalValue: il valore originale del campo, prima che venisse modificato tramite l'interfaccia o l'API della maschera
    Questo campo è valorizzato solamente se il valore del campo è stato caricato inizialmente (vedi loadOnlyVisibleFields).

Se il parametro excludeUnchanged ha valore true, allora l'oggetto ritornato conterrà solamente i valori dei campi il cui valore è stato cambiato.
Valore di default: false.

Per effetto del parametro loadOnlyVisibleFields alcuni campi aggiuntivi potrebbero non essere stati caricati.
Nel vettore fields sono presenti solamente i campi che sono stati caricati e i campi il cui valore è stato modificato.

mask.off(eventName, callback)

Annulla l'iscrizione di un callback ad un evento di maschera.

Questo metodo consente di annullare l'iscrizione ad un evento che era stata precedentemente effettuata tramite l'utilizzo del metodo on oppure tramite i parametri dedicati agli eventi (onContentReady, onCustomButtonClick, ...).
Il parametro eventName indica il nome dell'evento da cui annullare l'iscrizione.
Gli eventi disponibili sono i seguenti:

  • afterInsert
  • beforeInsert
  • contentReady
  • customButtonClick
  • error
  • fieldValueChanged
  • itemValueChanged
  • message
Il parametro callback è la funzione Javascript che si desidera non venga più invocata quando l'evento si verifica.

mask.on(eventName, callback)

Registra un callback ad un evento della maschera.
Il parametro eventName indica il nome dell'evento a cui iscriversi.
Gli eventi disponibili sono i seguenti:

  • afterInsert
  • beforeInsert
  • contentReady
  • customButtonClick
  • error
  • fieldValueChanged
  • itemValueChanged
  • message
Il parametro callback è la funzione Javascript che deve essere invocata quando l'evento viene scatenato.

mask.reloadItemDataById(id)

Aggiorna i dati relativi ad un mask item.

I mask item che supportano questa operazione sono i seguenti:

  • Field: se un campo ha un presenter con Data Source (ComboBox, ListView, ...) allora quei dati verranno aggiornati.
  • Dynamic Association: aggiorna il contenuto della griglia.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

mask.resetFieldValues()

Ripristina il valore di tutti i campi al loro valore originale.

await mask.scrollToItemById(id)

Scrolla la maschera fino a rendere visibile il mask item selezionato.
Se il mask item indicato è contenuto in un Tab, allora quel Tab verrà automaticamente selezionato così da rendere visibile l'item.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

mask.sendMessage(sender, target, type, data)

Invia un messaggio nel sistema di messaggi della maschera. Questo metodo permette di comunicare con i custom item e con qualsiasi implementazione custom che si agganci all'evento onMessage.

Il parametro opzionale sender può fungere da ID per identificare univocamente l'entità che sta inviando il messaggio.

Il parametro opzionale target può essere l'ID del mask item a cui inviare il messaggio.
Se questo parametro è valorizzato allora il messaggio sarà inviato solamente a quell'item.
Se questo parametro è nullo allora il messaggio sarà inviato in broadcast e sarà leggibile da chiunque si sia registrato all'evento onMessage.
Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

Il parametro type è una stringa che indica il tipo di messaggio da inviare. Il tipo di messaggio deve rappresentare il tipo di operazione, evento o dato che il messaggio vuole segnalare.

Il parametro data è un qualsiasi dato utile a descrivere in maggiore dettaglio il messaggio che si sta inviando.

mask.setFieldAllowNullByExternalId(externalId, allowNull)

Modifica la nullabilità del campo indicato.

Se il parametro allowNull ha valore true allora il campo sarà nullabile, altrimenti sarà obbligatorio.

Il parametro externalId indica l'ExternalId del campo su cui lavorare.

mask.setFieldAllowNullById(id, allowNull)

Modifica la nullabilità del campo indicato.

Se il parametro allowNull ha valore true allora il campo sarà nullabile, altrimenti sarà obbligatorio.

Il parametro id indica l'Id del campo su cui lavorare.

mask.setFieldValueByExternalId(externalId, value)

Scrive un nuovo valore in un campo.

Il parametro externalId indica l'ExternalId del campo su cui lavorare.

Il parametro value indica il valore da scrivere nel campo.
Si consiglia di tipicizzare nel modo corretto questo parametro, così da evitare errori di conversione. Ad esempio se il campo è di tipo Date o DateTime allora passare un'istanza del tipo Javascript Date.
Esistono le seguenti eccezioni:

  • Se il campo è di tipo MultiLanguage allora è possibile specificare i seguenti valori:
    • Una stringa, oppure null: in questo caso lo stesso valore verrà scritto in tutte le lingue.
    • Un array di oggetti, uno per ogni lingua che si vuole modificare.
      Ogni oggetto dovrà contenere la proprietà id o code per indicare a quale lingua fa riferimento, e dovrà contenere la proprietà value per definire il valore da scrivere in quella lingua.
  • Se il campo è di tipo ByteArray allora l'unico valore accettato è null, che svuota il campo.

mask.setFieldValueById(id, value)

Scrive un nuovo valore in un campo.

Il parametro id indica l'Id del campo su cui lavorare.

Il parametro value indica il valore da scrivere nel campo.
Si consiglia di tipicizzare nel modo corretto questo parametro, così da evitare errori di conversione. Ad esempio se il campo è di tipo Date o DateTime allora passare un'istanza del tipo Javascript Date.
Esistono le seguenti eccezioni:

  • Se il campo è di tipo MultiLanguage allora è possibile specificare i seguenti valori:
    • Una stringa, oppure null: in questo caso lo stesso valore verrà scritto in tutte le lingue.
    • Un array di oggetti, uno per ogni lingua che si vuole modificare.
      Ogni oggetto dovrà contenere la proprietà id o code per indicare a quale lingua fa riferimento, e dovrà contenere la proprietà value per definire il valore da scrivere in quella lingua.
  • Se il campo è di tipo ByteArray allora l'unico valore accettato è null, che svuota il campo.

mask.setItemAllowNullById(id, allowNull)

Modifica la nullabilità del mask item indicato.

Se il parametro allowNull ha valore true allora il mask item sarà nullabile, altrimenti sarà obbligatorio.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

mask.setItemColorById(id, color, what)

Modifica il colore di un mask item.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

Il parametro color è una stringa rappresentante un colore CSS valido che indica il colore che deve essere impostato nel mask item.
Il parametro what indica quale parte del mask item deve essere colorata. I valori accettati sono i seguenti:

  • background
  • foreground
I mask item che consentono la configurazione del colore sono i seguenti:
  • Label
  • Separator

mask.setItemLabelById(id, label)

Modifica l'etichetta di un mask item.
Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.
Il parametro label indica il testo che deve essere scritto nel mask item.
I mask item che consentono la configurazione del label sono i seguenti:

  • Custom Button: il testo del bottone
  • Field: l'etichetta del campo
  • Group Box: il titolo del Group Box
  • Label: il testo mostrato
  • Link: il testo mostrato all'utente (NON l'URL del link)
  • Separator: il testo mostrato al centro del separator
  • TextBox: l'etichetta descrittiva associata al Text Box

mask.setItemUrlById(id, url)

Modifica l'URL a cui sta puntando un Link.
Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.
Il parametro url è una stringa che rappresente l'URL a cui il link dovrà puntare.

mask.setItemValueById(id, value)

Scrive un nuovo valore in un mask item.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.
Il parametro value indica il valore che deve essere scritto nel mask item.
I mask item che consentono la scrittura del valore sono i seguenti:
  • TextBox: permette di scrivere il valore del Text Box

mask.shiftTabSelection(idTabGroup, delta)

Cambia il tab selezionato in un Tab Group, spostando la selezione di una quantità indicata come parametro.

Il parametro idTabGroup indica l'Id del Tab Group.
Per ottenere l'Id del Tab Group a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

Il parametro delta è un numero intero che indica di quanti tab spostare la selezione rispetto al tab corrente. Se delta è positivo allora il conteggio avviene muovendosi in avanti. Se delta è negativo allora il conteggio avviene muovendosi all'indietro.

await mask.showLoading(callback, message)

Questa funzionalità combina startLoading ed endLoading.
Il parametro callback è una funzione asincrona che verrà invocata immediatamente.
Il parametro message permette di impostare il messaggio da mostrare nel pannello di caricamento (facoltativo).
L'indicatore di caricamento rimarrà visibile fino a che il callback non ha terminato l'operazione asincrona (risolvendo o rigettando la promessa).

mask.startLoading(options)

Mostra l'indicatore di caricamento della maschera.
Il parametro options permette di fornire ulteriori opzioni al componente che si occupa di mostrare il pannello di caricamento. L'oggetto accetta le seguenti opzioni:

  • message: permette di impostare il messaggio da mostrare nel pannello di caricamento (facoltativo)
Questo metodo può essere utilizzato per impedire all'utente di interagire con la maschera mentre si stanno eseguendo operazioni in background.

await mask.submit(options)

Esegue l'inserimento del profilo.

Il parametro opzionale options è un oggetto che può contenere le seguenti proprietà:

  • validate: un booleano che indica se deve essere eseguita la validazione della maschera prima di eseguire il salvataggio. Il valore di default è true.
  • closeMask: un booleano che indica se la maschera deve essere chiusa in seguito ad un submit concluso con successo. Il valore di default è true.

Il metodo ritorna un oggetto con le seguenti proprietà:

  • isValid: se è stata eseguita la validazione allora questa proprietà contiene un valore booleano che indica se tutti gli elementi della maschera sono in stato valido.
  • canceled: indica se il submit è stato annullato.
    È possibile che il submit venga annullato da dei gestori degli eventi che, aggianciati all'evento onBeforeInsert hanno annullato l'evento ritornando false.
  • closeMask: indica se la maschera è stata chiusa in seguito al submit.
    Questo valore può essere differente rispetto al parametro closeMask specificato nelle options perchè l'evento onAfterInsert ha la possibilità di sovrascriverne il valore.
  • objectId: indica l'ObjectId del profilo inserito.
  • protocolCode: se la classe in cui è stato inserito il profilo ha configurato un Automatic Register, allora questa proprietà indica il ProtocolCode che è stato generato per il profilo inserito.

mask.toggleItemById(id, visible)

Mostra o nasconde un mask item.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

Il parametro visible è un booleano con valore true se il mask item deve essere reso visibile, oppure false se il mask item deve essere nascosto.

mask.toggleItemEnableById(id, enabled)

Abilita o disabilita un mask item.

I mask item disabilitati non sono interagibili dall'utente. Ad esempio i Field diventano in sola lettura, i Custom Button e i Submit Buttons diventano non cliccabili.
Abilitare o disabilitare un GroupBox o una ScrollView ha come effetto l'abilitazione/disabilitazione di tutti gli oggetti presenti al suo interno.

Il parametro id indica l'Id del mask item. Per ottenere l'Id dell'oggetto a partire dal suo ExternalId si può utilizzare il metodo getItemIdByExternalId.

Il parametro enabled è un booleano con valore true se il mask item deve essere abilitato, oppure false se il mask item deve essere disabilitato.

await mask.validate()

Esegue la validazione dell'intera maschera e aggiorna la UI mostrando l'elenco aggiornato dei validatori falliti.

Questo metodo ritorna un oggetto con le seguenti proprietà:

  • isValid: un booleano che indica se tutti i validatori della maschera sono risultati validi.
  • brokenRules: questa proprietà contiene un array delle regole di validità che non sono state rispettate.
    Ogni regola di validità è rappresentata da un oggetto con la proprietà message (il messaggio di errore mostrato all'utente), la proprietà type (il tipo di regola di validità) e altre proprietà che variano in funzione del tipo di regola di validità.
    Se isValid ha valore true allora questa proprietà è un array vuoto.

await mask.validateFieldByExternalId(externalId)

Esegue la validazione di un campo e ne aggiorna la UI mostrando il risultato della validazione.

Questo metodo ritorna un oggetto con le seguenti proprietà:

  • isValid: un booleano che indica se tutti i validatori del campo sono risultati validi.
  • errorMessages: questa proprietà contiene un array di stringhe, ovvero i messaggi di errore dovuti alle regole di validità non rispettate.

Il parametro externalId indica l'ExternalId del campo da validare.

await mask.validateFieldById(id)

Esegue la validazione di un campo e ne aggiorna la UI mostrando il risultato della validazione.

Questo metodo ritorna un oggetto con le seguenti proprietà:

  • isValid: un booleano che indica se tutti i validatori del campo sono risultati validi.
  • errorMessages: questa proprietà contiene un array di stringhe, ovvero i messaggi di errore dovuti alle regole di validità non rispettate.

Il parametro id indica l'Id del campo da validare.