Instrucciones para convertir Drupal Twig (tpl.php a html.twig)

Este documento se utilizó durante la mayor parte del proceso de conversión a Twig para Drupal 8 y también puede ser útil para que actualices tus propios temas y módulos para usar el motor de plantillas Twig en Drupal 8.

Nota: todo el trabajo con Twig ahora se realiza en la cola de problemas del núcleo de Drupal. Usa únicamente el sandbox de conversión Twig para encontrar plantillas y funciones ya convertidas.

Pasos para los principales participantes:

• Encuentra los problemas principales para publicar y revisar correcciones.
• No apliques parches al sandbox.
• No crees parches para el sandbox.
• Usa el sandbox solo para probar y/o obtener código previamente convertido.
• Mira este video en YouTube para una visión general de este proceso.

Configuración

Clonar Drupal 8.0.x:

git clone -b 8.0.x http://git.drupal.org/project/drupal.git d8

La versión de trabajo actual de Drupal se instalará en la carpeta "d8" (puedes nombrarla como quieras)

1. Instala Drupal como de costumbre (usando el perfil de instalación Estándar).
2. Configura los 3 ajustes de Twig (debugging, cache, auto_reload) a True en services.yml.

Conversión

Funciones de tema

Convierte la función de tema a un archivo de plantilla y a una función de preprocesamiento:

1. Identifica el archivo de donde proviene tu función de tema (¿theme.inc? ¿Core/modules/color/?)
2. Crea un archivo de plantilla X.html.twig para la función de tu tema:
                     - Nombra tu nuevo archivo acorde
                     - Elimina el prefijo theme_ del nombre de tu función y termina el nombre del archivo con .html.twig
                     - Convierte los guiones bajos (“_”) en guiones (“-”).
                     - Ejemplos:
                                * theme_link() se convierte en link.html.twig
                                * theme_user_signature() se convierte en user-signature.html.twig

3. Coloca tu nueva plantilla Twig en la carpeta de plantillas dentro del tema completo (en el sandbox):
                     - para funciones que vienen de un módulo específico, como stark/templates/comment, etc.
                     - para funciones que vienen de theme.inc, usa stark/templates/theme.inc
                     - para funciones que vienen de form.inc, usa stark/templates/form.inc
4. Consulta la documentación en API Drupal 8 y busca tu función.
                     - (hay enlaces a todas las funciones en la hoja de cálculo)
5. Añade un bloque de documentación al estilo PHP en la parte superior del archivo y envuélvelo en comentarios Twig {# #}
                     - Añade la línea @file en la parte más alta.
                     - Copia la definición de la función justo debajo de la línea @file. Reescribe “Devuelve HTML ...” como “Implementación de tema por defecto ...”. Reescríbelo para que esté en una sola línea.
                     - Añade la línea “Variables disponibles:” (sustituye las variables @param)
                     - Copia las variables listadas en la sección “Parámetros” de la documentación en api.drupal.org
                     - Elimina la línea @see template_preprocess(), si existe.
                     - Añade la línea @see template_preprocess_THEME_HOOK().
                     - Añade la línea temática @ingroup (ver ejemplo de bloque de documentación más abajo).

6. Copia el código fuente de tu función debajo del bloque de documentación (ver ejemplo abajo)
7. Cambia el código PHP mayormente a HTML y operadores de impresión
                   - Elimina el código PHP dentro del HTML, ejemplos:
                               * function whatever() {
                               * // …
                               * return $output; }
                   - Elimina los operadores de impresión PHP y reemplázalos con {{ }}
                               * Convierte $variables en nombres simples: $variable['title'] se convierte en {{ title }}
                               * Reemplaza la sintaxis de arrays con la sintaxis de punto: $variable['page']['tabs'] se convierte en {{ page.tabs }}
                   - Elimina la lógica PHP y reemplázala con la sintaxis de control {%%}.
                               * <?php foreach $items as $item ?> se convierte en {% for item in items %}
                   - Reemplaza comentarios PHP con comentarios de sintaxis Twig: {# #}
                   - Reemplaza funciones t() alrededor de literales con el filtro t: {{ 'texto entre comillas'|t }}
                   - Mueve toda la lógica PHP para variables a una función de preprocesamiento. (las instrucciones para preprocesamiento están abajo.)
8. Si durante este proceso ves cosas que deseas mejorar, por ejemplo, combinar plantillas aparentemente redundantes en una sola, o mejorar el marcado o nombres de variables, apúntalo en esta hoja de cálculo o crea un problema en nuestro sandbox. Por ejemplo: http://drupal.org/node/180591

Conversión o combinación en funciones de preprocesamiento

NOTA:

• Las funciones de preprocesamiento reemplazarán todas las funciones de tema.
• Si tienes lógica PHP en tu archivo de plantilla que afecta las variables que se imprimen, ese código debe moverse a una función de preprocesamiento.
• Si tu plantilla comenzó como una función de tema, esa función debe convertirse en una función de preprocesamiento.
• Si algunas funciones de tema ya tienen funciones de preprocesamiento asociadas, el código que procesa variables en esas funciones de tema debe moverse al preprocesamiento.
• No agregues una línea en tu implementación hook_theme que diga a Drupal que use un archivo de plantilla en lugar de una función de tema.

INSTRUCCIONES:

• Renombra theme_TU_FUNCION a template_preprocess_TU_FUNCION.
• Pasa $variables por referencia, añadiendo un ampersand (&). Por ejemplo, theme_select($variable) se convierte en template_preprocess_select(&$variable).
• Edita la función para que solo procese la lógica de manejo de variables; elimina cualquier marcado (es decir, $output).

Si a tus plantillas de Twig les faltan funciones...

Si necesitas acceso a un filtro o función en una plantilla Twig que aún no funciona, añádelo a este issue abierto. Ten en cuenta que la mayoría de las funciones de PHP o Drupal deben moverse a funciones de preprocesamiento. Solo si crees que un desarrollador de temas necesitará acceso a esa función, debería permanecer en la plantilla.

Ejemplo sencillo de conversión (theme_link)

Código PHP

function theme_link($variables) { return '<a href="' . ($variables['options']['html'] ? $variables['text'] : check_plain($variables['text'])) . '">' . ($variables['options']['html'] ? $variables['text'] : check_plain($variables['text'])) . '</a>'; } 

Plantilla Twig (nombre de archivo: link.html.twig)

{# /**
 * @file
 * Implementación de tema por defecto para mostrar un enlace.
 *
 * Variables disponibles:
 * - text: El texto del enlace para la etiqueta anchor.
 * - url: La URL completa a la que enlaza, como
 *   "/node/34" o "http://example.com/foo".
 * - attributes: Atributos HTML restantes para el elemento contenedor.
 *
 * @see template_preprocess_link()
 *
 * @ingroup themeable
 */ #}
<a href="{{ url }}" class="{{ attributes.class }}"{{ attributes }}>{{ text }}</a>

Cambios en system.module (función de preprocesamiento)

/**
 * Prepara las variables para las plantillas de enlace.
 *
 * Plantilla por defecto: link.html.twig.
 *
 * @param array $variables
 *   Un arreglo asociativo que contiene:
 *   - text: El texto traducido del enlace para la etiqueta anchor.
 *   - path: La ruta interna o URL externa a la que enlaza.
 *   - options: Un arreglo asociativo de opciones adicionales.
 */
function template_preprocess_link(&$variables) {
  $variables['url'] = url($variables['path'], $variables['options']);
}

Comentarios:

Andrey Podanenko: http://drupal.org/node/1783130 Cómo renombrar variables
jen: Añade tus propios delimitadores de comentarios Twig {# y #}.
jen: sigue los delimitadores de comentarios Twig con los marcadores estándar de doxygen para PHP.
jen: copia y pega esta definición de api.drupal.org
James Wilson: Al copiar definiciones de funciones, reescribe "Devuelve HTML ..." como "Implementación de tema por defecto".
jen: copia y pega "Parámetros" de api.drupal.org
James Wilson: Elimina el signo de dólar de los nombres de variables, si necesitas referenciar otra variable desde el bloque doc, usa comillas simples alrededor de la variable. [Ver discusión de política aquí http://drupal.org/node/1804710]
jen: "imprime" variables en Twig usando la sintaxis {{}}
jen: Los atributos están "perforados" para que puedas referenciar clases
jen: La mayoría de funciones como url() deben eliminarse de la plantilla y agregarse al preprocesamiento.