Compréhension d'un exemple d'application hybride

Observons l’exemple d’application ContactExplorer, qui figure dans le kit de développement mobile. ContactExplorer est une application locale hybride qui présente plus de fonctionnalités que le modèle d’application. Vous pouvez réaliser cet exercice sur un Mac OS ou sous Windows, mais vous devez utiliser un Mac pour valider entièrement la cible iOS.

Pour commencer, clonez le référentiel partagé, puis créez une application avec forcehybrid.

1. Dans une invite de commande ou une fenêtre de terminal, utilisez la commande cd pour accéder au répertoire dans lequel vous prévoyez de cloner le référentiel partagé.
2. Exécutez la commande suivante :

   git clone https://github.com/forcedotcom/SalesforceMobileSDK-Shared.git

3. Utilisez la commande cd pour accéder au répertoire dans lequel vous prévoyez de développer votre projet hybride.
4. Exécutez forcehybrid create avec les valeurs suivantes :

   Enter the target platform(s) separated by commas (ios, android): ios,android
   Enter your application type (hybrid_local or hybrid_remote, leave empty for hybrid_local): <press RETURN>
   Enter your application name: contactsApp
   Enter the package name for your app (com.mycompany.myapp): com.acmeapps.contactexplorer
   Enter your organization name (Acme, Inc.): AcmeApps.com
   Enter output directory for your app (leave empty for the current directory): <press RETURN>

   Maintenant que vous disposez d’un projet hybride générique, vous pouvez lui ajouter l’exemple de code contactexplorer.
5. Exécutez les commandes suivantes, en faisant en sorte de bien remplacer l’espace réservé dans la commande cp par votre chemin local.

   cd contactsApp
   cordova plugin add cordova-plugin-contacts
   cordova plugin add cordova-plugin-statusbar
   cordova plugin remove com.salesforce
   cordova plugin add https://github.com/forcedotcom/SalesforceMobileSDK-CordovaPlugin --force
   cp -RL <local path to SalesforceMobileSDK-Shared>/samples/contactexplorer/* www/
   cordova prepare

   Utilisateurs de Windows : Sous Windows, remplacez la commande Unix cp par la commande copy. Gardez toutefois à l’esprit que les fichiers des sous-dossiers js et css de /samples/contactexplorer/ sont des alias de fichiers sources situés sur d’autres chemins. Assurez-vous que vous copiez les fichiers source eux-mêmes, et non leurs alias. Voici un exemple :

   cd contactsApp
     cordova plugin add cordova-plugin-contacts
     cordova plugin add cordova-plugin-statusbar
     cordova plugin remove com.salesforce
     cordova plugin add https://github.com/forcedotcom/SalesforceMobileSDK-CordovaPlugin --force
     rem Make a path variable
     set SHAREDPATH=C:\SalesforceMobileSDK-Shared\
     md www
     cd www
     md css
     copy %SHAREDPATH%\samples\common\jquery.mobile-1.3.1.min.css css
     md js
     copy %SHAREDPATH%\test\MockCordova.js js
     copy %SHAREDPATH%\libs\cordova.force.js js
     copy %SHAREDPATH%\libs\force.js js
     copy %SHAREDPATH%\dependencies\jquery\jquery.min.js js
     copy %SHAREDPATH%\samples\common\jquery.mobile-1.3.1.min.js js
     cordova prepare

   
   

Le script forcedroid et les commandes qui s’ensuivent créent un projet iOS et un projet Android, les deux englobant l’exemple d’application ContactExplorer. Vous êtes désormais prêt à exécuter votre application sur l'une de ces plates-formes. Si vous utilisez un appareil iOS, vous devez configurer un profil pour le simulateur, tel que décrit dans le Xcode User Guide à l’adresse developer.apple.com/library. De même, les appareils Android doivent être configurés de la manière décrite sur developer.android.com/tools.

Lorsque vous exécutez l'application, l'écran de connexion Salesforce s'affiche après l'écran de bienvenue initial.

Connectez-vous avec le nom d'utilisateur et le mot de passe de votre organisation Developer Edition. Pour permettre à l’application d’accéder à vos données Salesforce, touchez Autoriser. Vous êtes maintenant dans l’application, vous pouvez récupérer les listes de contacts et de comptes. Touchez Extraire les contacts SFDC pour récupérer les noms des contacts Salesforce ou Extraire les comptes SFDC pour récupérer les noms des comptes de votre organisation DE.

À chaque fois que vous appuyez sur une touche, l'application ajoute des lignes à une liste infinie. Faites défiler vers le bas pour afficher la liste complète.

Examinons de plus près le fonctionnement de l'application.

1. Dans le projet contactsApp, ouvrez le fichier www/index.html.
2. Recherchez « function onDeviceReady() ».

Pour démarrer une session utilisateur avec force.js, vous devez appeler force.login(). Lorsque l’utilisateur est connecté à une application exécutée dans le conteneur, si nécessaire, le plug-in de la communauté actualise les jetons lorsque l’application tente d’accéder aux ressources de Salesforce. Le code suivant, adapté à l’exemple ContactExplorer, montre une implémentation typique de force.login().

Lorsque l’appareil indique qu’il est prêt, vous appelez la méthode force.login() pour publier l’écran de connexion.

/* Do login */
force.login(
    function() {
        console.log("Auth succeeded"); 
        // Call your app’s entry point
        // ...
    },
    function(error) {
        console.log("Auth failed: " + error); 
    }
);

Après avoir terminé le processus de connexion, l’exemple d’application affiche index.html (situé dans le dossier www). Une fois le chargement de la page terminé et l’infrastructure mobile prête, la fonction jQuery(document).ready() appelle regLinkClickHandlers(). La fonction (dans inline.js) configure des gestionnaires de clics pour les diverses fonctions de l’exemple d’application. Par exemple, le gestionnaire #link_fetch_sfdc_contacts exécute une requête en utilisant l’objet force.

$j('#link_fetch_sfdc_contacts').click(function() {
    logToConsole("link_fetch_sfdc_contacts clicked");
    force.query("SELECT Name FROM Contact LIMIT 25", 
        onSuccessSfdcContacts, onErrorSfdc); 
});

L’objet force est configuré lors de la première interaction OAuth 2.0 et permet d’accéder à l’API REST dans le contexte de l’utilisateur authentifié. Ici, nous récupérons les noms de tous les contacts de l’organisation DE. La fonction onSuccessSfdcContacts() restitue ensuite les contacts sous forme de liste sur la page index.html.

$j('#link_fetch_sfdc_accounts').click(function() {
    logToConsole("link_fetch_sfdc_accounts clicked");
    force.query("SELECT Name FROM Account LIMIT 25", 
        onSuccessSfdcAccounts, onErrorSfdc); 
});

Tout comme pour le gestionnaire #link_fetch_sfdc_contacts, le gestionnaire #link_fetch_sfdc_accounts extrait des enregistrements de compte via l’API REST. Les gestionnaires #link_reset et #link_logout effacent les listes affichées et déconnectent l’utilisateur, respectivement.

Notez que l'application peut également récupérer les contacts de l'appareil, ce qu'une application Web équivalente serait incapable de faire. Le gestionnaire de clics suivant récupère la requête de contacts de l'appareil en appelant le plug-in de contacts Cordova.

$j('#link_fetch_device_contacts').click(function() {
    logToConsole("link_fetch_device_contacts clicked");
    var options      = new ContactFindOptions();
    // empty search string returns all contacts
    options.filter   = ""; 
    options.multiple = true;
    options.hasPhoneNumber = true;
    var fields       = 
        [navigator.contacts.fieldType.displayName, 
            navigator.contacts.fieldType.name];
    navigator.contacts.find(fields, onSuccessDevice, 
        onErrorDevice, options);
});

Ce gestionnaire utilise les objets ContactFindOptions et navigator.contacts de cordova-plugin-contacts pour affiner une recherche et l’exécuter. Il appelle navigator.contacts.find() pour récupérer depuis l’appareil une liste de contacts contenant des numéros de téléphone. La fonction onSuccessDevice() (non représentée ici) restitue la liste de contacts dans la page index.html.

La bibliothèque force.js

<!-- include force.js for REST transaction support -->
<script src="js/force.js"></script>

Lorsque vous chargez la bibliothèque force.js, elle crée un objet force global. Cet objet est le point d’entrée de la fonctionnalité de la bibliothèque. Comme indiqué précédemment, la fonction salesforceSessionRefreshed utilise l’instance force pour passer des appels réseau tels que force.query().

Cette présentation a été courte, mais riche en contenus. D’autres widgets d’interface utilisateur de l’application ContactExplorer ont un comportement similaire à ceux que nous venons d’évoquer. Pendant votre temps libre, nous recommandons d’étudier le code aussi bien dans index.html que dans inline.js pour parfaire votre compréhension. En attendant, nous poursuivre notre découverte des interactions hybrides avec Salesforce. Intéressé(e) ? Sans aucun doute !