9.8. Trabajar con formularios en Drupal. Añadir un formulario de configuración mediante programación.

En este tutorial, trabajaremos con la API de Formularios de Drupal y crearemos un formulario de configuración para el módulo. Ya hemos creado módulos para mostrar una página y un bloque, ahora crearemos un formulario de configuración en el que almacenaremos datos para conectarnos a un servicio externo. Supongamos que necesitamos almacenar la API Key y el API Client ID en el sitio, por ejemplo, para usar la API de Google Maps.

Ejemplos de código disponibles en GitHub:
https://github.com/levmyshkin/drupalbook8

Podemos guardar esta información en el archivo settings.php y agregarla a git, pero no sería seguro. Es mejor guardar los accesos a servicios en la base de datos.

Agreguemos una nueva ruta para nuestro formulario:

modules/custom/drupalbook/drupalbook.routing.yml

drupalbook.settings:
  path: '/admin/structure/drupalbook/settings'
  defaults:
    _form: '\Drupal\drupalbook\Form\DrupalbookSettingsForm'
    _title: 'Formulario de configuración de DrupalBook'
  requirements:
    _permission: 'administer site configuration'

A diferencia de las rutas anteriores, aquí especificamos _form en lugar de _controller. Vamos a crear una clase de formulario. Creamos el archivo:

modules/custom/drupalbook/src/Form/DrupalbookSettingsForm.php

Debes crear la carpeta Form dentro de src. Esto permite organizar mejor el código.

Contenido del archivo:

<?php

namespace Drupal\drupalbook\Form;

use Drupal\Core\Form\ConfigFormBase;
use Drupal\Core\Form\FormStateInterface;

/**
 * Configura los ajustes del módulo DrupalBook.
 */
class DrupalbookSettingsForm extends ConfigFormBase {

  public function getFormId() {
    return 'drupalbook_admin_settings';
  }

  protected function getEditableConfigNames() {
    return [
      'drupalbook.settings',
    ];
  }

  public function buildForm(array $form, FormStateInterface $form_state) {
    $config = $this->config('drupalbook.settings');

    $form['drupalbook_api_key'] = [
      '#type' => 'textfield',
      '#title' => $this->t('API Key'),
      '#default_value' => $config->get('drupalbook_api_key'),
    ];

    $form['drupalbook_api_client_id'] = [
      '#type' => 'textfield',
      '#title' => $this->t('API Client ID'),
      '#default_value' => $config->get('drupalbook_api_client_id'),
    ];

    return parent::buildForm($form, $form_state);
  }

  public function submitForm(array &$form, FormStateInterface $form_state) {
    $this->configFactory->getEditable('drupalbook.settings')
      ->set('drupalbook_api_key', $form_state->getValue('drupalbook_api_key'))
      ->set('drupalbook_api_client_id', $form_state->getValue('drupalbook_api_client_id'))
      ->save();

    parent::submitForm($form, $form_state);
  }
}

El formulario hereda de ConfigFormBase, lo que permite guardar datos en el sistema de configuración. El ID del formulario debe ser único, y se recomienda iniciarlo con el nombre del módulo.

El método buildForm() construye el formulario. Usamos la API de Formularios de Drupal para definir campos. Documentación:
https://api.drupal.org/api/drupal/elements/8.5.x

También puedes utilizar campos de tipo select, checkboxes, radios, etc. Intenta agregarlos al formulario como práctica.

El método submitForm() guarda los datos en la configuración usando configFactory->getEditable() y set(), luego save(). También puedes personalizar el mensaje de éxito:

// parent::submitForm($form, $form_state);
drupal_set_message($this->t('¡La configuración fue guardada correctamente!'));

Después de crear el formulario, limpia la caché y visita la ruta configurada para ver tu formulario en acción.

Para acceder a los valores guardados desde cualquier parte del código:

$config = \Drupal::config('drupalbook.settings');
$api_key = $config->get('drupalbook_api_key');
$api_client_id = $config->get('drupalbook_api_client_id');

Este código funcionará en cualquier módulo o función preprocess.

En la próxima lección sobre formularios veremos cómo crear formularios de múltiples pasos.

Ejemplos de código disponibles en GitHub:
https://github.com/levmyshkin/drupalbook8