Associazione di opzioni di configurazione e dati

Una vista può essere associata a un binding di dati e a opzioni di configurazione. Il contesto della vista fornisce accesso a questi dati. Per accedere ai dati di binding e alle opzioni di configurazione, è necessario utilizzare le funzioni get e set JavaScript . Non è possibile utilizzare la notazione a punti JavaScript .

context.binding

L'oggetto di collegamento, se definito, fornisce l'accesso ai dati collegati a una vista. Esiste al massimo un bind di dati dichiarato per ciascuna vista.

È possibile accedere ai dati collegati a una vista utilizzando il costrutto this.context.binding.get("value"), dove value è un nome di proprietà speciale che restituisce il bind dei dati. Ad esempio, se una vista è associata a local.phoneBook.title, la vista può ottenere il titolo della rubrica nel modo seguente:


if (!! this.context.binding){
var title = this.context.binding.get("value")
}

Il motivo principale per il bind delle viste ai dati è che la vista può essere notificata se i dati collegati sono stati modificati. Il framework della vista rileva le modifiche dei dati nell'oggetto collegato e notifica automaticamente la vista richiamando la relativa funzione gestore eventi change . È importante notare che queste notifiche verranno inviate alla vista solo se l'oggetto di collegamento stesso cambia, ma non se cambiano le proprietà o le proprietà secondarie. Le seguenti sezioni discutono i diversi tipi di dati e delineano i casi in cui è richiesto un codice aggiuntivo per la vista per ricevere la notifica di una modifica dei dati.

Collegamento a tipi di dati semplici e complessi

Per tipi di dati semplici come stringhe e numeri, il framework della vista rileva le modifiche ai dati e notifica automaticamente la vista della modifica. Ad esempio, quando una vista è collegata al tipo di stringa semplice local.phoneBook.title, la funzione change() della vista viene richiamata con un evento di modifica che specifica che il titolo è stato modificato e il nuovo valore. Tutte le viste associate a local.phoneBook.title vengono notificate.

Per i tipi di dati complessi come gli oggetti di business, la vista viene notificata solo se l'oggetto di bind stesso cambia, ma non se cambiano le proprietà o le proprietà secondarie. Ad esempio, si supponga che la vista sia associata a un oggetto complesso local.phoneBook, non a un tipo semplice come String. L'oggetto phoneBook ha diverse proprietà, una delle quali è title. Se si verifica una modifica alla proprietà title , la funzione di modifica non viene richiamata, poiché la vista è collegata all'oggetto phoneBook e non alla proprietà title . La funzione di modifica viene richiamata solo se l'intero oggetto phoneBook viene modificato. Se è necessaria una vista per sapere se una proprietà di un oggetto complesso è stata modificata, è necessario collegare manualmente la vista alla proprietà utilizzando la funzione bind() o bindAll() . Notare che è possibile utilizzare le funzioni bind() e bindAll() nello stesso modo per le opzioni di configurazione.

Importante: la funzione bindAll() gestisce solo un livello nella struttura ad albero degli oggetti, quindi se l'oggetto ha più livelli (oggetti nidificati), la vista deve richiamare bindAll() più tempo per ogni livello di oggetto.

bind(path, callback, [scope]): Notifica la vista tramite callback se una proprietà specificata è stata modificata. L'ambito è un parametro facoltativo che specifica l'ambito di contesto del callback. Restituisce un handle al callback.
bindAll(callback, [scope]): Notifica la vista tramite callback se una proprietà sull'oggetto è stata modificata. L'ambito è un parametro facoltativo che specifica l'ambito di contesto del callback. Restituisce un handle al callback.

Per la firma callback, consultare l'argomento function (event) .

Il seguente esempio mostra il codice che è possibile aggiungere al gestore eventi di caricamento di una vista per collegare manualmente le proprietà di un oggetto complesso:

   var binding = this.context.binding.get("value");  //this is a complex object
   this.property2Handle = binding.bind("property1.property2", function(e) {some code}, this);
   this.property3Handle = binding.get("property3").bindAll(this.myBindAllChangeHandler, this);
   ......
   this.mybindAllChangeHandler(event) { .....};

Nell'esempio, la vista è collegata a un oggetto complesso e imposta un gestore di modifiche da notificare se binding.property1.property2 (che è una stringa) cambia. Inoltre, imposta un altro gestore modifiche per ricevere una notifica se una proprietà secondaria di property3 viene modificata. In entrambi i casi, l'ambito in cui viene richiamato il gestore modifiche è l'ambito this della vista.

Collegamento a un tipo di elenco

Quando si esegue il bind a un elenco, la vista viene automaticamente notificata quando l'intero oggetto Elenco cambia. Ad esempio, considerare che la vista è collegata all'elenco local.phoneBook.person[]. Se un nuovo elenco di persone viene creato e impostato sul bind della vista, ad esempio utilizzando la sintassi dello script del server tw.local.phoneBook.person = new tw.object.listOf.person(); il framework notifica automaticamente la modifica alla vista.

Collegamento agli aggiornamenti dell'elenco

Per ricevere una notifica quando un elemento viene aggiunto, rimosso o sostituito, è necessario collegare manualmente la vista utilizzando la funzione bindAll() . Nel seguente esempio di codice, la funzione listUpdated della vista viene richiamata ogni volta che un elemento dell'elenco viene aggiunto, rimosso o sostituito.

var binding = this.context.binding.get("value"); //this is a List object
this.bindAllHandle = binding.bindAll(this.listUpdated, this);

Collegamento alle proprietà dell'elenco

Oltre agli elementi di un elenco, un elenco dispone anche di proprietà speciali, ad esempio una proprietà che definisce gli elementi dell'elenco selezionati dall'utente. Le proprietà speciali sono descritte nella tabella seguente.

Tabella 1. Proprietà speciali di un elenco
Proprietà	Immettere	Descrizione
listAllSelectedIndices	Matrice	Gli indici degli elementi dell'elenco selezionati da un utente. Può essere selezionato più di un indice. Quando si imposta listAllSelectedIndices, si passano gli indici in un array. Utilizzare listAllSelectedIndices quando si aggiorna la selezione dell'elenco.
listAllSelected	Matrice	Un array di tutti gli elementi selezionati da un utente. Utilizzare listAllSelected per sottoscrivere una modifica a questa proprietà. questa proprietà è di sola lettura.
listSelectedIndex	Numero intero	L'indice dell'elemento selezionato. Questo valore corrisponde al valore dell'elemento di indice 0 della matrice listAllSelectedIndices. Utilizzare listSelectedIndex per sottoscrivere una modifica a questa proprietà. questa proprietà è di sola lettura.
listSelected	Oggetto	L'elemento selezionato. Questo valore corrisponde al valore dell'elemento di indice 0 della matrice listAllSelected. Utilizzare listSelected per sottoscrivere una modifica a questa proprietà. questa proprietà è di sola lettura.

La funzione bindAll() non include queste proprietà speciali.

Per ricevere la notifica di una modifica in una proprietà speciale, è possibile sottoscrivere la singola proprietà utilizzando la funzione bind() . In generale, è sufficiente sottoscrivere una proprietà speciale (vale a dire, non è necessario sottoscrivere tutte le proprietà speciali). Il seguente codice di esempio può essere aggiunto a un gestore eventi di caricamento per richiamare la funzione indicesChanged di una vista ogni volta che il valore di listAllSelectedIndices cambia.

var binding = this.context.binding.get("value"); //this is a list
this.selectedIndicesHandle = binding.bind("listAllSelectedIndices", this.indicesChanged, this);

Accesso agli elementi dell'elenco

Gli elenchi sono una raccolta di tipi semplici o di oggetti complessi con proprietà. Utilizzare la seguente notazione per richiamare i dati da un elenco:

Utilizzare get("value") per ottenere l'oggetto elenco. Ad esempio: list = this.context.binding.get("value")
Utilizzare get(index) per ottenere l'elemento indicizzato. Ad esempio: list.get(0) per ottenere il primo elemento.
Utilizzare get(property) per ottenere il valore della proprietà. Ad esempio: list.get("listSelected") per ottenere il valore della proprietà listSelected . Utilizzare una sintassi simile per ottenere i valori di tutte le altre proprietà.
Utilizzare items per ottenere un assieme che rappresenta gli elementi sottostanti dell'elenco. Ad esempio, list.items. I dati restituiti da items non devono essere modificati.

Elenca operazioni

Le seguenti API vengono utilizzate per modificare un elenco e per ottenere informazioni su un elenco.

Per aggiungere un oggetto, utilizzare list.add(item). Ad esempio, this.context.binding.get("value").add(item)
Per eliminare un oggetto, utilizzare list.remove(index), ad esempio this.context.binding.get("value").remove(0)
Per sostituire un oggetto, utilizzare list.put(index, item). Ad esempio, this.context.binding.get("value").put(0, item)
Per ottenere la lunghezza di un elenco, utilizzare list.length().
Per ottenere un elemento indicizzato o una proprietà dell'elenco, utilizzare list.get(index | property). Consultare Accesso agli elementi dell'elenco in precedenza.
Per aggiornare in modo programmatico la proprietà selezionata nell'elenco, utilizzare list.set(property). Ad esempio, this.context.binding.get("value").set("listAllSelectedIndices", [1, 2, 3]);

Ripulitura delle risorse associate

Quando un binding non è più necessario, è possibile rilasciare le risorse associate. Ogni funzione bind o bindAll restituisce un handle che può essere utilizzato per ripulire il bind. È necessario rilasciare le risorse collegate nel gestore eventi unload() o ogni volta che l'intero oggetto di collegamento viene modificato. Quando si verifica una modifica dei dati di bind, una vista deve annullare il bind manuale e ricollegarsi all'oggetto context.binding richiamando nuovamente bind e bindAll . Ad esempio, aggiungere il codice seguente nel gestore eventi di modifica:

if (event.type != "config"){
var binding = this.context.binding.get("value"); //this is a list
	// assumes that this.selectedIndicesHandle was initialized in the load function
  this.selectedIndicesHandle.unbind();
this.selectedIndicesHandle = binding.bind("listAllSelectedIndices", this.indicesChanged, this);
	// assumes that this.selectedIndicesHandle was initialized in the load function
this.bindAllHandle.unbind();
this.bindAllHandle = binding.bindAll(this.listUpdated, this);

}

Opzioni di configurazione

Oltre ai dati, anche le viste possono essere collegate alle opzioni di configurazione. Una visualizzazione può avere più opzioni di configurazione. Ad esempio, l'etichetta di un controllo pulsante è una proprietà di configurazione. I valori per la configurazione possono essere richiamati utilizzando l'oggetto this.context.options della vista. L'oggetto context.options contiene una proprietà di metadati predefinita oltre alle proprietà definite dall'utente configurabili per una vista.

Tabella 2. Opzioni di configurazione predefinite di una vista
Opzione	Immettere	Descrizione
etichetta	La stringa	Il valore dell'etichetta della vista, se presente
visibilità	La stringa	Impostazioni di visibilità della vista. I valori validi sono: `"DEFAULT"` \| '`"EDITABLE"` \| '`"REQUIRED"` \| '`"READONLY"` \| '`"NONE"` \| '`"HIDDEN"`. Vedere L'oggetto contesto. `DEFAULT` è il codice equivalente a '`Same as parent` che gli utenti vedono sullo schermo in un elenco di visibilità. Importante: le tabelle hanno una proprietà di configurazione Disabilita click - to - edit . Il valore predefinito è false, il che significa che le viste contenute in tale tabella utilizzano le impostazioni di visibilità della tabella. In altre parole, le viste in una determinata cella sono `READONLY` fino a quando l'utente non fa clic nella cella. Le viste vengono quindi `EDITABLE` finché l'utente non fa clic in un punto qualsiasi all'esterno della cella. Le viste tornano ad essere `READONLY`. Quando Disabilita click - to - edit è true, queste viste utilizzano le proprie impostazioni di visibilità. Importante: l'impostazione della visibilità su `REQUIRED` non convalida se un utente ha immesso o impostato un valore. È necessario fornire il codice che esegue questo controllo, ad esempio implementando un servizio di convalida per il coach che contiene la vista.
labelVisibility	La stringa	Impostazioni di visibilità dell'etichetta. I valori validi sono `"SHOW"` \| `"HIDE"`.
helpText	La stringa	La vista può utilizzare questa proprietà come testo a comparsa
className	La stringa	Il nome o i nomi classe CSS specificati. Di solito, non è necessario utilizzare questa vista poiché i nomi delle classi CSS vengono inseriti nell'attributo DOM della vista.
htmlOverrides	Associazione	Un'associazione delle coppie nome/valore che rappresenta l'attributo HTML specificato. Queste coppie nome/valore sono inserite nell'attributo DOM della vista.

Le opzioni di configurazione vengono accedute e aggiornate allo stesso modo dei dati di collegamento. Ad esempio:

Per ottenere le opzioni predefinite di una vista, utilizzare this.context.options._metadata.*. Ad esempio, per ottenere l'opzione di visibilità di una vista, utilizzare this.context.options._metadata.visibility.get("value");
Per impostare le opzioni predefinite di una vista, utilizzare this.context.options._metadata.*. Ad esempio, per impostare l'opzione di visibilità di una vista, utilizzare this.context.options._metadata.visibility.set("value", newValue);
Per ottenere un'opzione di configurazione definita dall'utente, utilizzare this.context.options.myOption.get("value");, dove myOption è il nome dell'opzione.
Per impostare un'opzione di configurazione definita dall'utente, utilizzare this.context.options.myOption.set("value", newValue);, dove myOption è il nome dell'opzione.

Per serializzare l'oggetto di bind dei dati in una stringa JSON, è possibile richiamare la funzione toJson() sull'oggetto di bind dei dati. Per richiamare un oggetto JavaScript di base che rappresenta il bind dei dati, è possibile richiamare toJSObject().