Creación de plantillas Twig personalizadas para un módulo personalizado

La idea general en Drupal 8 es que quieres evitar crear HTML directamente en el código PHP de tu módulo personalizado. Quieres que esto se maneje en las plantillas Twig. Para crear nuevas plantillas Twig en tu módulo, sigue estos pasos.

Paso 1: Define hook_theme en el archivo .module
Crea el archivo [módulo].module si aún no existe, y añade el código que define cada una de tus plantillas Twig. La clave de cada elemento en el array es lo que necesitarás para llamar a la plantilla más adelante. No uses guiones en el nombre del archivo.

function test_twig_theme($existing, $type, $theme, $path) {
  return [
    'my_template' => [
      'variables' => ['test_var' => NULL],
    ],
  ];
}

Consulta la documentación para hook_theme().

Paso 2: Llamar a la plantilla
En el lugar donde devuelves tu arreglo renderizable (desde un método de controlador que es llamado desde el archivo yml de rutas de tu módulo o en cualquier otro lugar), llama a la plantilla Twig. A continuación, un ejemplo de un módulo de prueba llamado desde un archivo de rutas yml del módulo (se necesita más información para esta parte).

/**
 * @file
 * Contains \Drupal\test_twig\Controller\TestTwigController.
 */
 
namespace Drupal\test_twig\Controller;
 
use Drupal\Core\Controller\ControllerBase;
 
class TestTwigController extends ControllerBase {
  public function content() {
 
    return [
      '#theme' => 'my_template',
      '#test_var' => $this->t('Test Value'),
    ];
 
  }
}

También puedes usar el método de renderizado para construir la salida si necesitas usarlo como parte de otro flujo de trabajo en tu código:

$renderable = [
  '#theme' => 'my_template',
  '#test_var' => 'test variable',
];
$rendered = \Drupal::service('renderer')->renderPlain($renderable);

Ten en cuenta que esta es una implementación básica que no realiza ningún almacenamiento en caché. Los documentos Render API Overview contienen información adicional sobre cómo puedes añadir caché a esto. Hablando de caché: los nombres de variables serán cacheados, y si los cambias (por ejemplo, de «test_var» a «my_var»), tendrás que actualizar el caché.

Paso 3: Crear la plantilla Twig
Dentro de tu módulo, en la carpeta de plantillas, crea la plantilla Twig. El nombre del archivo debe coincidir con lo que definiste en hook_theme() (reemplaza guiones bajos por guiones). En este caso, el nombre del archivo será my-template.html.twig.
Aquí está el archivo que usé para probar:

<p>¡Plantilla Twig de prueba!</p>
 
<p>test_var: {{ test_var }}</p>

Lo bueno es que el archivo de plantilla definido en tu módulo será usado si no existe un archivo equivalente en tu tema. Simplemente coloca el archivo en la carpeta de plantillas de tu tema, limpia la caché (drush cache-rebuild), y Drupal usará ese archivo.

Puedes colocar el archivo en cualquier subcarpeta dentro de la carpeta de plantillas de tu tema para mantener todo organizado.