Attribut Xrm.Page.data.entity (référence côté client) 

Date de publication : novembre 2016

S’applique à : Dynamics CRM 2015

Les attributs contiennent les données dans le formulaire. Utilisez la collection Xrm.Page.data.entity.attributs ou Xrm.Page.getAttribute ou la méthode de raccourci pour accéder à un ensemble d’attributs. Pour plus d'informations, voir Collections (référence côté client).

Propriétés et méthodes relatives aux attributs

• Méthodes relatives aux attributs booléens et de groupe d’options
  Les méthodes getInitialValue, getOption, getOptions, getSelectedOption et getText fournissent des façons d’obtenir des informations sur les attributs booléens ou de groupes d’options.

• Contrôles
  Accède aux contrôles associés aux attributs.

• getAttributeType
  Obtient le type d’attribut.

• getFormat
  Obtient le format d’attribut.

• getIsDirty
  Détermine si la valeur d’un attribut a changé depuis son dernier enregistrement.

• getIsPartyList
  Détermine si un attribut de recherche représente une recherche PartyList.

• getMaxLength
  Obtient la longueur de chaîne maximale qu’un attribut qui enregistre les données de chaîne peut avoir.

• getName
  Obtient le nom de l’attribut.

• getParent
  Obtient une référence à l’objet Xrm.Page.data.entity qui est le parent de tous les attributs.

• getUserPrivilege
  Détermine les privilèges dont dispose un utilisateur pour les champs avec la sécurité au niveau des champs.

• Méthodes relatives à l’attribut Nombre
  Utilisez les méthodes getMax, getMin et getPrecision pour accéder aux informations sur les propriétés des attributs de nombre.

• Événement OnChange
  Utilisez les méthodes addOnChange, removeOnChange et fireOnChange pour gérer les gestionnaires d’événements pour l’événement OnChange.

• RequiredLevel
  Utilisez les méthodes setRequiredLevel et getRequiredLevel pour contrôler si un attribut doit avoir une valeur pour sauvegarder un enregistrement.

• SubmitMode
  Utilisez les méthodes setSubmitMode et getSubmitMode pour contrôler si la valeur d’un attribut sera envoyée lorsqu’un enregistrement est sauvegardé.

• Valeur
  Utilisez les méthodes getValue et setValue pour déterminer les valeurs définies pour un attribut et pour modifier la valeur.

Méthodes relatives aux attributs booléens et de groupe d’options

Les méthodes getInitialValue, getOption, getOptions, getSelectedOption et getText fournissent des façons d’obtenir des informations sur les attributs Boolean ou OptionSet.

getInitialValue

Retourne une valeur qui représente l’ensemble des valeurs pour un attribut OptionSet ou Boolean lorsque le formulaire est ouvert.

Types d’attributs : groupe d’options et booléens

Xrm.Page.getAttribute(arg).getInitialValue()

• Valeur renvoyée
  Type : nombre Valeur initiale de l’attribut.

getOption

Retourne un objet d’option avec la valeur correspondant à l’argument passé à la méthode.

Types d’attributs : groupe d’options

Xrm.Page.getAttribute(arg).getOption(value)

• Arguments
  Valeur Chaîne ou Nombre

• Valeur renvoyée
  Type : objet d’option avec les propriétés text et value.

getOptions

Retourne un éventail d’objets d’option représentant les options valides pour un attribut de groupe d’options.

Types d’attributs : groupe d’options

Xrm.Page.getAttribute(arg).getOptions()

• Valeur renvoyée
  Type : variété d’objets d’option.

getSelectedOption

Retourne l’objet d’option sélectionné dans un attribut de groupe d’options.

Types d’attributs : groupe d’options

Xrm.Page.getAttribute(arg).getSelectedOption()

• Valeur renvoyée
  Type : objet d’option avec les propriétés text et value.

getText

Retourne la valeur de chaîne du texte de l’option actuellement sélectionnée pour un attribut de groupe d’options.

Types d’attributs : groupe d’options

Xrm.Page.getAttribute(arg).getText()

• Valeur renvoyée
  Type : Chaîne. Valeur text de l’option sélectionnée.

  Notes

  Si aucune option n’est sélectionnée, getText renverra une valeur de chaîne vide.

Contrôles

Voir Collections (référence côté client) pour découvrir les méthodes exposées par les collections.

Comme chaque attribut est représenté plusieurs fois sur la page, l’ensemble des contrôles donne accès à tous les contrôles représentant cet attribut. Si l’attribut est représenté par un seul champ dans la page, la longueur de cette collection sera 1. Lorsque vous utilisez la méthode getName de contrôle, le nom du premier contrôle sera le même que le nom de l’attribut. La deuxième instance d’un contrôle pour cet attribut sera « <attributeName>1 ». Le modèle <attributeName>+N continue pour chaque contrôle supplémentaire ajouté au formulaire pour un attribut spécifique.

Lorsqu’un formulaire affiche un contrôle de vidage des processus d’entreprise dans l’en-tête, les contrôles supplémentaires sont ajoutés pour chaque attribut affiché dans les flux de processus d’entreprise. Ces contrôles ont un nom unique comme suit : header_process_<attribute name>.

Lors de l’exécution d’actions sur les contrôles qui sont liés à un attribut, vous devez toujours considérer que le contrôle peut être inclus plusieurs fois sur la page, et en général vous devez effectuer les mêmes actions pour chaque contrôle de l’attribut. Vous pouvez le faire par bouclage via la collection de contrôles d’attributs et effectuer les actions sur chaque contrôle.

L’exemple suivant décrit une bibliothèque JavaScript avec deux fonctions réutilisables qui utilisent la collection de contrôles d’attribut pour masquer et afficher les contrôles :

• SDK.Sample.hideAllAttributeControls: masque tous les contrôles de l’attribut.

• SDK.Sample.showAllAttributeControls: affiche tous les contrôles de l’attribut.

if (typeof (SDK) == "undefined")
{SDK = { __namespace: true }; }
SDK.Sample = { __namespace: true };
SDK.Sample.hideAllAttributeControls = function (attributeLogicalName) {
    /// <summary>
    /// Hides all controls for the attribute.
    /// </summary>
    /// <param name="attributeLogicalName" type="String" mayBeNull="false" optional="false" >
    /// The logical name of an attribute.
    /// </param>
    if ((typeof attributeLogicalName != "string") ||
        (attributeLogicalName.length <= 3))
    { throw new Error("SDK.Sample.hideAllAttributeControls attributeLogicalName parameter must be a string at least 4 characters long."); }
    Xrm.Page.getAttribute(attributeLogicalName).controls.forEach(
        function (control, i) {
            control.setVisible(false);
            }
        );
}
SDK.Sample.showAllAttributeControls = function (attributeLogicalName) {
    /// <summary>
    /// Shows all controls for the attribute.
    /// </summary>
    /// <param name="attributeLogicalName" type="String" mayBeNull="false" optional="false" >
    /// The logical name of an attribute.
    /// </param>
    if ((typeof attributeLogicalName != "string") ||
        (attributeLogicalName.length <= 3))
    { throw new Error("SDK.Sample.showAllAttributeControls attributeLogicalName parameter must be a string at least 4 characters long."); }
    Xrm.Page.getAttribute(attributeLogicalName).controls.forEach(
        function (control, i) {
            control.setVisible(true);
            }
        );
}

Pour utiliser ces fonctions, passez le nom logique de l’attribut comme indiqué ici :

//Hide the controls for the subject attribute.
SDK.Sample.hideAllAttributeControls("subject");
//Show the controls for the subject attribute.
SDK.Sample.showAllAttributeControls("subject");

getAttributeType

Retourne une valeur de chaîne représentant le type d’attribut.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getAttributeType()

• Valeur renvoyée
  Type : Chaîne

  Cette méthode renverra une des valeurs de chaîne suivantes :

  • boolean

  • datetime

  • decimal

  • double

  • integer

  • lookup

  • memo

  • money

  • optionset

  • string

getFormat

Retourne une valeur de chaîne représentant les options de mise en forme de l’attribut.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getFormat()

• Valeur renvoyée
  Type : Chaîne

  Cette méthode renverra une des valeurs de chaîne suivantes ou null :

  • date

  • datetime

  • duration

  • email

  • language

  • none

  • phone

  • text

  • textarea

  • tickersymbol

  • timezone

  • url

Le tableau suivant répertorie les valeurs de chaîne du format à prévoir pour chaque type de schéma d’attribut et de format d’option.

Type de champ d’application	Option de format	Type d'attribut	Valeur de format
Date et heure	Date uniquement	datetime	Date
Date et heure	Date et heure	datetime	datetime
Nombre entier	Durée	integer	durée
Une seule ligne de texte	Courrier électronique	string	Courrier électronique
Nombre entier	Langue	optionset	langue
Nombre entier	Aucun(e)	integer	aucun(e)
Une seule ligne de texte	Zone de texte	string	zone de texte
Une seule ligne de texte	Texte	string	texte
Une seule ligne de texte	Symbole de l’action	string	symbole d'action
Une seule ligne de texte	Téléphone	string	Téléphone
Nombre entier	Fuseau horaire	optionset	fuseau horaire
Une seule ligne de texte	URL	string	URL

getIsDirty

Retourne la valeur booléenne indiquant s’il existe des modifications non enregistrées dans la valeur d’attribut.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getIsDirty()

• Valeur renvoyée
  Type : Booléen. True s’il y a des modifications non enregistrées, autrement False.

getIsPartyList

Retourne une valeur booléenne indiquant si la recherche représente une recherche partylist. Les recherches Partylist permettent de définir plusieurs enregistrements, comme le champ À: pour un enregistrement d’entité de courrier électronique.

Types d’attributs : recherche

Xrm.Page.getAttribute(arg).getIsPartyList()

• Valeur renvoyée
  Type : Booléen. True si l’attribut de recherche est partylist, sinon False.

• Remarques
  Cette méthode est uniquement disponible pour Entités mises à jour.

getMaxLength

Retourne un nombre indiquant la longueur maximale d’un attribut de chaîne ou de mémo.

Types d’attributs : chaîne, mémo

Xrm.Page.getAttribute(arg).getMaxLength()

• Valeur renvoyée
  Type : nombre Longueur maximale autorisée d’une chaîne pour cet attribut.

  Notes

  L’attribut description de formulaire de courrier électronique est un attribut de mémo, mais il n’a pas de méthode getMaxLength.

getName

Retourne une chaîne représentant le nom logique de l’attribut.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getName()

• Valeur renvoyée
  Type : Chaîne. Nom logique de l’attribut.

getParent

Retourne la référence à l’objet Xrm.Page.data.entity qui est le parent de tous les attributs.

Cette fonction permet de fournir une interface cohérente avec d’autres objets. Dans ce cas, comme chaque attribut renvoie le même objet, il n’existe pas de nombreux cas où il est utile.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getParent()

• Valeur renvoyée
  Type : objet Xrm.Page.data.entity.

getUserPrivilege

Retourne un objet avec trois propriétés booléennes correspondant aux privilèges indiquant si l’utilisateur peut créer, lire ou mettre à jour les valeurs de données d’un attribut. Cette fonction est destinée à être utilisée lorsque la sécurité au niveau des champs modifie les privilèges d’un utilisateur pour un attribut spécifique. Pour plus d'informations, voir Comment la sécurité de champ permet de contrôler l’accès aux valeurs des champs dans Microsoft Dynamics CRM 2015.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getUserPrivilege()

• Valeur renvoyée
  Type : Objet

  L’objet a trois propriétés booléennes :

  • canRead

  • canUpdate

  • canCreate

Méthodes relatives à l’attribut Nombre

Utilisez les méthodes getMax, getMin et getPrecision pour accéder aux informations sur les propriétés des attributs de nombre.

getMax

Retourne un nombre indiquant la valeur maximale autorisée pour un attribut.

Types d’attributs : devise, décimal, entier, double

Xrm.Page.getAttribute(arg).getMax()

• Valeur renvoyée
  Type : nombre. Valeur maximale autorisée pour l’attribut.

getMin

Retourne un nombre indiquant la valeur minimale autorisée pour un attribut.

Types d’attributs : devise, décimal, entier, double

Xrm.Page.getAttribute(arg).getMin()

• Valeur renvoyée
  Type : nombre Valeur minimale autorisée pour l’attribut.

getPrecision

Retourne le nombre de chiffres autorisés à droite de la virgule décimale.

Types d’attributs : devise, décimal, double et entier

Xrm.Page.getAttribute(arg).getPrecision()

• Valeur renvoyée
  Type : nombre. Nombre de chiffres autorisés à droite de la virgule décimale.

Événement OnChange

Il existe trois méthodes pour utiliser l’événement OnChange pour un attribut :

• addOnChange

• removeOnChange

• fireOnChange

addOnChange

Définit une fonction à appeler lorsque la valeur d’attribut est modifiée.

Xrm.Page.getAttribute(arg).addOnChange([function reference])

• Paramètre
  Type : pointeur de fonction

  Remarques : la fonction est ajoutée en bas du pipeline gestionnaire d’événements. Le contexte d’exécution est automatiquement défini pour agir comme le premier paramètre transmis au gestionnaire d’événements. Pour plus d'informations, voir Contexte d'exécution (référence côté client).

  Exemple : Dans cet exemple, la bibliothèque JScript contient deux fonctions. Ajouter la fonction addMessageToOnChange à l’événement OnLoad de formulaire ajoute la fonction displayMessage comme gestionnaire de l’événement OnChange pour le premier attribut dans le formulaire.

  function addMessageToOnChange() 
  { 
     Xrm.Page.data.entity.attributes.get(0).addOnChange(displayOrgName);
  }
  function displayOrgName(execContext) 
  { 
     Xrm.Utility.alertDialog(execContext.getContext().getOrgUniqueName()); 
  }
  

removeOnChange

Supprime une fonction de gestionnaire d’événements OnChange pour un attribut.

Xrm.Page.getAttribute(arg).removeOnChange([function reference])

• Paramètre
  Type : référence de fonction

  Exemple : Dans cet exemple, la bibliothèque JScript contient deux fonctions. Ajouter la fonction removeMessageFromOnChange à un autre événement de formulaire supprime la fonction displayOrgName comme gestionnaire de l’événement OnChange pour le premier attribut dans le formulaire.

  function removeMessageFromOnChange() 
  {
     Xrm.Page.data.entity.attributes.get(0).removeOnChange(displayOrgName);
  }
  function displayOrgName(execContext) 
  { 
     Xrm.Utility.alertDialog(execContext.getContext().getOrgUniqueName()); 
  }
  

fireOnChange

Entraîne l’événement OnChange sur l’attribut afin qu’un script associé à cet événement puisse s’exécuter.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).fireOnChange()

RequiredLevel

Vous pouvez contrôler si l’application nécessite qu’un champ contienne des données pour pouvoir sauvegarder un enregistrement. Utilisez les méthodes getRequiredLevel et setRequiredLevel pour ajuster cette condition.

getRequiredLevel

Retourne une valeur de chaîne indiquant si une valeur de l’attribut est obligatoire ou recommandée.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getRequiredLevel()

• Valeur renvoyée
  Type : Chaîne

  Retourne une des trois valeurs possibles :

  • none

  • required

  • recommended

setRequiredLevel

Définit si les données sont obligatoires ou recommandées pour l’attribut avant que les enregistrements puissent être sauvegardés.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).setRequiredLevel(requirementLevel)

• Arguments
  Type : Chaîne

  Une des valeurs suivantes :

  • none

  • required

  • recommended

SubmitMode

Vous pouvez contrôler quand les données d’un attribut sont envoyées si un enregistrement est créé ou sauvegardé. Par exemple, vous pouvez avoir un champ du formulaire qui doit uniquement contrôler la logique du formulaire. Vous n’êtes pas prêt à capturer les données dans celui-ci. Vous pouvez faire en sorte que les données ne soient pas enregistrées. Vous pouvez disposer d’un plug-in inscrit qui dépende toujours de la valeur incluse. Vous pouvez définir l’attribut afin qu’il soit toujours inclus. Les attributs qui ne sont pas mis à jour après la sauvegarde initiale de l’enregistrement, comme createdby, sont définis pour qu’ils ne soient pas envoyés lors de la sauvegarde. Pour forcer une valeur d’attribut à l’envoi, qu’elle ait changé ou non, utilisez la fonction setSubmitMode avec le paramètre en mode « toujours » défini.

Si vous utilisez setSubmitMode, trois options sont possibles :

• always : la valeur est toujours envoyée.

• never : la valeur n’est jamais envoyée. Lorsque cette option est définie, les données ne peuvent pas être modifiées pour aucun champ dans le formulaire pour cet attribut.

• dirty (par défaut) : la valeur est envoyée lors de la création si elle n’est pas null, puis lors de l’enregistrement lorsqu’elle est modifiée.

Utilisez getSubmitMode pour déterminer le paramètre en cours.

getSubmitMode

Retourne la chaîne indiquant si les données de l’attribut sont envoyées lorsque l’enregistrement est sauvegardé.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getSubmitMode()

• Valeur renvoyée
  Type : Chaîne

  Retourne une des trois valeurs possibles :

  • always

  • never

  • dirty

  La valeur par défaut pour les champs modifiables est « dirty », c’est-à-dire que la valeur est envoyée au serveur uniquement lorsqu’elle est modifiée.

setSubmitMode

Définit si les données de l’attribut sont envoyées lorsque l’enregistrement est sauvegardé.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).setSubmitMode()

• Arguments
  Type : Chaîne

  Une des valeurs suivantes :

  • always : les données sont toujours envoyées avec un enregistrement.

  • never : les données ne sont jamais envoyées avec un enregistrement. En cas d’utilisation, les champs du formulaire de cet attribut ne peuvent pas être modifiés.

  • dirty: Comportement par défaut. Les données sont envoyées avec l’enregistrement lorsqu’elles ont changé.

Valeur

L’accès et la définition de la valeur des attributs sont les actions les plus courantes dans des scripts de formulaire.

getValue

Récupère la valeur de données d’un attribut.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).getValue()

• Valeur renvoyée
  Type : Dépend du type d’attribut.

  Type d'attribut	Type renvoyé
  booléen	Booléen
  datetime	Date Pour obtenir la version de chaîne d’une date à l’aide des préférences des paramètres régionaux de l’utilisateur Microsoft Dynamics 365, utilisez les méthodes format et localeFormat. D’autres méthodes mettront les dates en forme avec des paramètres régionaux du système d’exploitation et non les préférences des paramètres régionaux Microsoft Dynamics 365 de l’utilisateur.
  décimal	Numéro
  Double	Numéro
  integer	Numéro
  recherche	Tableau Choix des objets de recherche. Notes Certaines recherches permettent de définir plusieurs enregistrements à associer dans une recherche, comme le champ À: pour un enregistrement d’entité de courrier électronique. Par conséquent, toutes les valeurs de données de recherche utilisent un éventail d’objets de recherche – même si l’attribut de recherche ne prend pas en charge plusieurs références d’enregistrement à ajouter. Chaque recherche contient les propriétés suivantes : entityType Chaîne : nom de l’entité affichée dans la recherche Id Chaîne : représentation de la chaîne de la valeur GUID d’enregistrement affichée dans la recherche. nom Chaîne : texte représentant le texte à afficher dans la recherche.
  memo	Chaîne
  devise	Numéro
  groupe d’options	Numéro
  chaîne	Chaîne

setValue

Définit la valeur de données d’un attribut.

Types d’attributs : Tous

Xrm.Page.getAttribute(arg).setValue()

• Arguments
  Dépend du type d’attribut.

  Type d'attribut	Type d’argument
  booléen	Booléen
  datetime	Date
  décimal	Numéro
  double	Numéro
  Entier	Numéro
  recherche	Tableau Choix des objets de recherche. Notes Certaines recherches, connues en tant que recherche « partylist » permettent de définir plusieurs enregistrements à associer dans une recherche, comme le champ À: pour un enregistrement d’entité de courrier électronique. Par conséquent, toutes les valeurs de données de recherche utilisent un éventail d’objets de recherche – même si l’attribut de recherche ne prend pas en charge plusieurs références d’enregistrement à ajouter. Chaque valeur de recherche contient les propriétés suivantes : entityType Chaîne : nom logique de l’entité représentée par la recherche. Id Chaîne : représentation de la chaîne de la valeur GUID d’enregistrement affichée dans la recherche. La valeur doit correspondre au format suivant : {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. nom Chaîne : texte représentant le texte à afficher dans la recherche. Généralement, l’attribut principal de l’entité. Voir Définir la valeur de l’attribut de recherche pour un exemple d’une fonction d’assistance que vous pouvez créer pour définir des valeurs d’attribut de recherche simples.
  memo	Chaîne
  devise	Numéro
  groupe d’options	Numéro Notes La méthode getOptions renvoie des valeurs d’options en tant que chaînes. Vous devez utiliser parseInt pour les convertir en nombre avant de pouvoir utiliser ces valeurs pour définir la valeur d’un attribut de groupe d’options. Les options statuscode (Raison du statut) valides dépendent du code d’état actuel de l’enregistrement. Le champ statecode (État) ne peut pas être défini dans des scripts de formulaire. Pour inclure des valeurs statecode valides, reportez-vous aux métadonnées des attributs. Voir TechNet : valeurs par défaut du statut et de la raison du statut pour obtenir la liste des valeurs par défaut des entités système. Pour les entités personnalisées, utilisez le navigateur de métadonnées de l’entité décrit dans Parcourir les métadonnées de votre organisation. Enfin, envisagez également toutes les transitions d’état personnalisées qui ont été appliquées au champ.Pour plus d'informations :TechNet : Définir les transitions de raison du statut.
  Chaîne	Chaîne Notes Un champ String avec le format de courrier électronique nécessite que la chaîne représente une adresse de messagerie valide.

Définir la valeur de l’attribut de recherche

Cet exemple présente la définition d’une fonction d’assistance setSimpleLookupValue qui définit la valeur des attributs de recherche simples.

function setSimpleLookupValue(LookupId, Type, Id, Name) {
   /// <summary>
   /// Sets the value for lookup attributes that accept only a single entity reference.
   /// Use of this function to set lookups that allow for multiple references, 
   /// a.k.a 'partylist' lookups, will remove any other existing references and 
   /// replace it with just the single reference specified.
   /// </summary>
   /// <param name="LookupId" type="String" mayBeNull="false" optional="false" >
   /// The lookup attribute logical name
   /// </param>
   /// <param name="Type" type="String" mayBeNull="false" optional="false" >
   /// The logical name of the entity being set.
   /// </param>
   /// <param name="Id" type="String" mayBeNull="false" optional="false" >
   /// A string representation of the GUID value for the record being set.
   /// The expected format is "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}".
   /// </param>
   /// <param name="Name" type="String" mayBeNull="false" optional="false" >
   /// The text to be displayed in the lookup.
   /// </param>
   var lookupReference = [];
   lookupReference[0] = {};
   lookupReference[0].id = Id;
   lookupReference[0].entityType = Type;
   lookupReference[0].name = Name;
   Xrm.Page.getAttribute(LookupId).setValue(lookupReference);
  }

Voici un exemple utilisant la fonction setSimpleLookupValue pour définir la valeur d’attribut primarycontactid sur un formulaire de compte :

setSimpleLookupValue("primarycontactid", "contact", "{6D9D4FCF-F4D3-E011-9D26-00155DBA3819}", "Brian Lamee");

Voir aussi

Référence par programmation côté client
Référence rapide des scripts de formulaires
Écrire du code pour les formulaires Microsoft Dynamics CRM 2015
Utiliser le modèle d’objet Xrm.Page

© 2017 Microsoft. Tous droits réservés. Copyright