Exploitation des données avec Lightning Data Service

<template>
    <lightning-card>
        <lightning-record-form
            object-api-name={objectApiName}
            fields={fields}
            onsuccess={handleSuccess}>
        </lightning-record-form>
    </lightning-card>
</template>

import { LightningElement } from 'lwc';
import { ShowToastEvent } from 'lightning/platformShowToastEvent';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import NAME_FIELD from '@salesforce/schema/Account.Name';
import REVENUE_FIELD from '@salesforce/schema/Account.AnnualRevenue';
import INDUSTRY_FIELD from '@salesforce/schema/Account.Industry';
export default class AccountCreator extends LightningElement {
    objectApiName = ACCOUNT_OBJECT;
    fields = [NAME_FIELD, REVENUE_FIELD, INDUSTRY_FIELD];
    handleSuccess(event) {
        const toastEvent = new ShowToastEvent({
            title: "Account created",
            message: "Record ID: " + event.detail.id,
            variant: "success"
        });
        this.dispatchEvent(toastEvent);
    }
}

import { LightningElement, api, wire } from 'lwc';
import { getRecord, getFieldValue } from 'lightning/uiRecordApi';
import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
export default class WireGetRecordProperty extends LightningElement {
    @api recordId;
    @wire(getRecord, { recordId: '$recordId', fields: [ACCOUNT_NAME_FIELD] })
    account;
    get name() {
        return getFieldValue(this.account.data, ACCOUNT_NAME_FIELD);
    }
}

<template>
  Account Name: {name}
</template>

wireGetRecordProperty est un exemple de décoration de propriété. Nous pouvons décorer une fonction de la même manière. Les décorateurs sont utiles lorsque vous souhaitez exécuter une logique sur les enregistrements renvoyés. Voici l’exemple précédent (wireGetRecordProperty) retravaillé pour lier une fonction (wiredAccount) à la place d’une propriété.

wireGetRecordFunction.js

import { LightningElement, api, wire } from 'lwc';
import { getRecord, getFieldValue } from 'lightning/uiRecordApi';
import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
export default class WireGetRecord extends LightningElement {
    @api recordId;
    data;
    error;
    @wire(getRecord, { recordId: '$recordId', fields: [ACCOUNT_NAME_FIELD] })
    wiredAccount({data, error}) {
        console.log('Execute logic each time a new value is provisioned');
        if (data) {
            this.data = data;
            this.error = undefined;
        } else if (error) {
            this.error = error;
            this.data = undefined;
        }
    }
    get name() {
        return getFieldValue(this.data, ACCOUNT_NAME_FIELD);
    }
}

Points marquants du code :

• Lignes 8 à 9 : au lieu de décorer une propriété, nous décorons la fonction wiredAccount. La fonction reçoit, en tant que paramètre, un objet qui possède deux attributs : data (données) et error (erreur). Nous utilisons la décomposition d’objet ES6 pour extraire les attributs de l’objet.
• Lignes 11 à 17 : étant donné que les adaptateurs Wire de LDS ne provisionnent pas une valeur unique, mais un flux de valeurs, il est possible d’invoquer la fonction wiredAccount plusieurs fois. En conséquence, une fonction liée doit réinitialiser les états qu’elle influence. Ainsi, aux lignes 11 à 17, si l’adaptateur Wire provisionne de nouvelles données, nous les stockons dans la propriété data et indiquons que la propriété error est non définie. En cas d’erreur, nous stockons cette dernière dans la propriété error et indiquons que la propriété data est non définie.

Dans cet exemple, nous pouvons accéder à la propriété name (nom) de la même manière que nous y avons accédé dans l’exemple précédent.

Modification des données avec les fonctions LDS

Les adaptateurs Wire de LDS sont parfaits pour lire des données, mais vous avez besoin d’une fonction LDS pour créer, mettre à jour ou supprimer des enregistrements. Notez que, bien que les adaptateurs Wire soient invoqués par le moteur des composants Lightning Web, vous devez appeler les fonctions de manière impérative. Les fonctions LDS notifient le cache LDS lorsque des enregistrements sont créés, mis à jour ou supprimés. Prenons cet exemple, qui utilise la fonction LDS createRecord pour créer un enregistrement de compte.

ldsCreateRecord.js

import { LightningElement} from 'lwc';
import { createRecord } from 'lightning/uiRecordApi';
import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import ACCOUNT_NAME_FIELD from '@salesforce/schema/Account.Name';
export default class LdsCreateRecord extends LightningElement {
    handleButtonClick() {
        const recordInput = {
            apiName: ACCOUNT_OBJECT.objectApiName,
            fields: {
                [ACCOUNT_NAME_FIELD.fieldApiName] : 'ACME'
            }
        };
        createRecord(recordInput)
            .then(account => {
                // code to execute if create operation is successful
            })
            .catch(error => {
                // code to execute if create operation is not successful
            });
    }
}

Points marquants du code :

• Ligne 2 : nous importons la fonction LDS createRecord.
• Lignes 3 à 4 : nous importons l’objet Account et le champ Account.Name (comme nous l’avons fait dans les exemples précédents) pour garantir l’intégrité des références.
• Ligne 6 : nous définissons la méthode handleButtonClick comme un gestionnaire d’événements. Elle réagit à l’événement qui se produit lorsqu’un utilisateur clique sur un bouton lightning-button dans le fichier .html (non représenté ici). Lorsque la fonction handleButtonClick est appelée, elle invoque la fonction createRecord de manière impérative.
• Ligne 10 : notre gestionnaire d’événements transmet une chaîne pour le champ Account.Name, dont l’adaptateur a besoin pour créer un compte.
• Ligne 13 : lorsque nous appelons une fonction LDS de manière impérative, celle-ci renvoie une promesse (un objet JavaScript qui simplifie l’exécution d’appels asynchrones).
• Lignes 14 à 16 : dans la méthode then, nous définissons ce qui se produit lorsque le compte est correctement créé.
• Lignes 17 à 19 : dans la méthode catch, nous définissons ce qui se produit lorsque la création du compte échoue.

Remarque :  les fonctions LDS ne vous permettent de travailler qu’avec des enregistrements uniques. Bien que vous puissiez utiliser plusieurs fonctions dans le même composant (pour créer deux types d’enregistrements différents dans la même opération, par exemple), chaque fonction s’exécute dans sa propre transaction indépendante. Par conséquent, il n’existe pas de logique de restauration commune. Si vous avez besoin qu’une opération DML combinée soit transactionnelle, envisagez d’utiliser Apex.

Pour en savoir plus sur les adaptateurs Wire et les fonctions LDS ainsi que leur utilisation, consultez le guide du développeur de composants Web Lightning et le blog des développeurs Salesforce.

Déploiement d’un composant Web Lightning de création de comptes

Maintenant que nous avons examiné différentes manières d’exploiter Lightning Data Service, passons à la pratique.

Avant de commencer

Nous partons du principe que votre environnement de développement Salesforce DX est configuré et que vous savez l’utiliser pour créer des composants Web Lightning et les déployer dans une organisation. Si vous ne maîtrisez pas encore ce processus, suivez le projet Prise en main rapide : composants Web Lightning.

Création d’un Trailhead Playground

Pour ce projet, vous devez créer un Trailhead Playground. Faites défiler la page jusqu’en bas, cliquez sur la flèche vers le bas en regard de Lancer, puis sélectionnez Créer une organisation Trailhead Playground. La création d’un Trailhead Playground prend généralement entre 3 et 4 minutes.

Remarque :  Oui, il faut vraiment un Trailhead Playground complètement nouveau ! Si vous utilisez une organisation ou un Playground existant, vous pourriez rencontrer des difficultés pour effectuer les défis.

Obtenir votre nom d'utilisateur et mot de passe Trailhead Playground

Accédez à votre Trailhead Playground. (S’il n’est pas déjà ouvert, descendez jusqu’au bas de cette page et cliquez sur Lancer.) Si vous voyez un onglet intitulé « Obtenir vos identifiants de connexion » dans votre organisation, c’est parfait ! Passez à l’étape 1. 

Sinon, depuis le lanceur d’application (), recherchez et ouvrez Playground Starter, puis laissez-vous guider. Si vous ne voyez pas l’application Playground Starter, consultez l’article Rechercher le nom d’utilisateur et le mot de passe de votre Trailhead Playground dans l’aide de Trailhead.

1. Cliquez sur l’onglet Obtenir vos identifiants de connexion et notez votre nom d’utilisateur.
2. Cliquez sur Réinitialiser mon mot de passe. Cela enverra un e-mail de réinitialisation du mot de passe à l’adresse e-mail associée à votre nom d’utilisateur.
3. Cliquez sur le lien dans l’e-mail.
4. Saisissez un nouveau mot de passe, confirmez-le, puis cliquez sur Modifier le mot de passe.

Prêt à vous lancer ? Alors allons-y !

Dans cet exercice, vous allez ajouter un composant Web Lightning à votre projet et le déployer dans votre Trailhead Playground. 

1. Créez un projet :
   1. ouvrez Visual Studio Code.
   2. Ouvrez la palette de commandes : cliquez sur Afficher | Palette de commandes.
   3. Dans la palette de commandes, sélectionnez SFDX :. créer un projet.
      Si vous ne le trouvez pas dans la liste, saisissez SFDX:Create Project (SFDX : créer un projet), puis appuyez sur Enter (Entrée).
   4. Acceptez le modèle standard.
   5. Pour le nom du projet, saisissez workingWithDataInLWC, puis appuyez sur Entrée.
   6. Sélectionnez l’emplacement du nouveau projet, puis cliquez sur Créer un projet.
2. Autorisez votre Trailhead Playground :
   1. Dans la palette de commandes, sélectionnez (ou saisissez) SFDX :. autoriser une organisation.
   2. Sélectionnez Production : login.salesforce.com et appuyez sur Entrée.
   3. Pour l’alias, saisissez lwc_and_salesforce_data, puis appuyez sur Entrée.
   4. Utilisez votre nom d’utilisateur et le mot de passe Trailhead Playground pour vous connecter.
   5. Une fois connecté à votre Trailhead Playground, laissez-le ouvert et revenez sur Visual Studio Code.
3. Créez un composant Web Lightning :
   1. dans le volet Explorateur, cliquez avec le bouton droit de la souris sur le dossier lwc et sélectionnez SFDX : création d’un composant Web Lightning.
   2. Pour le nom du composant, saisissez accountCreator et appuyez sur Entrée.
   3. Appuyez de nouveau sur Entrée pour accepter le répertoire par défaut.
4. Remplacez le contenu de vos fichiers accountCreator.html et accountCreator.js par le code fourni dans la section Lecture ou modification des données avec les composants de base du formulaire d’enregistrement plus haut dans cette unité.
5. Pour rendre ce composant accessible sur les pages d’application d’une organisation, remplacez le contenu de votre fichier accountCreator.js-meta.xml par ce code :
   

   <?xml version="1.0" encoding="UTF-8"?>
   <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
       <apiVersion>48.0</apiVersion>
       <isExposed>true</isExposed>
       <targets>
           <target>lightning__AppPage</target>
       </targets>
   </LightningComponentBundle>

6. Enregistrez les trois fichiers : accountCreator.html, accountCreator.js et accountCreator.js-meta.xml.
7. Déployez les fichiers de projet dans votre Trailhead Playground. (Cliquez avec le bouton droit de la souris sur le dossier accountCreater et sélectionnez SFDX : déployer la source dans l’organisation.)
8. Si votre Trailhead Playground n’est pas déjà ouvert, ouvrez-le. (Dans la palette de commandes, sélectionnez (ou saisissez) SFDX : ouvrir l’organisation par défaut.)
9. Dans votre Trailhead Playground, cliquez sur , puis sélectionnez Configuration.
10. Dans la zone Recherche rapide, saisissez Générateur d’applications Lightning, puis sélectionnez Générateur d’applications Lightning.
11. Créez une page Lightning :
    1. Cliquez sur Nouveau.
    2. Sélectionnez Page d’application, puis cliquez sur Suivant.
    3. Pour le libellé, saisissez Working with Data, puis cliquez sur Suivant.
    4. Pour la présentation, choisissez En-tête et menu latéral gauche.
    5. Cliquez sur Terminer.
12. Faites glisser le composant accountCreator vers le menu latéral de la page.
13. Enregistrez la page.
14. Activez la page : conservez le nom de l’application par défaut (Working with Data) et cliquez sur Enregistrer.
15. Lorsque vous êtes invité à ajouter la page au menu de navigation, cliquez sur Terminer.
16. Ouvrez la nouvelle page : dans la zone de recherche du lanceur d’application, saisissez work, puis sélectionnez Working with Data.

Voilà ! Vous disposez d’un composant Web Lightning qui utilise lightning-record-form pour créer des enregistrements de compte sur la page Working with Data. L’utilisation de Lightning Data Service est une façon d’exploiter les données Salesforce dans les composants Web Lightning. Dans l’unité suivante, vous apprendrez à exploiter les données avec Apex.

Ressources

• Guide du développeur de composants Web Lightning : Lightning Data Service
• Guide du développeur de composants Web Lightning : Exploitation des enregistrements dans les composants de base
• Guide du développeur de composants Web Lightning : Utilisation du service Wire pour obtenir des données
• Blog : Mise en cache et synchronisation des données de composants avec Lightning Data Service