Objets contextuels

Effectué

Lorsque vous créez des gestionnaires d’événements et que vous utilisez l’API de script client, vous devez comprendre les objets de contexte disponibles et comment les utiliser. La finalité des objets contextuels est d’offrir des informations concernant le contexte dans lequel votre code s’exécute. Ce contexte vous évite de coder en dur les informations contenues dans votre logique. Ce contexte vous permet de créer des fonctions plus génériques et de rendre vos fonctions moins sensibles à la structure de disposition spécifique des composants d’IU que vous utilisez.

Contexte d’exécution

Lorsque vous enregistrez un gestionnaire d’événements, vous avez la possibilité de transmettre le contexte d’exécution comme premier paramètre. Lorsque vous enregistrez le gestionnaire d’événements à l’aide des propriétés du formulaire, vous pouvez activer cette option. L’image illustre l’enregistrement d’un gestionnaire OnLoad et l’activation du contexte d’exécution.

En général, il est judicieux de toujours sélectionner cette option lorsque vous enregistrez un gestionnaire d’événements à l’aide des propriétés du formulaire. Lorsque vous enregistrez un gestionnaire d’événements à l’aide du code, cette option est sélectionnée automatiquement.

La définition de votre fonction qui prend le contexte d’exécution comme premier paramètre ressemblerait à ceci :

L’utilisation la plus courante du contexte d’exécution consiste à récupérer les contextes de formulaire et de grille. Une autre méthode utile dans ce contexte est getEventSource. La source de l’événement renvoie une référence à l’objet par rapport auquel l’événement s’est produit. Cet objet permet d’écrire des gestionnaires génériques qui interrogent la source de l’événement au moment de l’exécution pour découvrir sur quel contrôle l’événement s’est produit. Cet objet peut s’avérer utile lorsque vous écrivez une méthode que vous prévoyez d’enregistrer sur des événements pour plusieurs contrôles, au lieu d’enregistrer un gestionnaire d’événements distinct pour chaque contrôle.

Contexte de formulaire

Le contexte de formulaire de l’API client (formContext) offre une référence au formulaire ou à un élément du formulaire tel qu’un contrôle d’affichage rapide ou une ligne dans une grille modifiable par rapport auquel le code actuel s’exécute. Vous pouvez récupérer l’objet formContext du contexte d’exécution à l’aide de la fonction getFormContext.

Avant le contexte de formulaire, l’élément ou le formulaire était disponible à l’aide de l’objet global Xrm.Page. Dans la dernière version, l’objet Xrm.Page est obsolète et vous devez renvoyer une référence au formulaire ou à un élément du formulaire correspondant à l’aide de la méthode getFormContext de l’objet de contexte d’exécution transmis. Ainsi, au lieu d’écrire du code comme le suivant,

var firstName = Xrm.Page.getAttribute("firstname").getValue();

vous écririez le code ci-après à l’aide de formContext.

var formContext = executionContext.getFormContext();

var firstName = formContext.getAttribute("firstname").getValue();

En savoir plus sur l’obsolescence de Xrm.Page

Le schéma ci-après est un aperçu global des propriétés et méthodes disponibles dans le contexte de formulaire :

Objet de données

L’objet de données (formContext.data) est destiné à être utilisé pour toute manipulation de données de table et de processus dans le formulaire.

Ce tableau est un résumé de chacun des objets de données comportant des objets et collections :

Nom	Description
Attributs	Collection de données hors entité sur le formulaire. Les éléments de cette collection sont du même type de données que la collection d’attributs de l’entité, mais notez qu’il ne s’agit pas d’attributs de la table de formulaire.
Entité	Fournit des méthodes pour récupérer des informations spécifiques de l’enregistrement s’affichant sur la page, la méthode save et une collection de tous les attributs inclus dans le formulaire. Les données d’attribut sont limitées aux attributs représentés par des champs sur le formulaire par rapport à tous les champs disponibles dans la configuration d’entité. Pour plus d’informations, voir formContext.data.entity.
Processus	Fournit des objets et des méthodes pour interagir avec les données de flux de processus métier sur un formulaire. Pour plus d’informations, voir formContext.data.process.

Objet d’interface utilisateur

L’objet UI (formContext.ui) propose des méthodes pour récupérer des informations concernant l’interface utilisateur, ainsi que des collections pour plusieurs sous-composants du formulaire ou de la grille.

Ce tableau est un résumé de chacun des objets d’IU comportant des objets et des collections :

Nom	Description
Contrôles	Collection de tous les contrôles de la page. Pour plus d’informations sur les collections, les contrôles et les objets de contrôle de la collection, voir Collections.
FormSelector	Utilisez la méthode formSelector.getCurrentItem pour récupérer des informations sur le formulaire utilisé actuellement. Utilisez la collection formSelector.items pour renvoyer des informations sur tous les formulaires disponibles pour l’utilisateur.
Navigation	Collection de tous les éléments de navigation sur la page. Pour plus d’informations sur les éléments de la collection, consultez Élément formContext.ui.navigation. La navigation n’est pas disponible pour Microsoft Dynamics 365 pour tablettes. Pour automatiser la navigation globale de l’application, nous utilisons généralement l’espace de noms Xrm.Navigation.
Processus	Fournit des objets et des méthodes permettant d’interagir avec le contrôle de flux de processus métier sur un formulaire, par exemple, pour définir sa visibilité. Pour plus d’informations, consultez formContext.ui.process.
QuickForms	Collection de tous les contrôles de vue rapide sur un formulaire. Pour plus d’informations, consultez formContext.ui.quickForms.
Onglets	Collection de tous les onglets de la page. Pour plus d’informations sur les éléments de la collection, voir formContex.ui.tabs.

Il est courant d’utiliser l’objet de données au lieu de l’objet d’IU si vous devez obtenir ou définir une valeur de colonne de table. L’objet de données possède un seul attribut représentant la valeur de la colonne de table. Avec l’objet d’IU, vous pouvez avoir plusieurs contrôles pour la même colonne de table sur un formulaire, chacun avec une référence à l’attribut. Il est donc plus facile de manipuler la valeur de l’attribut et l’objet d’IU à l’aide de l’objet de données si vous souhaitez utiliser les contrôles qui représentent cet attribut sur le formulaire.

L’utilisation des objets de contexte dans vos scripts les rend plus résilients aux modifications apportées au formulaire et à l’API client.

Continuer