Transmettre des données à partir d’une page en tant que paramètre des actions du ruban

Notes

Cette rubrique concerne les commandes classiques.

Il existe une nouvelle façon de définir les commandes. Voir Vue d’ensemble du commandement moderne (Version préliminaire)

Lorsque vous définissez une action dans un ruban, vous devez souvent transmettre des données de la page vers une fonction JavaScript ou une URL. Cet article décrit les options disponibles pour utiliser l’élément <CrmParameter> pour récupérer ces valeurs.

Contexte de formulaire et de grille dans les actions du ruban

Pour transmettre des informations de contexte d’exécution (contexte de formulaire ou contexte de grille) à la fonction JavaScript pour vos actions du ruban, spécifiez PrimaryControl pour le contexte du formulaire ou SelectedControl pour le contexte de la grille en tant que valeur <CrmParameter> de vos définition du ruban. SelectedControl passera dans le contexte de grille, pour les sous-grilles et les grilles de la page d’accueil. La valeur passée dans PrimaryControl ou SelectedControl est utilisée en tant qu’argument de votre fonction JavaScript pour le contexte de formulaire ou le contexte de grille respectivement.

Par exemple, voici une exemple de définition du ruban où nous transmettons le paramètre PrimaryControl à la fonction JavaScript :

<CommandDefinition Id="SampleCommand">
  <EnableRules/>
  <DisplayRules/>
  <Actions>
    <JavaScriptFunction Library="$webresource:new_mySampleScript.js" FunctionName="mySampleFunction">
      <CrmParameter Value="PrimaryControl" />
    </JavaScriptFunction>
  </Actions>
</CommandDefinition>

Ensuite, dans le fichier de ressource web new_mySampleScript.js référencé dans l’exemple précédent, définissez votre fonction JavaScript avec la variable primaryControl en tant qu’argument. Cet argument fournit le contexte de formulaire en fonction de l’emplacement où la commande de ruban est exécutée :

function mySampleFunction(primaryControl) {
    var formContext = primaryControl;
    // Perform operations using the formContext object
}

Vous pouvez également spécifier CommandProperties en tant que valeur <CrmParameter> dans votre définition du ruban concernant les détails de l’événement du contrôle de ruban. Vous pouvez l’utiliser pour envoyer des informations contextuelles à une fonction JavaScript dans laquelle des actions spécifiques peuvent être déterminées selon le contexte de l’événement.

Notes

L’obtention du contexte de formulaire et du contexte de grille pour les fonctions Javascript pour des actions de ruban est différente de la manière dont vous obtenez ces valeurs dans les scripts de formulaire. Pour plus d’informations sur les scripts de formulaire et comment obtenir ces contextes, voir Contexte de formulaire de l’API client et Contexte de grille de l’API client.

Valeurs du formulaire

Avec un ruban de formulaire, vous pouvez utiliser la collection data.entity.attributs et la collection ui.contrôles pour récupérer et définir les valeurs des colonnes connues.

Par exemple, l’exemple de code suivant montre comment récupérer la colonne de nom du compte dans le formulaire du compte, puis comment définir une valeur dans la colonne websiteurl selon la valeur du nom du compte :

function mySampleFunction(primaryControl) {
    var formContext = primaryControl;    
    var accountName = formContext.getControl("name").getAttribute().getValue();    

    // Set the WebSiteURL column if account name contains "Contoso"
    if (accountName.toLowerCase().search("contoso") != -1) {
        formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
    }
    else {
        Xrm.Navigation.openAlertDialog({ text: "Account name does not contain 'Contoso'." });
    }
}

Valeurs de la grille

La majorité des valeurs disponibles pour l’élément <CrmParameter> sont liées à l’utilisation des données affichées dans une grille ou un organigramme hiérarchique. En utilisant les options d’énumération du paramètre Value, vous pouvez facilement isoler les éléments par :

• Éléments sélectionnés

  • SelectedControlSelectedItemCount

  • SelectedControlSelectedItemIds

  • SelectedControlSelectedItemReferences

• Tous les éléments

  • SelectedControlAllItemCount

  • SelectedControlAllItemIds

  • SelectedControlAllItemReferences

• Éléments non sélectionnés

  • SelectedControlUnselectedItemCount

  • SelectedControlUnselectedItemIds

  • SelectedControlUnselectedItemReferences

  Pour chacun de ces groupements, vous pouvez collecter le nombre d’éléments et l’identificateur GUID. Si vous transmettez les valeurs à une URL, vous pouvez également récupérer les objets EntityReference qui contiennent toutes les informations nécessaires pour identifier de manière unique les objets de la grille. Ces paramètres s’appliquent que la page affichée soit la grille principale (HomepageGrid) ou une sous-grille située dans un formulaire. Lorsqu’ils sont utilisés avec le paramètre SelectedEntityTypeName, vous disposez de toutes les informations nécessaires pour passer à une autre application.

Autres informations sur le contexte

Outre les valeurs des données, vous pouvez récupérer des informations de contexte client à l’aide de <CrmParameter>. Vous pouvez utiliser les options suivantes comme valeur de l’élément CrmParameter : OrgName, OrgLcid et UserLcid.

Pour une action <Url>, vous pouvez également utiliser le paramètre PassParams pour inclure les informations contextuelles.

Les options PrimaryEntityTypeName et FirstPrimaryItemId de Value fournissent des informations pour un enregistrement de table. Vous pouvez utiliser PrimaryItemIds pour un ruban HomepageGrid pour obtenir la liste de tous les éléments affichés.

Voir aussi

Personnaliser le ruban
Transmission des paramètres vers une URL à l’aide du ruban
Définir les actions du ruban
Définir les actions personnalisées pour modifier le ruban
Contexte de formulaire de l’API client
Contexte de grille de l’API client

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é).