Options de configuration données de liaison et de configuration

Une vue peut être associée à une liaison de données et à des options de configuration. Le contexte de vue fournit l'accès à ces données. Pour accéder à la liaison de données et aux options de configuration, vous devez utiliser les fonctions JavaScript get et set. Vous ne pouvez pas utiliser la notation JavaScript.

context.binding

L'objet de liaison, s'il est défini, permet d'accéder à des données qui sont liées à une vue. Il existe au moins une liaison de données déclarée pour chaque vue.

Vous pouvez accéder aux données liées à une vue à l'aide de la construction: this.context.binding.get("value"), où value est un nom de propriété spécial qui renvoie la liaison de données. Par exemple, si une vue est liée à local.phoneBook.title, la vue peut obtenir le titre de l'annuaire téléphonique comme suit:


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

Les vues se lient aux données principalement pour être averties des modifications des données. La structure de vue détecte les modifications de données dans l'objet lié et avertit automatiquement la vue en appelant sa fonction du gestionnaire d'événements change. Il est important de noter que ces notifications seront envoyées à la vue uniquement si l'objet de liaison lui-même change, mais pas si l'une de ses propriétés ou sous-propriétés change. Les sections suivantes décrivent les différents types de données et les cas où du code supplémentaire est nécessaire pour que la vue puisse recevoir une notification de modification des données.

Liaison à des types de données simples et complexes

Pour les types de données simples, tels que les chaînes et les nombres, la structure de vue détecte les modifications de données et signale automatiquement les modifications à la vue. Par exemple, lorsqu'une vue est liée à la chaîne de type simple local.phoneBook.title, la fonction change() de la vue est appelée avec un événement de modification qui indique que le titre a changé et sa nouvelle valeur. Toutes les vues qui sont liées à local.phoneBook.title sont averties.

Pour les types de données complexes, tels que les objets métier, la vue est notifiée uniquement si l'objet de liaison lui-même change, mais pas si l'une de ses propriétés ou sous-propriétés change. Supposons que la vue est liée à un objet complexe local.phoneBook et non pas à un type simple comme une chaîne. L'objet phoneBook a plusieurs propriétés, notamment title. S'il y a une modification de la propriété title , la fonction de modification n'est pas appelée car la vue est liée à l'objet phoneBook et non à la propriété title . La fonction de modification est appelée uniquement si la totalité de l'objet phoneBook est modifié. S'il est nécessaire qu'une vue sache si une propriété d'un objet complexe a changé, vous devez lier manuellement la vue à la propriété à l'aide de la fonction bind() ou bindAll(). Notez que vous pouvez utiliser les fonctions bind() et bindAll() de la même manière pour les options de configuration.

Important: La fonction bindAll() ne gère qu'un niveau de profondeur dans l'arborescence des objets. Par conséquent, si l'objet comporte plusieurs niveaux (objets imbriqués), la vue doit appeler des multiples de temps bindAll() pour chaque niveau d'objet.

bind(path, callback, [scope]): Indique la vue via un rappel si une propriété indiquée a changé. Scope est un paramètre facultatif qui définit la portée contextuelle du rappel. Retourne un descripteur au rappel.
bindAll(callback, [scope]): Notifie la vue via un rappel si une propriété de l'objet a été modifié. Scope est un paramètre facultatif qui définit la portée contextuelle du rappel. Retourne un descripteur au rappel.

Pour la signature de rappel, voir la rubrique fonction (événement) .

L'exemple suivant présente un code que vous pouvez ajouter à une vue de chargement du gestionnaire d'événements pour lier manuellement les propriétés d'un objet complexe :

   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) { .....};

Dans cet exemple, la vue est liée à un objet complexe et définit un gestionnaire de modifications à avertir si binding.property1.property2 (une chaîne) change. Elle définit également un autre gestionnaire de modifications à informer si une sous-propriété property3 change. Dans les deux cas, la portée dans laquelle le gestionnaire de modifications est appelé est la portée this de la vue.

Liaison à un type de liste

Lorsque vous effectuez une liaison à une liste, la vue est automatiquement averti lorsque tout l'objet Liste change. Par exemple, supposons que la vue est liée à la liste local.phoneBook.person[]. Si une nouvelle liste de personnes est créée et définie sur la liaison de la vue, par exemple, à l'aide de la syntaxe de script du serveur tw.local.phoneBook.person = new tw.object.listOf.person(); , la structure informe automatiquement la vue du changement.

Liaison aux mises à jour de la liste

Pour recevoir une notification lorsqu'un élément est ajouté, supprimé ou remplacé, vous devez lier la vue manuellement à l'aide de la fonction bindAll(). Dans l'exemple de code, la fonction listUpdated de la vue est appelée chaque fois qu'un élément de liste est ajouté, supprimé ou modifié.

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

Liaison aux propriétés de la liste

Outre les éléments, une liste possède également des propriétés spéciales, telle qu'une propriété qui définit les éléments de liste sélectionnés par un utilisateur. Les propriétés spéciales sont décrites dans le tableau suivant.

Tableau 1. Propriétés spéciales d'une liste
Propriété	Type	Description
listAllSelectedIndices	Tableau	Index des éléments de liste sélectionnées par un utilisateur. Plusieurs index peuvent être sélectionnés. Lorsque vous définissez listAllSelectedIndices, vous envoyez les index dans un tableau. Utilisez listAllSelectedIndices lors de la mise à niveau de la sélection de liste.
listAllSelected	Tableau	Tableau de tous les éléments qu'un utilisateur a sélectionné. Utilisez listAllSelected pour vous abonner à une modification à cette propriété. Cette propriété est en lecture seule.
listSelectedIndex	Entier	Index de l'élément sélectionné. Cette valeur correspond à la valeur de l'élément d'index 0 du tableau listAllSelectedIndices. Utilisez listSelectedIndex pour vous abonner à une modification à cette propriété. Cette propriété est en lecture seule.
listSelected	Objet	Elément sélectionné. Cette valeur correspond à la valeur de l'élément d'index 0 du tableau listAllSelected. Utilisez listSelected pour vous abonner à une modification à cette propriété. Cette propriété est en lecture seule.

La fonction bindAll() ne contient pas ces propriétés spéciales.

Pour recevoir la notification d'une modification dans une propriété spéciale, vous devez vous abonner à la propriété en utilisant la fonction bind(). En règle générale, il suffit de s'abonner à une propriété spéciale (à savoir qu'il n'est pas nécessaire de s'abonner à toutes les propriétés spéciales). L'exemple de code suivant pourrait être ajouté à un gestionnaire d'événements de chargement pour appeler la fonction indicesChanged d'une vue chaque fois que la valeur de listAllSelectedIndices change.

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

Accès aux éléments d'une liste

Les listes sont une collection d'objets de type simple ou complexe ayant des propriétés. Utilisez la notation suivante pour obtenir les données d'une liste :

Utilisez get("value") pour obtenir l'objet liste. Par exemple : list = this.context.binding.get("value")
Utilisez get(index) pour obtenir l'élément indexé. Par exemple, list.get(0) pour obtenir le premier élément.
Utilisez get(property) pour obtenir la valeur de la propriété. Par exemple, list.get("listSelected") pour obtenir la valeur de la propriété listSelected. Utilisez la même syntaxe pour obtenir les valeurs de toutes les autres propriétés.
Utilisez items pour obtenir un tableau qui représente les éléments sous-jacents de la liste. Par exemple, list.items. Les données retournées par items ne doivent pas être modifiées.

Opérations de liste

Les API suivantes sont utilisées pour modifier une liste et pour obtenir des informations sur une liste.

Pour ajouter un objet, utilisez list.add(item). Exemple : this.context.binding.get("value").add(item)
Pour supprimer un objet, utilisez list.remove(index), Par exemple, this.context.binding.get("value").remove(0)
Pour remplacer un objet, utilisez list.put(index, item). Exemple : this.context.binding.get("value").put(0, item)
Pour obtenir la longueur d'une liste, utilisez list.length().
Pour obtenir un élément ou une propriété indexée de la liste, utilisez list.get(index | property). Voir Accès aux éléments de liste précédemment.
Pour mettre à jour par programmation la propriété sélectionnée dans la liste, utilisez use list.set(property). Exemple : this.context.binding.get("value").set("listAllSelectedIndices", [1, 2, 3]);

Nettoyage des ressources liées

Lorsqu'une liaison n'est plus nécessaire, vous pouvez libérer les ressources liées. Chaque fonction bind ou bindAll renvoie un descripteur qui peut être utilisé pour nettoyer la liaison. Vous devez libérer les ressources liées dans le gestionnaire d'événements unload() ou chaque fois que l'ensemble de l'objet de liaison est modifié. Lorsqu'une modification de liaison de données se produit, une vue doit délier la liaison manuelle et se relier à l'objet context.binding en appelant bind et bindAll. Par exemple, ajoutez le code suivant dans le gestionnaire d'événements de chargement :

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);

}

Options de configuration

Outre les données, des vues peuvent également être associées à des options de configuration. Une vue peut avoir plusieurs options de configuration. Par exemple, le libellé d'un bouton de contrôle est une propriété de configuration. Les valeurs de la configuration peuvent être extraites en utilisant l'objet this.context.options de la vue. L'objet context.options contient une propriété prédéfinie de métadonnées en plus des propriétés définies par l'utilisateur qui sont configurables pour une vue.

Tableau 2. Options de configuration prédéfinies d'une vue
Option	Type	Description
libellé	Chaîne	Valeur du libellé de la vue, s'il existe.
visibilité	Chaîne	Paramètres de visibilité de la vue. Les valeurs valides sont les suivantes : `"DEFAULT"` \| '`"EDITABLE"` \| '`"REQUIRED"` \| '`"READONLY"` \| '`"NONE"` \| '`"HIDDEN"`. Voir l'objet contextuel. le `DEFAULT` est le code équivalent au " `Same as parent` que les utilisateurs voient à l'écran dans une liste de visibilité. Important: Les tables comportent une propriété de configuration Désactiver le clic pour éditer . La valeur par défaut est false, ce qui signifie que les vues contenues dans cette table utilisent les paramètres de visibilité de la table. En d'autres termes, les vues d'une cellule donnée sont `READONLY` jusqu'à ce que l'utilisateur clique dans la cellule. Les vues sont ensuite `EDITABLE` jusqu'à ce que l'utilisateur clique en dehors de la cellule. Les vues redeviennent `READONLY`. Lorsque Désactiver Cliquer-pour-modifier a la valeur true, ces vues utilisent leurs propres paramètres de visibilité. Important: La définition de la visibilité sur `REQUIRED` ne valide pas si un utilisateur a entré ou défini une valeur. Vous devez fournir le code qui effectue cette vérification en implémentant, par exemple, un service de validation pour le coach qui contient la vue.
labelVisibility	Chaîne	Paramètres de visibilité du libellé. Les valeurs admises sont `"SHOW"` \| `"HIDE"`.
helpText	Chaîne	La vue peut utiliser cette propriété comme infobulle
className	Chaîne	Nom(s) de classe CSS définie. Généralement, une vue n'a pas besoin de l'utiliser, car les noms de classe CSS sont insérés dans l'attribut DOM de la vue.
htmlOverrides	Mappe	Mappe de paire nom-valeur qui représente l'attribut HTML spécifié. Ces paires nom-valeur sont insérées dans l'attribut DOM de la vue.

Les options de configuration sont accessibles et mises à jour de la même manière que la liaison de données. Par exemple :

Pour obtenir les options prédéfinies d'une vue, utilisez this.context.options._metadata.* Par exemple, pour obtenir l'option de visibilité d'une vue, utilisez this.context.options._metadata.visibility.get("value");
Pour obtenir les options prédéfinies d'une vue, utilisez this.context.options._metadata.*. Par exemple, pour définir l'option de visibilité d'une vue, utilisez this.context.options._metadata.visibility.set("value", newValue);
Pour obtenir une option de configuration définie par l'utilisateur, utilisez this.context.options.myOption.get("value");, où myOption est le nom d'option.
Pour définir une option de configuration définie par l'utilisateur, utilisez this.context.options.myOption.set("value", newValue);, où myOption est le nom de l'option.

Pour sérialiser l'objet de liaison de données à une chaîne JSON, vous pouvez appeler la fonction toJson() sur l'objet de liaison de données. Pour obtenir un objet JavaScript de base qui représente la liaison de données, vous pouvez appeler toJSObject().