Projet : application Amphibians

1. Avant de commencer

Attention : Cet atelier de programmation est obsolète et sa mise à jour n'est plus assurée. Reportez-vous au cours Principes de base d'Android avec Compose pour connaître les dernières pratiques recommandées.

Cet atelier de programmation présente une nouvelle application appelée Amphibiens, que vous allez créer vous-même. Il explique les différentes étapes à suivre pour mener à bien le projet d'application Amphibiens, y compris sa configuration et ses tests dans Android Studio.

Conditions préalables

• Ce projet est destiné aux utilisateurs qui ont terminé le module 4 du cours sur les bases d'Android en Kotlin.

Objectifs de l'atelier

• Implémenter la mise en réseau dans une application à l'aide de Retrofit et Moshi et la gestion appropriée des erreurs

Ce dont vous avez besoin

• Un ordinateur sur lequel est installé Android Studio

2. Présentation de l'application terminée

Bienvenue dans le projet Amphibians.

Jusqu'à présent, toutes les applications que vous avez créées reposaient sur des données stockées localement. Cette fois, vous allez utiliser une application qui affiche des informations sur différentes espèces d'amphibiens et utiliser vos connaissances en matière de mise en réseau, d'analyse JSON et de modèles de vue pour permettre à l'application d'exploiter les données provenant du réseau. Les données de l'application seront extraites d'une API personnalisée pour ce projet et affichées sous forme de liste.

Dans l'application finale, le premier écran que verra l'utilisateur affiche le nom de chaque espèce dans une vue recycleur.

Appuyez sur un élément de la liste pour accéder à l'écran de détails, qui affiche également le nom de l'espèce ainsi qu'une description détaillée.

Bien que la partie UI de cette application soit déjà créée pour vous, l'exécution du projet de départ n'affiche aucune donnée. Vous devrez implémenter la partie réseau de l'application, puis afficher les données téléchargées dans la mise en page.

3. Premiers pas

Télécharger le code du projet

Notez que le nom du dossier est android-basics-kotlin-amphibians-app. Sélectionnez ce dossier lorsque vous ouvrez le projet dans Android Studio.

URL du code de démarrage :

https://github.com/google-developer-training/android-basics-kotlin-amphibians-app/tree/main

Nom de la branche avec code de démarrage : main

Pour obtenir le code de cet atelier de programmation et l'ouvrir dans Android Studio, procédez comme suit :

Obtenir le code

1. Cliquez sur l'URL indiquée. La page GitHub du projet s'ouvre dans un navigateur.
2. Sur la page GitHub du projet, cliquez sur le bouton Code pour afficher une boîte de dialogue.

3. Dans la boîte de dialogue, cliquez sur le bouton Download ZIP (Télécharger le fichier ZIP) pour enregistrer le projet sur votre ordinateur. Attendez la fin du téléchargement.
4. Recherchez le fichier sur votre ordinateur (il se trouve probablement dans le dossier Téléchargements).
5. Double-cliquez sur le fichier ZIP pour le décompresser. Un dossier contenant les fichiers du projet est alors créé.

Ouvrir le projet dans Android Studio

1. Lancez Android Studio.
2. Dans la fenêtre Welcome to Android Studio (Bienvenue dans Android Studio), cliquez sur Open an existing Android Studio project (Ouvrir un projet Android Studio existant).

Remarque : Si Android Studio est déjà ouvert, sélectionnez l'option de menu File > New > Import Project (Fichier > Nouveau > Importer un projet).

3. Dans la boîte de dialogue Import Project (Importer un projet), accédez à l'emplacement du dossier du projet décompressé. Il se trouve probablement dans le dossier Téléchargements.
4. Double-cliquez sur le dossier de ce projet.
5. Attendez qu'Android Studio ouvre le projet.
6. Cliquez sur le bouton Run (Exécuter) pour créer et exécuter l'application. Assurez-vous qu'elle fonctionne correctement.
7. Parcourez les fichiers du projet dans la fenêtre de l'outil Projet pour voir comment l'application est configurée.

Implémenter le service d'API

Comme dans les projets précédents, la majeure partie de l'application est déjà implémentée pour vous. Il vous suffit de mettre en œuvre la partie réseau à l'aide des connaissances que vous avez acquises dans le module 4. N'hésitez pas à vous familiariser avec le code de démarrage. Vous devriez déjà connaître la plupart des concepts qui sont issues des modules 1 à 3. Les étapes suivantes exploitent des parties spécifiques du code, le cas échéant.

L'application affichera une liste de données provenant du réseau sur les amphibiens. Les données sur les amphibiens découleront d'un objet JSON renvoyé par l'API. Examinez le fichier Amphibian.kt dans le package network. Cette classe modélisera un objet amphibien unique dont une liste sera renvoyée par l'API. Chaque amphibien possédera trois propriétés : un nom, un type et une description.

data class Amphibian(
    val name: String,
    val type: String,
    val description: String
)

Le backend de cette API est assez simple. Pour accéder aux données sur les amphibiens, vous devez fournir deux informations clés : une URL de base et un point de terminaison afin d'obtenir la liste des amphibiens.

1. URL de base : https://developer.android.com/courses/pathways/android-basics-kotlin-unit-4-pathway-2/
2. Instruction GET pour obtenir la liste des amphibiens : android-basics-kotlin-unit-4-pathway-2-project-api.json

Conseil : Vous pouvez afficher le fichier JSON brut dans votre navigateur.

Le projet inclut déjà les dépendances Retrofit et Moshi. Le fichier AmphibianApiService.kt se trouve dans le package network. Il contient plusieurs commentaires TODO. Effectuez les cinq tâches suivantes pour implémenter l'application Amphibians :

1. Créez une variable pour stocker l'URL de base de l'API.
2. Créez l'objet Moshi avec une fabrique d'adaptateurs Kotlin que Retrofit utilisera pour analyser JSON.
3. Créer une instance Retrofit à l'aide du convertisseur Moshi.
4. Implémentez l'interface AmphibianApiService avec une fonction suspend pour chaque méthode d'API (pour cette application, il n'existe qu'une seule méthode pour obtenir la liste des amphibiens).
5. Créez un objet AmphibianApi pour exposer un service Retrofit initialisé à grande échelle qui utilise l'interface AmphibianApiService.

Astuce : Si vous avez besoin de rafraîchir vos connaissances, consultez la section Connexion à Internet.

Implémenter le ViewModel

Une fois votre API implémentée, vous enverrez la requête à l'API Amphibians et stockerez toutes les valeurs à afficher. Vous procéderez dans la classe AmphibianViewModel.kt du package ui.

Vous remarquerez qu'au-dessus de la déclaration de classe figure une énumération appelée AmphibianApiStatus.

enum class AmphibianApiStatus {LOADING, ERROR, DONE}

Les trois valeurs possibles (LOADING, ERROR et DONE) permettent d'indiquer l'état de la demande envoyée à l'utilisateur.

Dans la classe AmphibianViewModel.kt proprement dite, vous devez implémenter certaines variables LiveData, une fonction permettant d'interagir avec l'API, et une fonction permettant de définir l'amphibien sur l'écran de détails.

1. Ajoutez _status et une variable MutableLiveData privée pouvant contenir une énumération AmphibianApiStatus et une propriété sous-jacente status pour l'état.
2. Ajoutez une variable amphibians et une propriété de sauvegarde privée _amphibians pour la liste des amphibiens, de type List<Amphibian>.
3. Ajoutez une variable _amphibian de type MutableLiveData<Amphibian> et une propriété sous-jacente amphibian pour l'objet amphibien sélectionné, de type LiveData<Amphibian>. Cela permettra de stocker l'amphibien sélectionné affiché sur l'écran de détails.
4. Définissez une fonction appelée getAmphibianList(). Lancez une coroutine à l'aide de ViewModelScope. Dans la coroutine, exécutez une demande GET pour télécharger les données sur les amphibiens en appelant la méthode getAmphibians() du service Retrofit. Vous devez utiliser try et catch pour traiter les erreurs de manière appropriée. Avant d'envoyer la demande, définissez la valeur de _status sur AmphibianApiStatus.LOADING. Une demande fructueuse devrait définir _amphibians sur la liste des amphibiens à partir du serveur, et définir _status sur AmphibianApiStatus.DONE. En cas d'erreur, _amphibians devrait être défini sur une liste vide, et _status sur AmphibianApiStatus.ERROR.
5. Implémentez la méthode onAmphibianClicked() pour définir la propriété _amphibian que vous avez définie sur l'argument "amphibian" transmis dans la fonction. Cette méthode est déjà appelée lorsqu'un amphibien est sélectionné, de sorte qu'il s'affiche sur l'écran de détails.

Conseil : Comme pour les autres classes ViewModel que vous avez définies, vous devez utiliser les types LiveData et MutableLiveData de manière appropriée.

Mettre à jour l'UI à partir de ViewModel

Après avoir implémenté le ViewModel, il ne vous reste plus qu'à modifier les classes de fragment et les fichiers de mise en page pour utiliser les liaisons de données.

1. Le ViewModel est déjà référencé dans AmphibianListFragment. Dans la méthode onCreateView(), après le gonflement de la mise en page, il suffit d'appeler la méthode getAmphibianList() à partir de ViewModel.
2. Dans fragment_amphibian_list.xml, les balises <data> des variables de liaison de données ont déjà été ajoutées aux fichiers de mise en page. Il vous suffit d'implémenter les actions à effectuer pour l'interface utilisateur en fonction du modèle de vue. Définissez les liaisons appropriées pour listData et apiStatus.
3. Dans fragment_amphibian_detail.xml, implémentez les actions à effectuer afin de définir les propriétés de texte appropriées pour le nom et la description de l'amphibien.

4. Instructions de test

Exécuter vos tests

Pour exécuter les tests, vous pouvez effectuer l'une des opérations suivantes.

Pour un scénario de test unique, ouvrez une classe de scénario de test et cliquez sur la flèche verte à gauche de la déclaration de classe. Vous pouvez ensuite sélectionner l'option "Run" (Exécuter) dans le menu. Tous les tests seront exécutés dans le scénario de test.

Souvent, il suffit d'exécuter un seul test, par exemple lorsqu'un test a échoué et que tous les autres ont réussi. Il est possible d'exécuter un seul test de la même manière que vous le feriez pour un scénario de test complet. Utilisez la flèche verte et sélectionnez l'option Exécuter.

Si vous avez plusieurs scénarios de test, vous pouvez également exécuter l'ensemble de la suite de tests. Comme pour l'exécution de l'application, cette option se trouve dans le menu Exécuter.

Notez qu'Android Studio utilise par défaut la dernière cible que vous avez exécutée (applications, cibles de test, etc.). Par conséquent, si le menu indique toujours Run > Run 'app' (Exécuter > Exécuter 'application'), vous pouvez exécuter la cible de test en sélectionnant Run > Run (Exécuter > Exécuter).

Sélectionnez ensuite la cible de test dans le menu pop-up.

Les résultats des tests sont affichés dans l'onglet Exécuter. Dans le volet de gauche, la liste des tests ayant échoué s'affiche, le cas échéant. Les échecs sont signalés par un point d'exclamation rouge à côté du nom de la fonction. Les tests réussis sont marqués d'une coche verte.

Conseil : Pour afficher les tests qui ont réussi ou ceux qui ont échoué, ou les deux, dans le volet de gauche, vous pouvez utiliser les deux boutons situés dans l'angle supérieur gauche. Sélectionnez la coche pour afficher les tests réussis, ou l'icône en forme de cercle barré pour afficher la liste des tests qui ont échoué. Par défaut, seuls les tests ayant échoué sont présentés.

Si un test échoue, la sortie textuelle vous fournit des informations pour vous aider à résoudre le problème sous-jacent.

Par exemple, dans le message d'erreur ci-dessus, le test vérifie si une vue TextView utilise une ressource de chaîne spécifique. Cependant, le test échoue. Le texte situé après "Expected" (Attendu) et "Got" (Reçu) ne correspond pas, ce qui signifie que la valeur attendue par le test ne correspond pas à la valeur de l'application en cours d'exécution. Dans cet exemple, la chaîne utilisée dans TextView n'est pas squeeze_count dans la réalité, comme ce que le test s'attend à voir.