Ahora que ya conocemos los principios básicos acerca del proceso de conexión y consumo de datos desde una API externa en Drupal, vamos a poner en práctica lo aprendido, Creando un módulo personalizado con Drush.
Conexión con API externa en Drupal 10.
Paso 1 - Generar un módulo personalizado
El primer paso para lograr la conexión entre Drupal y un API externa, será generar un módulo personalizado, donde iremos añadiendo toda la estructura necesaria. Para ello, abriremos nuestra consola y ejecutaremos el siguiente comando de Drush:
drush gen module
A continuación, contestaremos a las preguntas básicas que nos irán apareciendo en la consola, hasta finalizar el proceso.
Paso 2- Crear página de confirmación
Para este ejercicio, además de conectarnos con la API JSON, vamos a mostrar al usuario los datos descargados, con esto, podremos hacerno una idea, de cómo ampliar otras funcionalidades, como la creación de todos los registros dentro de la base de datos de Drupal. Con este propósito, a continuación, y utilizando el mismo módulo personalizado que acabamos de generar, crearemos un contrlador con su respectiva página, para ello ejeuctaremos otra opción de Drush gen:
drush gen controller
En esta ocasión, seleccionaremos todas las opciones por defecto, así podremos activar nuestro módulo y comprobar que todo funciona correctamente, antes de incluir los cambios finales.
Ahora es el turno de generar la página donde mostremos la inforamción, una vez realizada la conexión. Esta vez, ejecutaremos el siguiente comando de Drush:
drush gen template
Seleccionaremos todas las opciones por defecto y sólo añadiremos un nombre de plantilla. (confirmation-data)
Paso 3 - Primeras comprobaciones
Ya hemos creado nuestro módulo personalizado, así que antes de comenzar a añadir el resto de configuraciones, comprobaremos que todo funciona correctamente. Para ello, activaremos el módulo desde la interfaz de Drupal o mediante consola y a continuación visitaremos la página, cuya url encontraemos dentro del archivo routing.yml.
Conectándonos a la API
Para este ejemplo, vamos a utilizar la API cat-facts, está muy bien documentada y te servirá para hacer pruebas de conexión entre Drupal y ella.
Actualizando datos dentro del Controller
En este ejemplo, la idea es que tengas todas las herramientas necesarias, para que pueda crear tu propio módulo personalizado y conectarte con una API JSON real, por esta razón no entraremos en detalles. No obstante te he añadido comentarios en cada uno de los cambios a realizar, que podrás copiar y pegar, y una vez comprobado y entendido el proceso, sabrás dónde y cómo realizar el resto de cambios, hasta que vayas ganando experiencia.
El primero de los archivos que actualizaremos será el Controller ApiConnectorController.php, que es dónde realizaremos el trabajo más importante, conectarnos con la API y recuperar los datos para luego pasarlos a la plantilla.
Así que, lo próximo que deberás hacer, si has seguido todos los pasos anteriores, será COPIAR Y PEGAR el siguiente código:
<?php declare(strict_types = 1);
namespace Drupal\api_connector\Controller;
use Drupal\Component\Serialization\Json;
use Drupal\Core\Controller\ControllerBase;
use GuzzleHttp\Exception\GuzzleException;
/**
* Returns responses for Api connector routes.
*/
class ApiConnectorController extends ControllerBase {
/**
* Builds the response.
* @throws GuzzleException
*/
public function getData(): array {
$client = \Drupal::httpClient();
$request = $client->get(
"https://cat-fact.herokuapp.com/facts" // Url de API JSON
);
$response = $request->getBody()->getContents();
$results = Json::decode($response);
$data = $results;
//ksm($data);
// Descomentar para comprobar valores (Debes tener módulo Devel activado)
//https://drupaladicto.com/curso/programacion-drupal/contenidos-de-prueba-generados-con-el-modulo-devel
$build['content'] = [
'#theme' => 'confirmation_data', //Coloca el nombre de tu plantilla declarada en .module
'#data' => $data, //Esta es la encargada de pasar todos los valores recuperados a la plantilla.
'#title' => t('Data from External JSON API') //Este es un título adicional que podrás personalizar y mostrar en la plantilla.
];
return $build;
}
}
Explicación sobre los cambios en el Controller
Lo más relevante que deberás tomar en cuenta, dentro del Controller, son las líneas donde se realiza la conexión, que es donde hemos añadido la url a la que nos conectaremos.
$request = $client->get( "https://cat-fact.herokuapp.com/facts" // Url de API JSON );
Además, hemos añadido el método getData(), para que tenga más coherencia con nuestro ejemplo, sustituyendo al __invoke(), que nos genera Drush automáticamente cuando creamos el módulo mediante el uso de comandos; por esta razón, tendremos que añadirlo dentro de nuestro archivo routing.
También encontrarás la línea que te permitirá comprobar los valores recibidos, que está comentada, para que no te muestre nada si no lo necesitas. El objetivo es que una vez sustituidos todos los valores necesarios en cada archivo, si descomentas esta línea, te mostrará en la página, todos los datos con su respectiva estructura. Para habilitarlo, borrar las dos líneas inclidadas a la izquierda de ksm. (También necesitarás haber descargado y activado el módulo Devel)
//ksm($data);
Actualizando datos en el .module
El siguiente archivos que actualizaremos será el api_connector.module, donde comentaremos la parte del código que no vamos a necesitar para este ejemplo y actualizaremos el hook_theme, para poder mostrar en la plantilla el título y los valores recuperados desde la API JSON.
Si has seguido todos los pasos anteriores, podrás COPIAR Y PEGAR el siguiente código:
<?php declare(strict_types = 1);
/**
* @file
* Primary module hooks for API Connector module.
*/
/**
* Implements hook_theme().
*/
function api_connector_theme(): array {
return [
'confirmation_data' => [
'variables' => ['data' => [], 'title' => '' ] //Hemos sustituido esta línea con los nuevos valores que mostremos en Twig.
],
];
}
///**
// * Prepares variables for confirmation-data.html.twig template.
// *
// * Default template: confirmation-data.html.twig.
// *
// * @param array $variables
// * An associative array containing:
// * - foo: Foo variable description.
// */
//function template_preprocess_confirmation_data(array &$variables): void {
// $variables['foo'] = 'bar';
//}
Actualizando la plantilla
Ahora que hemos realizado el resto de cambios en .module y en el controlador, es el turno de añadir una pocas líneas que nos permitirán ver en pantalla, los datos extraidos desde la API JSON. Como he dicho al principio del ejemplo, esta es una guía básica, para que puedas comenzar y continuar practicando y perfeccionando, en función de las necesidades de tu proyecto.
En este caso, los datos no se guardan en Drupal, pero gracias a que estamos mostrándolos dentro de una plantilla Twig, nos permite aplicar algunso filtros como el |upper, que aplica mayúsculas al texto relacionado con el tipo de animal.
Si has seguido todos los pasos anteriores, podrás COPIAR Y PEGAR el siguiente código dentro de tu plantilla:
{#
/**
* @file
* Default theme implementation to display confirmation_data.
*
* Available variables:
* - foo: Foo variable description.
*
* @see template_preprocess_confirmation_data()
*
* @ingroup themeable
*/
#}
<div class="wrapper-class">
{# Con esta línea recuparamos el título personalizado #}
<h2>{{ title }}</h2>
<ul>
{# {{ foo }}#}
{% for item in data %}
<li>{{ item.text }} - <strong>{{ item.type|upper }}</strong></li>
{% endfor %}
</ul>
</div>
Explicación de los cambios
En esta plantilla, podrás imprimir el resto de valores extraidos, que verás en la parte superior, si descomentas la línea //ksm del Controller, añadiendo punto (.), después de la variable item, seguido del nombre del dato que quieres mostrar.
Actualizando el routing
Como hemos mencionado anteriormente, al añadir el método getData(), dentro de nuestro Controller, tendremos que especificar su llamada, en el archivo routing.yml, para que Drupal pueda llamarlo y mostar los datos relacionados dentro de nuestra plantilla.
api_connector.example:
path: '/api-connector/example'
defaults:
_title: 'Example'
_controller: '\Drupal\api_connector\Controller\ApiConnectorController::getData'
requirements:
_permission: 'access content'
Con este ejemplo, ya cuentas con las herramientas necesarias, para conectarte desde Drupal, hacia una API JSON externa y mostrar los datos recibidos, dentro de una plantilla, que podrás personalizar. En próximos artículos, abordaremos otros temas, como la manera de guardar los datos en Drupal y/o, mostrarlos dentro de una vista.
Hasta la próxima.