Transform API
Un módulo de Drupal que expone rutas y entidades transformadas a JSON con una API integral, permitiendo a los desarrolladores de Drupal aprovechar su conocimiento existente de entidades, modos de visualización y plantillas para producir JSON en lugar de HTML.
transform_api
Install
composer require 'drupal/transform_api:^2.1'
Overview
Transform API proporciona un camino familiar para que los desarrolladores de Drupal transformen su conocimiento de entidades, modos de visualización y plantillas en salida JSON en lugar de HTML. Al acceder a cualquier ruta en Drupal con el parámetro GET format=json, la solicitud se redirige a través de Transform API, produciendo salida JSON mientras conserva la capacidad de almacenamiento en caché y los requisitos de permisos.
El módulo introduce conceptos clave análogos al núcleo de Drupal: Transforms (equivalente a plantillas de tema), Transformer (equivalente al servicio de renderizado), Transform arrays (equivalente a render arrays), Transform modes (equivalente a modos de visualización), y Transform blocks (equivalente a bloques). Estos proporcionan salidas JSON globales segmentadas en regiones configurables.
El módulo ofrece amplio soporte de plugins para transformaciones de campos, soportando todos los tipos de campo comunes de Drupal incluyendo texto, booleano, entero, flotante, datetime, imagen, archivo, enlace, referencia de entidad y más. Se integra con Layout Builder y soporta imágenes responsivas a través de submódulos.
Features
- Transformación automática a JSON de cualquier ruta de Drupal agregando el parámetro format=json a las URLs
- Modos de transformación para configurar cómo las entidades se transforman a JSON, similar a los modos de visualización para HTML
- Sistema de bloques de transformación para agregar datos JSON globales a las respuestas, organizados en regiones configurables
- Plugins de transformación de campos completos que soportan todos los tipos de campo comunes de Drupal (texto, booleano, numérico, datetime, imagen, archivo, enlace, referencia de entidad, etc.)
- Soporte completo de caché usando CacheableMetadata de Drupal para rendimiento óptimo
- Múltiples métodos de autenticación incluyendo Basic Auth, Cookie y OAuth2
- Hooks de alteración para personalizar la salida de transformación en varios niveles
- Integración con Layout Builder para transformar componentes de sección
- Soporte de transformaciones anidadas para componer estructuras JSON complejas
- Callbacks de transformador lazy para manejar contenido dinámico no cacheable
Use Cases
Configuración Drupal Headless/Desacoplado
Use Transform API para servir contenido JSON a un framework frontend JavaScript (React, Vue, Angular). Configure modos de transformación para diferentes contextos de visualización (completo, teaser, tarjeta) y permita que el frontend consuma los datos JSON estructurados mientras mantiene las capacidades de gestión de contenido de Drupal.
Backend para Aplicación Móvil
Exponga contenido de Drupal como APIs JSON para aplicaciones móviles nativas. La API soporta métodos de autenticación Basic Auth, Cookie y OAuth2. Las transformaciones de entidad proporcionan datos estructurados mientras los bloques de transformación agregan datos globales como menús de navegación y configuración del sitio.
Sindicación de Contenido
Exporte contenido en formato JSON para sindicación a otros sistemas. Use modos de transformación para controlar qué campos se exponen y cómo se formatean. El sistema de caché asegura entrega eficiente incluso bajo alta carga.
Aplicación Web Progresiva (PWA)
Construya una PWA que obtenga JSON de endpoints de Transform API. Use bloques de transformación basados en regiones para proporcionar datos del shell de la aplicación (menús, información de usuario) separadamente del contenido principal, habilitando estrategias de caché eficientes.
Modelado de Contenido API-First
Diseñe tipos de contenido con el consumo de API en mente. Configure modos de transformación por bundle para exponer diferentes conjuntos de campos para diferentes consumidores. Use hooks de alteración para agregar campos calculados o modificar la estructura de salida sin cambiar los modelos de contenido.
Tips
- Agregue format=json a cualquier URL de Drupal para obtener salida JSON en lugar de HTML
- Use modos de transformación como modos de visualización - cree transformaciones 'card', 'teaser', 'full' para diferentes contextos
- Los bloques de transformación se evalúan una vez y se cachean - use #lazy_transformer para contenido dinámico no cacheable
- Anide objetos EntityTransform en transform arrays en lugar de llamar transform() directamente para mejor caché
- Use hook_ENTITYTYPE_transform_alter para personalizaciones específicas de entidad en lugar del genérico hook_transform_alter
- La clave de control #collapse reduce el anidamiento cuando un array tiene solo un miembro - útil para campos de valor único
- Las regiones de bloques de transformación pueden consultarse independientemente via el parámetro region en RequestPathTransform
Technical Details
Admin Pages 7
/admin/structure/display-modes/transform
Lista todos los modos de transformación disponibles en el sistema. Los modos de transformación definen cómo las entidades se transforman a JSON, similar a cómo los modos de visualización definen el renderizado HTML. Los usuarios pueden agregar, editar y eliminar modos de transformación para diferentes tipos de entidad.
/admin/structure/display-modes/transform/add/{entity_type_id}
Crear un nuevo modo de transformación para un tipo de entidad específico. El modo de transformación define cómo las entidades de este tipo serán transformadas a JSON.
/admin/structure/block/transform
Administrar bloques de transformación que proporcionan datos JSON globales para todas las rutas transformadas. Los bloques pueden asignarse a regiones y configurarse con condiciones de visibilidad similar a los bloques regulares de Drupal.
/admin/structure/block/transform/region
Administrar regiones de bloques de transformación. Las regiones organizan los bloques de transformación y pueden consultarse independientemente en las respuestas JSON. Incluye configuración para la región predeterminada y si colapsar regiones de un solo bloque.
/admin/structure/block/transform/region/add
Crear una nueva región de bloques de transformación para organizar bloques de transformación en la salida JSON.
/admin/structure/block/transform/add/{plugin_id}
Configurar una instancia de bloque de transformación incluyendo su configuración, ubicación de región y condiciones de visibilidad.
/admin/structure/types/manage/{bundle}/transform
Configurar cómo los campos de un tipo de contenido se transforman a JSON para cada modo de transformación. Seleccionar qué plugin de transformación de campo usar para cada campo u ocultar campos de la salida JSON.
Permissions 4
Hooks 5
hook_transform_alter
Alterar todos los arrays de transformación mientras se transforman. Se llama para cada transform procesado por el transformador.
hook_HOOK_transform_alter
Alterar arrays de transformación con un identificador HOOK específico. El HOOK es proporcionado por el método getAlterIdentifiers() del transform, típicamente el tipo de transform y tipo de entidad.
hook_blocks_transform_config_alter
Alterar la configuración de bloques de transformación. Permite agregar o modificar bloques de transformación programáticamente.
hook_field_transform_third_party_settings_form
Agregar configuraciones de terceros a formularios de configuración de transformación de campos.
hook_field_transform_settings_summary_alter
Alterar el resumen de configuración mostrado para transformaciones de campos en la interfaz.