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 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 ayant déclenché l’événement. 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 le contrôle ayant déclenché l’événement. Cet objet peut s’avérer utile lorsque vous souhaitez écrire une seule méthode pouvant être enregistrée sur des événements sur plusieurs contrôles, au lieu de créer un gestionnaire d’événements distinct pour chaque contrôle. Par exemple, si vous avez un événement OnChange pour plusieurs champs, vous pouvez identifier le champ ayant déclenché l’événement à l’aide de getEventSource et l’utiliser en conséquence.

Contexte de formulaire

Le contexte de formulaire de l’API client (formContext) référence le formulaire ou un élément du formulaire tel qu’un contrôle de filtre 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.

Auparavant, l’élément ou le formulaire était accessible à l’aide de l’objet global Xrm.Page. Cependant, dans la dernière version, l’objet Xrm.Page est déconseillé. À la place, vous devez obtenir une référence au formulaire ou à l’élément approprié sur le formulaire à l’aide de la méthode getFormContext de l’objet de contexte d’exécution. 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) permet de manipuler des données dans le formulaire pour toute table.

Ce tableau est un résumé de chacun des objets et chacune des collections de l’objet de données :

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é	Méthodes permettant de récupérer des informations spécifiques de la ligne 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 en savoir plus, consultez formContext.data.entity.
Processus	Objets et méthodes permettant d’interagir avec les données de flux de processus métier sur un formulaire. Pour en savoir plus, consultez formContext.data.process.

Objet d’IU

L’objet d’IU (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 et chacune des collections de l’objet d’IU :

Nom	Description
Contrôles	Collection de tous les contrôles de la page. Pour en savoir plus sur les collections, les contrôles et les objets de contrôle de la collection, consultez Collections.
FormSelector	Méthodes permettant d’obtenir des informations sur les formulaires. Récupérez des informations sur le formulaire utilisé actuellement à l’aide de la méthode formSelector.getCurrentItem. Renvoyez des informations sur tous les formulaires à la disposition de l’utilisateur à l’aide de la collection formSelector.items.
Navigation	Collection de tous les éléments de navigation sur la page. Pour en savoir plus 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. En général, nous automatisons la navigation globale de l’application à l’aide de l’espace de noms Xrm.Navigation.
Processus	Objets et 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 en savoir plus, consultez formContext.ui.process.
QuickForms	Collection de tous les contrôles de filtre sur un formulaire. Pour en savoir plus, consultez formContext.ui.quickForms.
Onglets	Collection de tous les onglets de la page. Pour en savoir plus sur les éléments de la collection, consultez formContex.ui.tabs.

Il est courant d’obtenir ou de définir une valeur de colonne de table à l’aide de l’objet de données au lieu de l’objet d’IU. L’objet de données possède un seul attribut représentant la valeur de la colonne de table. En comparaison, l’objet d’IU comporte plusieurs contrôles pour la même colonne de table sur le formulaire, chacun avec une référence à l’attribut. Il est donc plus facile de manipuler la valeur d’attribut et l’objet d’IU à l’aide de l’objet de données pour 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.