Proyecto: App de Amphibians

1. Antes de comenzar

En este codelab, se presenta una nueva app llamada Amphibians, que compilarás por tu cuenta. En él, seguirás los pasos necesarios para completar el proyecto de la app de Amphibians, incluidas la configuración del proyecto y las pruebas en Android Studio.

Requisitos previos

• Este proyecto es para usuarios que completaron la unidad 4 del curso Aspectos básicos de Android en Kotlin.

Qué compilarás

• Implementarás las herramientas de redes en una app con Retrofit y Moshi, y procesarás los errores de forma adecuada.

Requisitos

• Una computadora que tenga Android Studio instalado

2. Descripción general de la app finalizada

Te damos la bienvenida al proyecto Amphibians.

Hasta este momento, todas las apps que compilaste dependían de los datos almacenados de manera local. En este caso, trabajarás con una app que muestra información sobre distintas especies de anfibios y usarás tus conocimientos de las herramientas de redes, el análisis de JSON y los modelos de vista a fin de permitir que la app use datos de la red. La app obtendrá sus datos de una API personalizada para este proyecto y los mostrará en una vista de lista.

En la app final, la primera pantalla que verá el usuario mostrará los nombres de cada especie en una vista de reciclador.

Si presionas un elemento de la lista, se navega a la pantalla de detalles que también muestra el nombre de la especie, así como una descripción detallada.

Si bien la parte de la IU de esta app ya está compilada para ti, cuando ejecutes el proyecto de inicio, no se mostrarán datos. Deberás implementar la parte de herramientas de redes de la app y, luego, mostrar los datos descargados en el diseño.

3. Cómo comenzar

Descarga el código del proyecto

Ten en cuenta que el nombre de la carpeta es android-basics-kotlin-amphibians-app. Selecciona esta carpeta cuando abras el proyecto en Android Studio.

Para obtener el código necesario para este codelab y abrirlo en Android Studio, haz lo siguiente:

Obtén el código

1. Haz clic en la URL proporcionada. Se abrirá la página de GitHub del proyecto en un navegador.
2. En esa página, haz clic en el botón Code, que abre un cuadro de diálogo.

3. En el cuadro de diálogo, haz clic en el botón Download ZIP para guardar el proyecto en tu computadora. Espera a que se complete la descarga.
4. Ubica el archivo en tu computadora (probablemente en la carpeta Descargas).
5. Haz doble clic en el archivo ZIP para descomprimirlo. Se creará una carpeta nueva con los archivos del proyecto.

Abre el proyecto en Android Studio

1. Inicia Android Studio.
2. En la ventana Welcome to Android Studio, haz clic en Open an existing Android Studio project.

Nota: Si Android Studio ya está abierto, selecciona la opción de menú File > New > Import Project.

3. En el cuadro de diálogo Import Project, navega hasta donde se encuentra la carpeta de proyecto descomprimido (probablemente en Descargas).
4. Haz doble clic en la carpeta del proyecto.
5. Espera a que Android Studio abra el proyecto.
6. Haz clic en el botón Run para compilar y ejecutar la app. Asegúrate de que funcione como se espera.
7. Explora los archivos del proyecto en la ventana de herramientas Project para ver cómo se configuró la app.

Implementa el servicio de la API

Al igual que en los proyectos anteriores, la mayor parte de la app ya se puso en marcha. Solo deberás implementar la parte de las herramientas de redes mediante lo que aprendiste en la unidad 4. Familiarízate con el código de partida. Ya deberías conocer la mayoría de los conceptos vistos en las unidades 1 a 3. En los siguientes pasos, se indican partes específicas del código cuando resulte necesario a fin de completar cada paso.

La app muestra una lista de datos de anfibios de la red. Estos datos provienen de un objeto JSON que muestra la API. Consulta el archivo Amphibian.kt en el paquete red. Esta clase modela un solo objeto anfibio, y la API mostrará una lista de estos. Cada anfibio tendrá tres propiedades: un nombre, un tipo y una descripción.

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

El backend para esta API es bastante simple. Existen dos datos clave que necesitarás para acceder a la información de los anfibios: una URL base y un extremo con el fin de obtener la lista de anfibios.

1. URL base: https://developer.android.com/courses/pathways/android-basics-kotlin-unit-4-pathway-2/
2. Envía una solicitud GET para la lista de anfibios: android-basics-kotlin-unit-4-pathway-2-project-api.json

El proyecto ya tiene las dependencias de Retrofit y Moshi. En el paquete red, encontrarás el archivo AmphibianApiService.kt. El archivo contiene varios comentarios TODO. Realiza las siguientes cinco tareas a fin de implementar la app de anfibios:

1. Crea una variable para almacenar la URL base de la API.
2. Compila el objeto Moshi con la fábrica del adaptador de Kotlin que Retrofit usará con el propósito de analizar JSON.
3. Crea una instancia de Retrofit mediante el convertidor de Moshi.
4. Implementa la interfaz AmphibianApiService con una función suspend para cada método de API (en esta app, solo hay uno: GET obtiene la lista de anfibios).
5. Crea un objeto AmphibianApi con el fin de exponer un servicio de Retrofit inicializado de forma diferida que usa la interfaz AmphibianApiService.

Implementa ViewModel

Una vez que se implemente tu API, realizarás la solicitud a la API de anfibios y almacenarás los valores que deban mostrarse. Lo harás en la clase AmphibianViewModel.kt, que se encuentra en el paquete IU.

Notarás que, encima de la declaración de la clase, hay una enumeración llamada AmphibianApiStatus.

enum class AmphibianApiStatus {LOADING, ERROR, DONE}

Los tres valores posibles, LOADING, ERROR y DONE, se usan para mostrarle al usuario el estado de la solicitud.

En la clase AmphibianViewModel.kt, deberás implementar algunas variables LiveData, una función para interactuar con la API y una función que controle mostrar el anfibio en la pantalla de detalles.

1. Agrega un _status, una variable MutableLiveData privada que pueda contener una enumeración AmphibianApiStatus y la propiedad de copia de seguridad status para el estado.
2. Agrega una variable amphibians y una propiedad de copia de seguridad privada _amphibians para la lista de anfibios, del tipo List<Amphibian>.
3. Agrega una variable _amphibian del tipo MutableLiveData<Amphibian> y la propiedad de copia de seguridad amphibian para el objeto anfibio seleccionado de tipo LiveData<Amphibian>. Este se usará a fin de almacenar el anfibio seleccionado que se muestra en la pantalla de detalles.
4. Define una función llamada getAmphibianList(). Lanza una corrutina mediante ViewModelScope, dentro de la corrutina, realiza una solicitud GET para descargar los datos de anfibios llamando al método getAmphibians() del servicio Retrofit. Deberás usar try y catch a los efectos de corregir los errores de forma adecuada. Antes de realizar la solicitud, establece el valor de _status en AmphibianApiStatus.LOADING. Una solicitud correcta debe establecer el elemento _amphibians en la lista de anfibios del servidor y el _status en AmphibianApiStatus.DONE. En caso de que se produzca un error, se deberá establecer _amphibians en una lista vacía y el elemento _status en AmphibianApiStatus.ERROR.
5. Implementa el método onAmphibianClicked() con el fin de establecer la propiedad _amphibian que definiste en el argumento del anfibio que se pasó a la función. Cuando se selecciona un anfibio, se llama a este método, de modo que se mostrará en la pantalla de detalles.

Actualiza la IU desde ViewModel

Después de implementar ViewModel, lo único que queda por hacer es editar las clases de fragmentos y los archivos de diseño para usar las vinculaciones de datos.

1. Ya se hace referencia a ViewModel en AmphibianListFragment. En el método onCreateView(), después del aumento del diseño, simplemente llama al método getAmphibianList() desde ViewModel.
2. En fragment_amphibian_list.xml, las etiquetas <data> para las variables de vinculación de datos ya se agregaron a los archivos de diseño. Solo tienes que implementar los elementos TODO de modo que la IU se actualice en función del modelo de vista. Configura las vinculaciones apropiadas para listData y apiStatus.
3. En fragment_amphibian_detail.xml, implementa los elementos TODO a fin de configurar las propiedades del texto adecuadas para el nombre y la descripción del anfibio.

4. Instrucciones para pruebas

Cómo realizar las pruebas

Para ejecutar las pruebas, puedes realizar una de las siguientes acciones:

Si se trata de un solo caso de prueba, abre una clase de caso de prueba y haz clic en la flecha verde que está a la izquierda de la declaración de la clase. Luego, puedes seleccionar la opción Run en el menú. Se ejecutarán todas las pruebas del caso de prueba.

Lo más probable es que quieras ejecutar una sola prueba, por ejemplo, si hay una sola prueba fallida y las otras aprueban. Puedes ejecutar una sola prueba como lo harías con todo el caso de prueba. Usa la flecha verde y selecciona la opción Run.

Si tienes varios casos de prueba, también podrás ejecutar todo el conjunto. Al igual que cuando ejecutas la app, encontrarás esta opción en el menú Run.

Ten en cuenta que Android Studio usará, de forma predeterminada, el último objetivo que ejecutaste (app, objetivos de prueba, etc.), por lo que, si el menú sigue indicando Run > Run 'app', podrás ejecutar el objetivo de prueba seleccionando Run > Run.

Luego, selecciona el objetivo de prueba en el menú emergente.

Se muestran Los resultados de la ejecución de las pruebas en la pestaña Run. En el panel de la izquierda, verás una lista de las pruebas fallidas, si hay. Se marcan las pruebas fallidas con un signo de exclamación rojo junto al nombre de la función, mientras que las que aprueban tienen una marca de verificación verde.

Si una prueba falla, la salida de texto proporcionará información que te ayudará a solucionar el problema.

Por ejemplo, en el mensaje de error anterior, la prueba verifica si un objeto TextView usa un recurso de strings específico. Sin embargo, la prueba falla. El texto que sigue a "Expected" y el que sigue a "Got" no coinciden, lo que significa que el valor que la prueba esperaba no coincide con el valor de la app en ejecución. En este ejemplo, la string que se utiliza en el objeto TextView no es squeeze_count, como espera la prueba.