Contexte du formulaire API client

Le contexte de formulaire de l’API client (formContext) fournit une référence au formulaire ou à un élément du formulaire, comme un contrôle d’aperçu ou une ligne dans une grille modifiable, sur lequel le code actuel est exécuté.

Auparavant, l’objet Xrm.Page global était utilisé pour représenter un formulaire ou un élément du formulaire. Avec la version la plus récente, l’objet Xrm.Page est déconseillé, et vous devez maintenant utiliser la méthode getFormContext de l’objet de contexte d’exécution transmis pour renvoyer la référence au formulaire approprié ou à un élément du formulaire.

Important

Déconseillé signifie que nous avons l’intention de supprimer une fonctionnalité ou une capacité d’une future version majeure des applications basées sur un modèle ; la fonctionnalité ou la capacité continuera de fonctionner et sera entièrement prise en charge jusqu’à ce qu’elle soit officiellement supprimée. Une annonce publique dans cette documentation, sur le blog officiel et à de nombreux autres emplacements sera faite au moins six mois avant sa suppression.

L’utilisation de l’objet Xrm.Page comme accès statique au contexte du formulaire principal est toujours pris en charge pour maintenir la compatibilité descendante avec les scripts existants, et ne sera pas supprimée aussi rapidement que d’autres méthodes d’API client répertoriées dans la section Obsolescence de l’API client. Nous vous recommandons d’utiliser le nouvel objet formContext au lieu de l’objet Xrm.Page dans votre la version 9.0 ou ultérieure ciblant le code lorsque cela est possible. De plus, l’utilisation de l’objet formContext vous permet de créer des gestionnaires d’événements communs qui peuvent fonctionner sur un formulaire ou dans une grille modifiable selon l’emplacement d’appel. Pour plus d’informations : getFormContext (référence de l’API client).

L’obtention de l’objet formContext pour les fonctions Javascript pour des actions de ruban est différente de la manière dont vous obtenez celui-ci dans les scripts de formulaire. Plus d’informations : Contexte de formulaire et de grille dans les actions du ruban.

Notes

Les contextes de formulaire ne sont valides que pendant l’événement où ils sont transmis. Les mêmes restrictions s’appliquent qu’avec les contextes d’exécution

Utilisation de l’objet formContext au lieu de l’objet Xrm.Page

Il est facile de convertir le code existant avec Xrm.Page pour utiliser le nouvel objet formContext. Par exemple, prenez le script suivant qui utilise l’objet Xrm.Page :

function displayName()
{
   var firstName = Xrm.Page.getAttribute("firstname").getValue();
   var lastName = Xrm.Page.getAttribute("lastname").getValue();
   console.log(firstName + " " + lastName);
}

Voici le script mis à jour qui utilise le contexte d’exécution transmis pour récupérer l’objet formContext au lieu d’utiliser l’objet statique Xrm.Page  :

function displayName(executionContext)
{
   var formContext = executionContext.getFormContext(); // get formContext

   // use formContext instead of Xrm.Page   
   var firstName = formContext.getAttribute("firstname").getValue(); 
   var lastName = formContext.getAttribute("lastname").getValue();
   console.log(firstName + " " + lastName);
}

Important

Vous devez vous souvenir de sélectionner l’option Transmettre le contexte d’exécution comme premier paramètre dans la boîte de dialogue Propriétés du gestionnaire lors de la configuration des gestionnaires d’événements pour utiliser l’objet formContext. Pour plus d’informations, voir Contexte d’exécution de l’API client

Modèle d’objet formContext

Utilisez les objets data et ui sous l’objet formContext pour manipuler par programme les éléments de données et d’interface utilisateur dans les applications basées sur un modèle.

objet de données

Fournit des propriétés et des méthodes pour travailler avec les données d’un formulaire, y compris les données de table et les données du contrôle flux des processus d’entreprise. Contient les objets suivants :

Object	Description
attributes	Collection de données hors table sur le formulaire. Les éléments de cette collection sont du même type que la collection de colonnes, mais ils ne sont pas des colonnes de forme table. Pour plus d’informations, voir Collections
entity	Fournit des propriétés et des méthodes pour récupérer des informations spécifiques dans l’enregistrement affiché sur la page, la méthode save et une collection de tous les attributs inclus dans le formulaire. Les données de colonne sont limitées aux colonnes représentées sur le formulaire. Pour plus d’informations, voir formContext.data.entity
process	Fournit des objets et des méthodes pour interagir avec les données du flux des processus d′entreprise dans un formulaire. Pour plus d’informations, voir formContext.data.process

Fournit également une collection d’attributs pour accéder à un contrôle non lié à une table. Consultez la section Collections dans le modèle d’objet formContext plus loin dans cet article.

Pour plus d’informations, consultez : formContext.data

Objet ui

Fournit des méthodes pour récupérer les informations concernant l’interface utilisateur, outre les collections pour plusieurs sous-composants du formulaire ou de la grille. Contient les objets suivants :

Object	Description
formSelector	Fournit une collection d’éléments qui fournit des fonctionnalités pour interroger les formulaires disponibles pour l’utilisateur actuel. Utilisez la méthode navigate pour fermer le formulaire actif et en ouvrir un autre.
navigation	Ne contient aucune méthode. Permet d’accéder aux éléments de navigation via la collection d’éléments. Consultez la section suivante sur les collections pour plus d’informations.
process	Fournit des méthodes pour interagir avec le contrôle du flux des processus d’entreprise dans un formulaire.

Pour plus d’informations, consultez : formContext.ui

Collections du modèle d’objet formContext

Le tableau suivant décrit les collections du modèle d’objet Xrm. Pour plus d’informations sur les méthodes disponibles pour les collections en général, voir Collections (référence de l’API client).

Collection	Description
attributes	Deux objets contiennent une collection de colonnes : - La collection formContext.data.attributes permet d’accéder aux colonnes non liées à une table. - La collection formContext.data.entity.attributes permet d’accéder à chaque colonne de table disponible sur le formulaire. Seules les colonnes ajoutées au formulaire sont disponibles.
Contrôles	Trois objets contiennent un ensemble de contrôles : - formContext.ui.controls : donne accès à chaque contrôle présent dans le formulaire. - formContext.data.entity.attribute.controls : Étant donné qu’une colonne peut avoir plusieurs contrôles sur le formulaire, cette collection donne accès à chacun d’eux. Cette collection ne contient qu’un seul élément, sauf si plusieurs contrôles pour la colonne sont ajoutés au formulaire. - formContext.ui.tabs.sections.controls : cette collection contient uniquement les contrôles disponibles dans la section.
formContext.data.process.stages et formContext.data.process.steps	Donne accès à une collection de phases et d’étapes dans un flux des processus d’entreprise. Elles permettent également d’ajouter et de supprimer des éléments de la collection.
formContext.ui.formSelector.items	Lorsque plusieurs formulaires sont fournis pour une table, vous pouvez associer chaque formulaire à des rôles de sécurité. Lorsque les rôles de sécurité associés à un utilisateur lui permettent d’afficher plusieurs formulaires, la collection formContext.ui.formSelector.items permet d’accéder à chaque définition de formulaire disponible pour cet utilisateur.
formContext.ui.navigation.items	La collection formContext.ui.navigation.items donne accès aux éléments de navigation qui sont définis dans la zone de navigation de l’éditeur de formulaires. Les utilisateurs accèdent à ces derniers à l’aide de la barre de commandes.
formContext.ui.quickForms	Fournit des méthodes pour accéder à tous les contrôles d’affichage rapide et à ses contrôles constitutifs sur les formulaires.
formContext.ui.tabs	Vous pouvez organiser chaque formulaire en utilisant un ou plusieurs onglets. Cette collection donne accès à chacun de ces onglets.
formContext.ui Tab.sections	Vous pouvez organiser chaque onglet de formulaire en utilisant une ou plusieurs sections. La collection sections donne accès à chacune de ces sections. Vous devez définir l’onglet qui contient la section souhaitée ou parcourir chaque onglet pour trouver la section appropriée.

Articles associés

getFormContext method
getGlobalContext method
getAttribute method
getControl method
Méthodes du contexte d’exécution

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).