Tâches courantes de script client

• 8 minutes

Le modèle d’objet d’API client est vaste et riche. En vous familiarisant avec l’écriture de scripts client, vous constatez que vous pouvez implémenter votre logique à l’aide de nombreux objets et méthodes d’API. Dans cette unité, nous allons examiner certaines des tâches courantes que vous effectuez, ainsi que les techniques permettant de les accomplir.

Accéder aux données de colonne Dataverse

Une colonne Dataverse se trouve dans le modèle d’objet en tant qu’objet d’attribut. La méthode getAttribute() de l’objet formContext vous permet de localiser rapidement un attribut spécifique ou tous les attributs présents sur le formulaire. Chaque objet d’attribut comprend des méthodes courantes et d’autres méthodes, selon le type de données d’attribut.

Tâche	Exemple
Accéder par nom	javascript var nameAttribute = formContext.getAttribute("name"); Affecte l’attribut pour la colonne Nom du compte à la variable nameAttribute. Si l’attribut n’est pas présent sur le formulaire, la méthode getAttribute renvoie la valeur null.
Accéder à tous les attributs	javascript var allAttributes = formContext.getAttribute(); Affecte un tableau de tous les attributs dans la collection formContext.data.entity.attributes à la variable allAttributes.

Utiliser des attributs

Tâche	Exemple
Obtenir la valeur d’un attribut	javascript var nameValue = formContext.getAttribute("name").getValue(); Affecte la valeur de la colonne Account Name à la variable nameValue.
Définir la valeur d’un attribut	javascript formContext.getAttribute("name").setValue("new name"); Définit la valeur de la colonne Account Name sur « nouveau nom ».
Obtient l’objet d’option sélectionné actuellement dans un attribut OptionSet (l’attribut OptionSet décrit la colonne de choix Dataverse)	javascript var addressTypeOption = formContext.getAttribute("address1_addresstypecode").getSelectedOption(); Affecte l’option sélectionnée dans la colonne Address Type à la variable addressTypeOption.
Déterminer si une valeur d’attribut a changé dans l’interface utilisateur depuis l’ouverture du formulaire	javascript var isNameChanged = formContext.getAttribute("name").getIsDirty(); Affecte une valeur booléenne qui indique si la valeur de la colonne Account Name a changé en la variable isNameChanged.
Changer si les données sont requises dans une colonne pour enregistrer un enregistrement	javascript formContext.getAttribute("creditlimit").setRequiredLevel("required"); Définit la colonne Crédit autorisé comme étant obligatoire. javascript formContext.getAttribute("creditlimit").setRequiredLevel("none"); Définit la colonne Crédit autorisé comme étant facultative.
Déterminer si les données d’un attribut sont envoyées lorsque l’enregistrement est enregistré	javascript var nameSubmitMode = formContext.getAttribute("name").getSubmitMode(); La valeur de la variable nameSubmitMode est un texte toujours, jamais ou modifié pour représenter la variable submitMode pour la colonne Account Name.
Contrôler si les données d’un attribut sont enregistrées lorsque l’enregistrement est enregistré	javascript formContext.getAttribute("name").setSubmitMode("always"); L’exemple force la valeur de la colonne Account Name à toujours être enregistrée, même si elle n’a pas changé.
Lorsque la sécurité de niveau de colonne a été appliquée à un attribut, déterminez si un utilisateur dispose des privilèges permettant d’effectuer des opérations de création, de lecture ou de mise à jour sur l’attribut.	javascript var canUpdateNameAttribute = formContext.getAttribute("name").getUserPrivilege().canUpdate; Affecte une valeur booléenne qui représente le privilège de l’utilisateur de redéfinir la colonne Account Name sur la variable canUpdateNameAttribute.

Accéder aux contrôles de formulaire

Tâche	Exemple
Accéder à tous les contrôles pour un attribut spécifique	javascript var nameControls = formContext.getAttribute("name").controls.get(); Affecte un tableau de tous les contrôles pour l’attribut Nom à la variable nameControls. La plupart des attributs sont représentés par un seul contrôle, mais ils peuvent avoir plusieurs contrôles si une même colonne a été ajoutée plusieurs fois au formulaire.
Accéder à un contrôle par son nom	javascript var nameControl = formContext.getControl("name"); Le premier contrôle ajouté à un formulaire pour une colonne porte le même nom que la colonne. Chacun des autres noms de contrôle se voit ajouter un numéro d’index. Par exemple, trois contrôles pour la colonne de nom sont nommés name, name1 et name2, respectivement.
Accéder à tous les contrôles	javascript var allControls = formContext.getControl(); Affecte un tableau de tous les contrôles dans la collection formContext.ui.controls à la variable allControls.

Utiliser des contrôles de formulaire

Les objets de contrôle comme les objets d’attribut possèdent un ensemble commun de méthodes, quel que soit leur type. Ils possèdent également des méthodes spécialisées selon le type de contrôle.

Tâche	Exemple
Déterminer si un contrôle est visible	javascript var isNameVisible = formContext.getControl("name").getVisible(); Affecte une valeur booléenne à la variable isNameVisible qui indique si la colonne Account Name est visible.
Masquer ou afficher un contrôle	javascript formContext.getControl("name").setVisible(false); Masque la colonne Account Name.
Obtenir une référence à l’attribut du contrôle	javascript var nameAttribute = formContext.getControl("name").getAttribute(); Affecte l’attribut pour le contrôle de la colonne Account Name à la variable nameAttribute.
Désactiver ou activer tous les contrôles pour un attribut	javascript formContext.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); }); N’oubliez pas que tout attribut peut avoir plusieurs contrôles.
Modifier l’intitulé d’un contrôle	javascript formContext.getControl("name").setLabel("Company Name"); Définit l’intitulé de la colonne Account Name sur le texte Nom de la société.
Obtenir le parent d’un contrôle	javascript var parentSection = formContext.getControl("name").getParent(); Affecte le contrôle parent de la colonne Account Name à la variable parentSection.
Définir le focus sur un contrôle	javascript formContext.getControl("name").setFocus(); Définit le focus d’entrée actif sur la colonne Account Name.

Utiliser les onglets et sections

Chaque formulaire contient une collection d’onglets. Chaque onglet contient une collection de sections. Chaque section contient une collection de contrôles. Vous pouvez accéder par programme à ces éléments et utiliser leurs méthodes.

Tâche	Exemple
Afficher ou masquer un onglet	javascript formContext.ui.tabs.get("general").setVisible(false); Masque l’onglet général.
Modifier l’intitulé d’un onglet	javascript formContext.ui.tabs.get("general").setLabel("Major"); Définit l’intitulé de l’onglet général sur le texte Majeur.
Afficher ou masquer une section	javascript formContext.getControl("industrycode").getParent().setVisible(false); Masque la section contenant la colonne Industry Code.

Utiliser des données d’entité

Le tableau suivant contient des méthodes que vous pouvez utiliser pour obtenir des informations concernant l’enregistrement actif.

Tâche	Exemple
Obtenir l’identifiant de l’enregistrement actif	javascript var recordId = formContext.data.entity.getId(); Affecte un identificateur unique d’enregistrement actif à la variable recordId. Si le formulaire est ouvert pour créer un enregistrement, la valeur null est renvoyée.
Enregistrer l’enregistrement actif	javascript formContext.data.entity.save(); Effectuez les actions équivalentes avec Enregistrer et fermer ou Enregistrer et nouveau à l’aide de saveandclose ou saveandnew.
Déterminez si des données de l’enregistrement actif ont été modifiées.	javascript var isDirty = formContext.data.entity.getIsDirty(); Affecte une valeur booléenne qui indique si la valeur d’une colonne du formulaire a été modifiée en variable isDirty.