LightGallery Formatter convierte un campo de medios de Drupal en una galería limpia que funciona bien en pantallas táctiles. Usa la biblioteca de JavaScript lightGallery. Configuras un estilo de galería una sola vez y después lo reutilizas en cualquier campo.

Lo crean y lo mantienen Andrii y Denys.

Qué es

LightGallery Formatter es un formateador de campo para campos de referencia a Media. Elígelo en Manage display, escoge un perfil y tus imágenes, tus videos remotos (YouTube y Vimeo) y tus archivos PDF se abrirán en un visor.

No tienes que escribir JSON ni código. Todos los ajustes son casillas y listas desplegables en las pantallas de administración.

El formateador aparece en un campo de referencia a Media cuando ese campo puede guardar un tipo de Media con imágenes, o el tipo estándar Document (un tipo basado en archivos con el nombre de máquina document). También aparece cuando el campo no limita los tipos de Media. Un campo que solo permite video remoto no lo ofrece.

Por qué existe

El módulo drupal/lightgallery que ya existe te pide configurar cada campo por separado. Eso se vuelve lento cuando un sitio tiene muchas galerías.

Este módulo usa perfiles reutilizables. Crea los que necesites. Cambia un perfil y todas las galerías que lo usan cambian con él. Lo configuras una vez y lo usas en todas partes.

Tampoco tienes que instalar la biblioteca a mano. lightGallery 2.9.0 viene incluida en el módulo, junto con React. No hay descargas adicionales ni rutas personalizadas de Composer.

Funciones principales

• Perfiles reutilizables. Un perfil puede controlar muchos campos.
• Medios mezclados en una galería. Imágenes, videos de YouTube, videos de Vimeo y archivos PDF, en el orden que eligió el editor.
• Biblioteca incluida. lightGallery y React vienen con el módulo. No hay que descargar JavaScript a mano ni seguir pasos de Composer para la biblioteca.
• 31 transiciones. Slide, Fade, Zoom, Lollipop, Rotate, Tube y más, todas en una lista desplegable.
• Controles completos. Zoom, pantalla completa, miniaturas, botón de descarga y navegación con el teclado con las teclas Esc y las flechas. La rueda del ratón es opcional.
• Soporte táctil. Deslizar y arrastrar en teléfonos y tabletas. Puedes desactivar cualquiera de los dos.
• Controles que se ocultan solos. Es opcional, con un retraso que tú eliges.
• Miniaturas de video. Las miniaturas de YouTube y Vimeo salen de la miniatura del elemento Media.
• Clonación de perfiles. Copia un perfil y úsalo como punto de partida para uno nuevo. Novedad de la versión 1.1.0.
• Diapositivas de PDF. Los archivos PDF se abren en el visor con el lector que ya trae el navegador. Novedad de la versión 1.1.0.
• Exportación de configuración. Los perfiles pasan de un sitio a otro con la configuración estándar de Drupal.
• Vista previa en vivo. Prueba un perfil mientras lo editas. Esto necesita un submódulo opcional.
• Enlaces de respaldo. Los enlaces de imágenes y PDF siguen funcionando antes de que cargue el script, o si no llega a cargar.
• Entrada en el informe de estado. El informe de estado de Drupal muestra la versión de lightGallery incluida.

Requisitos

• Drupal ^10.3, ^11 o ^12
• Los módulos del núcleo Media y Media Library. El módulo necesita los dos.
• Para archivos PDF, el tipo de Media estándar Document y al menos un tipo de Media con imágenes para la miniatura del PDF

Instalación

Instala el módulo con Composer. No necesitas Node.js ni npm en tu sitio. El JavaScript ya está compilado y viene dentro del módulo.

composer require drupal/lightgallery_formatter

Actívalo con Drush.

drush en lightgallery_formatter

También puedes activar los submódulos opcionales.

drush en lightgallery_formatter_preview lightgallery_formatter_demo

Si prefieres las pantallas de administración, ve a Extend, busca el grupo LightGallery y marca los módulos que quieras.

Inicio rápido

Paso 1. Crea un perfil

1. Ve a Configuration → Media → LightGallery (/admin/config/media/lightgallery).
2. Haz clic en Add LightGallery profile.
3. Escribe un Label y un Machine name. Solo puedes cambiar el nombre de máquina mientras el perfil es nuevo.
4. Define las opciones generales. Mira la sección «Perfiles y ajustes» más abajo.
5. Activa los plugins que quieras, como miniaturas, zoom o pantalla completa.
6. Si el submódulo Preview está activo, haz clic en Generate Preview en la parte superior del formulario para probar tus ajustes.
7. Guarda el perfil.

El módulo trae un perfil llamado Default. Necesitas el permiso Administer LightGallery formatter para administrar perfiles.

Paso 2. Usa el perfil en un campo de medios

1. Ve a Structure → Content types → (tu tipo) → Manage display.
2. Busca tu campo de referencia a Media.
3. Elige el formateador LightGallery.
4. Haz clic en el icono de engranaje.
5. Elige tu LightGallery Profile. Solo se muestran los perfiles activados.
6. Elige un estilo de imagen para Gallery thumbnails (inline on page).
7. Si el campo tiene archivos PDF, elige una miniatura para los PDF. Mira la sección «Trabajar con PDF» más abajo.
8. Guarda.

Comprueba también que el campo permite los tipos de Media que vas a usar. Marca Image para las imágenes, Remote video para YouTube y Vimeo, y Document para los archivos PDF.

Paso 3. Revisa el resultado

Abre un contenido con imágenes, videos o archivos PDF. Se muestran como una sola galería, en el mismo orden que eligió el editor.

Perfiles y ajustes

Un perfil es una entidad de configuración de Drupal (lightgallery_profile). Guarda una etiqueta, un nombre de máquina, una casilla Enabled y los ajustes de cada plugin. Solo se pueden elegir perfiles activados en los ajustes del formateador de un campo.

Clonar un perfil (novedad de la 1.1.0)

Clonar es una forma rápida de crear una variante de un perfil que ya te gusta.

1. Ve a Configuration → Media → LightGallery (/admin/config/media/lightgallery).
2. En la columna Operations del perfil que quieres copiar, abre la lista desplegable y elige Clone.
3. El formulario de clonación se abre en /admin/config/media/lightgallery/{machine_name}/clone. Es el mismo formulario de Add y Edit, ya relleno con los ajustes del perfil de origen.
4. El Label es la etiqueta del perfil de origen seguida de (copy). Cámbiala.
5. El Machine name está vacío. Escribe uno nuevo con letras minúsculas, números y guiones bajos. Si el nombre ya está en uso, se rechaza.
6. Cambia los ajustes que quieras y haz clic en Save.

Conviene saber

• No se guarda nada hasta que haces clic en Save. Si sales de la página, no se crea ningún clon.
• Se copian la casilla Enabled y los ajustes de todos los plugins. Eso incluye General, Thumbnail, Zoom, Video y los demás, con su estado de activado o desactivado.
• El perfil de origen nunca cambia.
• El clon es un perfil nuevo y separado. Si lo editas después, el original no se toca, y al revés.
• Al guardar vuelves a la lista de perfiles con el mensaje «Created the ... LightGallery profile.»
• Clonar necesita el mismo permiso que editar, es decir Administer LightGallery formatter.

Ajustes generales

Estos ajustes siempre están activos. Los encuentras en la sección General Settings del formulario.

• License key. Mira «Una nota sobre la clave de licencia» más abajo.
• Enable looping. Pasa de la última diapositiva a la primera.
• Preload count. Cuántas diapositivas se cargan por adelantado, de 1 a 5.
• Transition speed (ms). La velocidad de la animación en milisegundos.
• Transition mode. El estilo de la transición. Puedes elegir entre 31.
• Closable, Close on tap y Close with Esc key. Controlan cómo pueden cerrar el visor los visitantes.
• Keyboard navigation. Las flechas y teclas parecidas.
• Show close icon y Show maximize icon.
• Hide controls delay (ms). Oculta la barra de herramientas después de este tiempo. Con 0 se queda visible.
• Show counter. Muestra el número de la diapositiva y el total.
• Enable download. Muestra el botón de descarga.
• Enable desktop drag y Enable touch swipe.
• Mouse wheel navigation.
• Allow media overlap. Déjala activada si quieres ver en la barra el interruptor de miniaturas y los iconos de otros plugins.

El perfil Default que trae el módulo tiene el botón de descarga desactivado. Un perfil nuevo empieza con ese botón activado.

Plugins

El código tiene 12 plugins. General siempre está activo. Los otros 11 los activas uno por uno dentro de un perfil. El README cuenta 11 porque no incluye el plugin Video.

• General. Las opciones principales que se describen arriba. Siempre activo.
• Video. Permite reproducir videos en el visor, para YouTube y Vimeo. Sus ajustes incluyen la reproducción automática del primer video, la reproducción automática al cambiar de diapositiva, pasar a la siguiente diapositiva cuando termina un video y la opción de Video.js.
• Thumbnail Navigation. Una fila de miniaturas en la parte inferior del visor. Sus ajustes incluyen el estilo de imagen, el ancho, el alto, el margen, la posición de la miniatura actual, la alineación, un botón para mostrar u ocultar y dónde colocarlo.
• Zoom. Acerca y aleja, y muestra el tamaño real. Sus ajustes incluyen la escala, el zoom infinito, el botón de tamaño real, los iconos de zoom y un retraso antes de activar el zoom.
• Fullscreen. Ocupa toda la ventana del navegador. No tiene ajustes.
• Pager. Un indicador del número de página.
• Relative Caption. Títulos colocados junto a la imagen.
• Rotate. Gira y voltea imágenes. Sus ajustes incluyen la velocidad de giro, girar a la izquierda y a la derecha, y voltear en horizontal y en vertical.
• Autoplay. Una presentación automática. Sus ajustes incluyen el inicio automático, el intervalo (5000 ms por defecto), una barra de progreso, forzar la reproducción automática y los controles con su posición.
• Medium Zoom. Un zoom al estilo de Medium. Sus ajustes incluyen el margen y el color de fondo.
• Share. Botones para compartir en Facebook, Twitter y Pinterest. Puedes activar o desactivar cada uno y cambiar el texto de cada botón.
• Hash. Enlaces directos a una diapositiva en la dirección de la página. Sus ajustes incluyen activar hash y nombres personalizados para las diapositivas.

Cada plugin, salvo General, tiene su propia casilla Enable ... plugin. En un perfil nuevo solo se envían al navegador los plugins marcados.

Dos tipos de miniaturas

• Las miniaturas de la galería son la cuadrícula de la página. Eliges el estilo de imagen en el formateador del campo.
• Las miniaturas del visor son la fila dentro del visor. Eliges el estilo de imagen en el perfil, en Thumbnail Navigation. Si lo dejas vacío, la fila usa el estilo de miniatura de galería del campo.

Enlaces directos (plugin Hash)

Con el plugin Hash activo, la dirección de la página cambia mientras te mueves por la galería. El formato es #lg={gallery-id}&slide={index}. El índice de la diapositiva empieza en 0. Con Custom slide name activado, se usa el nombre de la diapositiva en lugar del número cuando existe.

Si pones en la misma página más de una galería con Hash activado, prueba los enlaces directos antes de confiar en ellos.

Interacciones conocidas entre plugins

• Hash junto con Thumbnail Navigation puede comportarse de forma rara en algunos navegadores.
• Relative Caption puede escribir una advertencia en la consola del navegador durante las transiciones. No cambia el funcionamiento de la galería.
• Los clics de Medium Zoom pueden chocar con los clics en la fila de miniaturas.

Si ves un problema, desactiva uno de los plugins en el perfil.

Una nota sobre la clave de licencia

La lightGallery 2.9.0 incluida es de código abierto con la licencia GPLv3. El archivo package.json de la biblioteca y el encabezado de licencia del archivo incluido dicen GPLv3.

El formulario del perfil tiene un campo License key. Viene con el valor 0000-0000-000-0000, y el texto de ayuda dice que uses ese valor para uso no comercial. El módulo no comprueba la clave. Pasa el valor a lightGallery, y la biblioteca solo escribe un mensaje en la consola del navegador. Si la clave es la que viene por defecto, la biblioteca registra una advertencia de que no es válida para producción. Si el campo está vacío, registra un error que pide una clave válida. La galería funciona en los dos casos.

La licencia comercial es para proyectos que mantienen cerrado su código fuente. La página de licencia de lightGallery dice que GPLv3 es gratuita y que la licencia de pago es para proyectos de código cerrado. Los módulos de Drupal son GPL, así que para la mayoría de los sitios de Drupal sirve la opción GPLv3. Si no estás seguro de tu propio proyecto, lee las condiciones en https://www.lightgalleryjs.com/license/ o pregunta a los autores de la biblioteca.

Tipos de medios compatibles

• Imágenes. Elementos de imagen de Media del núcleo. Usa los estilos de imagen de Drupal para las miniaturas. En los ajustes del formateador, en Gallery item source by media type, puedes elegir qué campo de imagen usar para cada tipo de Media.
• YouTube y Vimeo. Elementos de video remoto, con miniaturas tomadas de la miniatura del elemento Media. El formateador trata como video remoto los tipos de Media con los nombres de máquina remote_video, video u oembed_video. Activa el plugin Video en el perfil para que los videos se reproduzcan en el visor.
• Archivos PDF. El tipo de Media estándar Document, con el nombre de máquina document y una fuente de archivo. Novedad de la versión 1.1.0.
• Archivos de video HTML5. El formateador de campo no los admite. Mira «Notas sobre el video» más abajo.

Trabajar con PDF

Cómo se muestra un PDF

• El PDF se abre dentro del visor como una diapositiva con iframe, que usa el lector de PDF del navegador. El módulo no incluye su propio lector de PDF. En el código no hay pdf.js ni etiquetas embed u object.
• Las imágenes y los archivos PDF pueden estar en el mismo campo. El orden que puso el editor se mantiene para los botones de anterior y siguiente.
• Cada diapositiva de PDF tiene un título con el nombre del archivo y un enlace Open or download PDF que abre el archivo original en una pestaña nueva.

Qué cuenta como PDF

• El elemento Media debe ser del tipo document con una fuente de archivo.
• El tipo MIME del archivo guardado debe ser exactamente application/pdf. No basta con que el nombre termine en .pdf.
• El código no pone límite al tamaño del archivo ni al número de PDF en una galería.

La miniatura del PDF

• Un PDF no tiene imagen propia, así que eliges una imagen para él. Es un ajuste de la visualización del campo y no del perfil.
• En los ajustes del formateador (el icono de engranaje), abre Gallery item source by media type y busca PDF settings. En los campos sin límite de tipos de Media, PDF settings se muestra solo.
• Haz clic en Select PDF thumbnail. Se abre la Media Library normal de Drupal en una ventana emergente. Puedes elegir exactamente un elemento. Solo se ofrecen tipos de Media con imágenes.
• Después de elegir, el resumen dice «Selected thumbnail» y el botón cambia a Change PDF thumbnail.
• La imagen elegida debe estar publicada y ser visible para el usuario. Se comparte entre todos los PDF de esa visualización del campo. Se usa para la cuadrícula de la página y para la fila del visor, cada una con su propio estilo de imagen.
• Si no eliges miniatura, o la elegida está sin publicar, oculta o eliminada, los archivos PDF de esa galería se omiten. Las imágenes se siguen mostrando.
• Si el sitio no tiene un tipo de Media con imágenes, el selector no se muestra y el ajuste se guarda como 0.
• La línea de resumen bajo el formateador muestra «PDF thumbnail: not configured» hasta que eliges una.

Cuando algo no se puede mostrar

• Un elemento Media que no se puede mostrar se omite y la galería sigue funcionando. Se escribe una advertencia corta en el canal de registro lightgallery_formatter. Los motivos posibles son que falte el campo de origen, que falte el archivo, un tipo MIME incorrecto, un tipo de Media no compatible o que falte la miniatura del PDF.
• Si se omiten todos los elementos, no se muestra nada para ese campo.

Cuando el navegador no puede mostrar PDF dentro de la página

• El script comprueba si el lector de PDF del navegador está activado. Si no lo está, los archivos PDF no se abren en el visor. La miniatura pasa a ser un enlace normal al PDF, con un enlace Open or download PDF debajo.
• Aparece un aviso corto sobre la galería. Dice «Your browser cannot display PDFs here. You can still open or download each PDF.» También añade una pista para Chrome, Edge, Firefox o Safari sobre cómo activar el lector.
• Sin JavaScript, o si la galería no carga, la página sigue mostrando cada PDF como una miniatura con el nombre del archivo y un enlace Open PDF in a new tab.

Notas sobre el video

• YouTube y Vimeo funcionan con elementos Media del tipo de video remoto. La dirección que se reproduce se lee del campo de origen del elemento Media.
• El formulario del plugin Video menciona los videos HTML5 y Video.js, y la biblioteca incluida puede reproducir video HTML5. Pero el formateador de campo no tiene código que cree una diapositiva a partir de un archivo de video subido. Un elemento Media de un tipo de video basado en archivos se mostraría como una diapositiva de imagen con su miniatura. Por eso no listamos el video HTML5 como compatible.
• La opción de pasar a la siguiente diapositiva cuando termina el video no funciona con YouTube. El formulario del plugin también lo dice.

Cómo funciona por dentro

• La galería se construye con React y el componente de React de lightGallery. Vite los empaqueta en un solo archivo, js/dist/lightgallery-react.js.
• El servidor primero imprime enlaces y miniaturas simples. Cuando carga el script, la galería interactiva los reemplaza. Si el script falla, vuelven los enlaces simples.
• Las versiones incluidas son lightGallery 2.9.0 y React 18.
• No se usa jQuery.

Submódulos

Los dos submódulos son opcionales.

LightGallery Formatter Preview

Añade un botón Generate Preview al formulario del perfil, para que veas la galería con tus ajustes actuales antes de guardar. También contiene los Media de ejemplo de imagen, PDF y video remoto que usan la vista previa y la demostración, con una miniatura de PDF de ejemplo.

drush en lightgallery_formatter_preview -y

LightGallery Formatter Demo

Crea contenido de demostración para probar galerías con imágenes, archivos PDF y videos mezclados. Está hecho para el perfil de instalación demo_umami y reutiliza los Media de ejemplo del módulo Preview. Al instalarse también elige la miniatura de PDF del módulo Preview para la visualización de la demostración. Te lo recomendamos si quieres ver lo que puede hacer el módulo.

drush en lightgallery_formatter_demo -y

Exportar la configuración y desplegar

Cada perfil es configuración de Drupal y se guarda como lightgallery_formatter.profile.{machine_name}. Contiene el nombre de máquina, la etiqueta, el indicador de activado y los ajustes de los plugins. Expórtala e impórtala igual que el resto de la configuración de tu sitio. Crea un perfil en tu sitio de desarrollo, expórtalo y luego despliégalo.

Los ajustes del formateador de un campo, incluidos el perfil elegido y la miniatura del PDF, están en la configuración de visualización de ese campo (core.entity_view_display...). La miniatura del PDF se guarda como un ID de Media, así que comprueba que ese elemento Media exista en el sitio de destino.

drush config:export drush config:import

Compatibilidad y versiones

• 1.1.0. Publicada el 1 de octubre de 2026 (la etiqueta de git tiene fecha del 28 de septiembre). Funciona con Drupal ^10.3 || ^11 || ^12.
• 1.0.9. Publicada el 20 de marzo de 2026. Funciona con Drupal ^10.3 || ^11.

Qué hay de nuevo en la 1.1.0

• Soporte de PDF, en la misma galería que las imágenes y los videos remotos
• Una miniatura de PDF compartida, que se elige para cada visualización de campo con Media Library
• Los PDF se abren en el lector del navegador, con una alternativa clara y un aviso cuando el lector está desactivado
• Clonación de perfiles desde la lista de perfiles (Operations → Clone)
• Compatibilidad con Drupal 12
• Media Library del núcleo ahora es una dependencia obligatoria
• El marcado de respaldo ahora se queda en la página hasta que la galería ha cargado, y vuelve si la carga falla
• Salida más segura, porque se escapan los nombres de archivo, las etiquetas y los atributos
• El informe de estado de Drupal muestra la versión de lightGallery incluida
• Muchas pruebas automáticas nuevas

La página del proyecto dice que 56 sitios informan que usan el módulo. Las versiones estables están cubiertas por la política de avisos de seguridad de Drupal.

Para desarrolladores

El módulo usa ddev-drupal-contrib para el desarrollo local.

git clone git@git.drupal.org:project/lightgallery_formatter.git cd lightgallery_formatter ddev start ddev lgf:init

El comando ddev lgf:init instala Drupal con el perfil demo_umami, activa el módulo con contenido de demostración y te da un acceso de administrador. Otros comandos son ddev phpcs, ddev phpcbf, ddev phpstan y ddev phpunit.

Solo necesitas Node.js si quieres cambiar la parte visual. El código fuente está en js/react/ y los estilos están en css/ (Sass). Compila con npm run build, que usa Vite para el JavaScript y Sass para el CSS. La versión de Node se define en .nvmrc. Los archivos compilados van a js/dist/.

Enlaces

• Página del proyecto https://www.drupal.org/project/lightgallery_formatter
• Cola de incidencias https://www.drupal.org/project/issues/lightgallery_formatter
• Código fuente https://git.drupalcode.org/project/lightgallery_formatter
• Video tutorial en YouTube (en inglés) https://www.youtube.com/watch?v=FyHGh2xYSEo
• Biblioteca lightGallery https://www.lightgalleryjs.com/
• Licencia de lightGallery https://www.lightgalleryjs.com/license/

Créditos

• Lo crean y lo mantienen Andrii y Denys.
• La biblioteca lightGallery es de Sachin Neravath. La versión incluida, la 2.9.0, tiene licencia GPLv3. React también se incluye, con licencia MIT.
• Gracias a @bbu23 y @nk_ por sus ideas sobre los ajustes basados en perfiles.
• Las capturas de pantalla vienen de la página del proyecto en Drupal.org y del video tutorial en YouTube.