Partager via

Écrire votre premier script client

Prêt à écrire votre premier script client pour voir le résultat ? Commençons. Nous allons faire simple.

Objectif

Une fois cette procédure pas à pas terminée, vous savez comment utiliser du code JavaScript dans des applications basées sur des modèles. Ce processus implique les étapes générales suivantes :

  • Localiser ou créer une solution à laquelle ajouter votre travail
  • Écrire votre code JavaScript pour résoudre un problème métier
  • Télécharger votre code en tant que ressource Web
  • Associer votre ressource Web à un formulaire
  • Configurer les événements de formulaire et de champ
  • Tester votre code

Étape 1 : Localiser ou créer une solution

Utilisez des solutions pour transporter des personnalisations d’un environnement à un autre. Écrivez et testez votre code JavaScript dans un environnement de développement dans le cadre d’une solution non managée. Lorsque vous avez terminé le test, exportez la solution en tant que solution managée et importez-la ou installez-la dans votre environnement de production.

Une solution existante pourrait déjà être disponible pour vous. L’application pilotée par modèle que vous souhaitez personnaliser avec votre script doit déjà faire partie d’une solution. Vous pouvez modifier cette solution ou créer une solution qui dépend d’une autre solution existante.

Pour créer une solution

  1. Accéder à Power Apps.

  2. Dans le volet de navigation de gauche, sélectionnez Solutions, puis sélectionnez Nouvelle solution.

  3. Dans la fenêtre contextuelle, entrez un nom d’affichage, un nom et un éditeur.

    La plupart des entreprises ont un éditeur existant qu’ils utilisent toujours. Utilisez cet éditeur. Si vous êtes la première personne, créez votre propre éditeur.

    Sélectionnez Nouveau serveur de publication pour ouvrir la boîte de dialogue Nouveau serveur de publication . Dans cette procédure pas à pas, utilisez un éditeur avec cette définition :

    Formulaire pour créer un nouvel éditeur avec des informations pour Example Publisher

    Notez la valeur Préfixe. Cette valeur doit identifier votre entreprise. Dans ce cas, utilisez example.

    Cette solution est celle que vous utilisez dans cette procédure pas à pas.

    Formulaire de solution pour la première solution de script client

  4. Localisez ou ajoutez une application pilotée par modèle à votre solution.

    Une nouvelle solution n’inclut aucune application basée sur des modèles. Vous devez ajouter une application basée sur des modèles existante ou en créer une nouvelle.

    Note

    Pour les besoins de cette procédure pas à pas, assurez-vous que l’application inclut la table Compte. Les scripts et instructions ci-dessous utilisent les champs présents dans un formulaire pour la table Compte.

    Option A : Ajouter une application pilotée par modèle existante à votre solution

    1. Dans votre solution, sélectionnez Ajouter>Applicaton existante>Application pilotée par modèle.

    Ajouter une application pilotée par modèle existante

    1. Sélectionnez une application existante, puis sélectionnez Ajouter.

    Option B : Créer une application pilotée par modèle dans votre solution

    Dans votre solution, sélectionnez Nouvelle>application basée sur un modèle d’application>.

    Voir le didacticiel Générer votre première application pilotée par modèle Créez une application qui inclut la table des Comptes.

Étape 2 : écrire votre code JavaScript

La première étape consiste à identifier le problème métier que vous souhaitez résoudre à l’aide de scripts clients. Lorsque vous identifiez le problème, écrivez votre code JavaScript contenant la logique métier personnalisée qui répond à votre problème métier.

Les applications basées sur des modèles ne fournissent pas d’éditeur JavaScript. Utilisez un outil de création externe qui offre des fonctionnalités spécifiques pour l'édition des fichiers JavaScript, tels que Notepad++, Visual Studio Code ou Microsoft Visual Studio.

Cette procédure pas à pas utilise le code JavaScript suivant :

// A namespace defined for the sample code
// As a best practice, you should always define 
// a unique namespace for your libraries
var Example = window.Example || {};
(function () {
    // Define some global variables
    var myUniqueId = "_myUniqueId"; // Define an ID for the notification
    var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
    var message = currentUserName + ": Your JavaScript code in action!";

    // Code to run in the form OnLoad event
    this.formOnLoad = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // Display the form level notification as an INFO
        formContext.ui.setFormNotification(message, "INFO", myUniqueId);

        // Wait for 5 seconds before clearing the notification
        window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);
    }

    // Code to run in the column OnChange event 
    this.attributeOnChange = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // Automatically set some column values if the account name contains "Contoso"
        var accountName = formContext.getAttribute("name").getValue();
        if (accountName.toLowerCase().search("contoso") != -1) {
            formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
            formContext.getAttribute("telephone1").setValue("425-555-0100");
            formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
        }
    }

    // Code to run in the form OnSave event 
    this.formOnSave = function () {
        // Display an alert dialog
        Xrm.Navigation.openAlertDialog({ text: "Record saved." });
    }
}).call(Example);

Copiez ce code dans un fichier texte et enregistrez-le sous Example-form-script.js.

Explication détaillée du code

Voyons en détail le code :

  • Définir l’espace de noms : le code commence par définir un espace de noms pour votre script personnalisé. En guise de meilleure pratique, créez toujours des bibliothèques JavaScript avec espace de noms pour éviter que vos fonctions ne se substituent aux fonctions d’une autre bibliothèque.

    var Example = window.Example || {};

    Dans ce cas, vous pouvez utiliser toutes les fonctions définies dans cette bibliothèque en tant que Example.[functionName]. Choisissez un espace de noms qui correspond au nom de votre éditeur de solution.

  • Définir des variables globales : la section suivante définit certaines variables globales à utiliser dans le script. Vous pouvez accéder aux informations de contexte globalement à l’aide de la méthode Xrm.Utility.getGlobalContext .

    // Define some global variables
var myUniqueId = "_myUniqueId"; // Define an ID for the notification
var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
var message = currentUserName + ": Your JavaScript code in action!";

  • Fonction à exécuter sur l’événement OnLoad : cette section contient la fonction qui s’exécute lorsque le formulaire de compte se charge. Par exemple, lorsque vous créez un enregistrement de compte ou lorsque vous ouvrez un enregistrement de compte existant.

    La fonction Example.formOnLoad utilise le paramètre executionContext pour obtenir l’objet formContext. Lorsque vous attachez votre code à l’aide de l’événement de formulaire ultérieurement, sélectionnez l’option permettant de passer le contexte d’exécution à cette fonction.

    Cette fonction affiche une notification au niveau du formulaire à l’aide de la méthode formContext.ui.setFormNotification .

    Ensuite, cette fonction utilise la méthode setTimeOut JavaScript pour retarder l’exécution de la méthode formContext.ui.clearFormNotification pour supprimer la notification après 5 secondes.

    // Code to run in the form OnLoad event
this.formOnLoad = function (executionContext) {
    var formContext = executionContext.getFormContext();

    // Display the form level notification as an INFO
    formContext.ui.setFormNotification(message, "INFO", myUniqueId);

    // Wait for 5 seconds before clearing the notification
    window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);        
}

  • Fonction à exécuter sur l’événement OnChange : associez la fonction à la Example.attributeOnChange colonne Nom du compte dans le formulaire de compte afin qu’elle soit exécutée uniquement lorsque vous modifiez la valeur du nom du compte.

    Cette fonction effectue une recherche insensible à la casse pour Contoso dans le name du compte et, le cas échéant, définit automatiquement les valeurs des colonnes websiteurl, telephone1 et description du formulaire de compte.

    // Code to run in the column OnChange event 
this.attributeOnChange = function (executionContext) {
    var formContext = executionContext.getFormContext();

    // Automatically set some column values if the account name contains "Contoso"
    var accountName = formContext.getAttribute("name").getValue();
    if (accountName.toLowerCase().search("contoso") != -1) {
        formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
        formContext.getAttribute("telephone1").setValue("425-555-0100");
        formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
    }
}

  • Fonction à exécuter sur l’événement OnSave : la Example.formOnSave fonction affiche une boîte de dialogue d’alerte à l’aide de la méthode Xrm.Navigation.openAlertDialog . Cette boîte de dialogue affiche un message avec un bouton OK. L’utilisateur peut fermer l’alerte en sélectionnant OK.

    Note

    Cette fonction n’utilise pas le contexte d’exécution, car les méthodes Xrm.Navigation ne le nécessitent pas.

    // Code to run in the form OnSave event 
this.formOnSave = function () {
    // Display an alert dialog
    Xrm.Navigation.openAlertDialog({ text: "Record saved." });
}

Étape 3 : Télécharger votre code en tant que ressource Web

Maintenant que votre code est prêt, chargez-le dans votre solution.

  1. Dans votre solution, sélectionnez Nouvelle>ressource Web>.

    Ajoutez une nouvelle ressource web à votre solution

  2. Dans la boîte de dialogue Nouvelle ressource web , sélectionnez Choisir un fichier et sélectionnez le Example-form-script.js fichier que vous avez enregistré précédemment.

  3. Entrez le nom d’affichage, le nom et éventuellement une description. Assurez-vous que le champ Type est défini sur JavaScript (JS).

    Nouvelle boîte de dialogue de ressource Web pour créer un exemple de script de formulaire

    Note

    • Le nom a un préfixe qui correspond au préfixe de personnalisation de l’éditeur de solution. Il existe d’autres façons de créer des ressources web, mais la création d’une ressource web garantit que la ressource web fait partie de votre solution.
    • Le nom de la ressource Web est example_example-form-script.

Étape 4 : Associez votre ressource Web à un formulaire

  1. Dans votre solution, sélectionnez Objets>Applications>Votre application et cliquez sur Modifier.

    Modifier l’application dans la solution

  2. Développez Compte et sélectionnez le formulaire de compte. Cliquez sur les points de suspension (...) à droite du formulaire Informations , puis sélectionnez Modifier.

    Modifier le formulaire des informations sur le compte

  3. Dans le volet de navigation de gauche, sélectionnez Bibliothèques de formulaires et cliquez sur Ajouter une bibliothèque.

    Ajoute une bibliothèque au formulaire

  4. Dans la boîte de dialogue Ajouter une bibliothèque JavaScript, recherchez la ressource Web JavaScript que vous avez créée par son nom : Example Script.

    Boîte de dialogue Ajouter une bibliothèque JavaScript

  5. Sélectionnez la ressource web Example de script et cliquez sur Ajoutez.

Étape 5 : Configurer les événements de formulaire et de champ

  1. Sélectionnez l’onglet Événements.

    Gestionnaires d’événements de formulaire

Configurer le formulaire lors de l'événement "On Load"

  1. Sélectionnez le gestionnaire d’événements En charge et cliquez sur + Gestionnaire d’événements.

    Configurer le gestionnaire au chargement du formulaire

    Vérifiez que les paramètres suivants sont corrects :

    • Le Type d’événement est En charge.
    • La bibliothèque example_example-form-script est sélectionnée.
    1. Saisissez le nom de la fonction dans le champ Fonction. Dans ce cas, entrez Example.formOnLoad.
    2. Sélectionnez Transmettre le contexte d’exécution comme premier paramètre.
    3. Cliquez sur Terminé.

Configurer le formulaire sur l'événement de sauvegarde

  1. Sélectionnez le gestionnaire d’événements On Save , puis sélectionnez + Gestionnaire d’événements.

    Configurer le gestionnaire de l’événement d’enregistrement du formulaire

    Vérifiez que les paramètres suivants sont corrects :

    • Le Type d’événement est En cours d’enregistrement.
    • La bibliothèque example_example-form-script est sélectionnée.
    1. Saisissez le nom de la fonction dans le champ Fonction. Dans ce cas, entrez Example.formOnSave.

      Note

      Vous n’avez pas besoin de sélectionner Le contexte d’exécution pass comme premier paramètre pour cette fonction, car il ne l’utilise pas.

    2. Cliquez sur Terminé.

Configurer l’événement de modification du champ

  1. Sélectionnez le champ Nom de compte et l’onglet Événements.

    Sélectionner les événements du champ Nom du compte

  2. Sélectionnez le gestionnaire d’événements Modification en cours et cliquez sur + Gestionnaire d’événements.

    Configurer le gestionnaire d’événement OnChange pour le champ

    Vérifiez que les paramètres suivants sont corrects :

    • Le Type d’événement est En cours de modification.
    • La bibliothèque example_example-form-script est sélectionnée.
    1. Saisissez le nom de la fonction dans le champ Fonction. Dans ce cas, Example.attributeOnChange.
    2. Sélectionnez Transmettre le contexte d’exécution comme premier paramètre.
    3. Cliquez sur Terminé.

Enregistrer et publier vos changements

Enregistrez le formulaire, puis cliquez sur Publier.

Étape 6 : Tester votre code

Actualisez votre navigateur pour vous assurer que vos modifications prennent effet dans votre instance d’applications basées sur des modèles.

Pour tester votre code :

  1. Accéder à Power Apps.

  2. Dans le volet de navigation gauche, sélectionnez Applications.

  3. Ouvrez l’application basée sur un modèle que vous venez de modifier, ou sélectionnez-la, puis sélectionnez Exécuter.

    Ouvrir l’application à tester

Tester la fonction de chargement du formulaire

  1. Sélectionnez un enregistrement de compte dans la liste pour l’ouvrir.

  2. Vérifiez que la notification s’affiche.

    Notification de chargement du formulaire

  3. Vérifiez que la notification disparaît dans 5 secondes.

Tester la fonction de modification du champ

  1. Modifiez le nom du compte pour ajouter « Contoso »dans le nom et passez à la colonne suivante en appuyant sur la touche TAB.

  2. Vérifiez les valeurs attendues définies pour les colonnes Téléphone principal, Site web et Description.

    Valeurs définies lors de la modification du champ

Tester la fonction d’enregistrement du formulaire

  1. Cliquez sur Enregistrer.

  2. Vérifiez que la boîte de dialogue d’alerte affiche le message que vous avez configuré dans votre code.

    Boîte de dialogue d’alerte lors de l’enregistrement du formulaire

  3. Sélectionnez OK pour fermer l’alerte.

Déboguer le code JavaScript pour les applications pilotées par modèle
Événements dans les formulaires et les grilles des applications basées sur un modèle
Événement OnLoad du formulaire
Événement de sauvegarde du formulaire (référence de l’API client) dans les applications basées sur un modèle
Événement OnChange de colonne (référence de l’API client)

  • Last updated on