Swiper formatter
Integra Swiper.js, una biblioteca moderna de deslizamiento orientada a dispositivos móviles, como field formatters y plugin de estilo de Views para Drupal.
swiper_formatter
Instalar
composer require 'drupal/swiper_formatter:^2.0'
composer require 'drupal/swiper_formatter:^1.0'
Overview
Swiper formatter proporciona integración con Drupal para Swiper.js, una de las bibliotecas de deslizamiento más modernas y con más funciones disponibles. A diferencia de los sliders de imágenes tradicionales, este módulo está diseñado como un widget de interfaz de usuario de deslizamiento integral que puede manejar casi cualquier tipo de contenido.
El módulo soporta direcciones de deslizamiento horizontal y vertical y funciona con varios tipos de campos incluyendo imágenes, campos de texto/marcado, referencias de media, referencias de entidades, paragraphs y resultados de Views. Ofrece un sistema de entidades de configuración que permite crear "plantillas Swiper" reutilizables con opciones personalizables para navegación, paginación, reproducción automática, carga diferida, diseños de cuadrícula, breakpoints y muchas más características de Swiper.js.
El contenido puede mostrarse en formato Swiper regular o con funcionalidad de diálogo/modal, donde al hacer clic en un slide se abre el contenido en una superposición modal, off-canvas o de diálogo.
Features
- Sistema de entidades de configuración para crear plantillas Swiper reutilizables con amplias opciones de personalización
- Múltiples field formatters: Swiper images, Swiper markup (texto), Swiper entity (referencias de entidades), Swiper Paragraphs (paragraphs)
- Variantes de diálogo para todos los formatters que abren contenido en superposiciones modal, dialog u off-canvas
- Plugin de estilo de Views para mostrar cualquier resultado de Views como un slider Swiper
- Soporte para módulos de Swiper.js: Navigation, Pagination, Scrollbar, Autoplay, Lazy Loading y Grid
- Soporte de breakpoints responsivos con capacidad de referenciar otras plantillas Swiper para diferentes tamaños de viewport
- Múltiples opciones de fuente de biblioteca: paquete incluido, CDN remoto o instalación local
- Soporte de subtítulos desde varias fuentes de campo incluyendo alt/título de imagen y otros campos de texto
- Efectos de transición de slides: slide, fade, cube, coverflow, flip y cards
- Integración con Token para títulos de diálogo dinámicos y enlaces personalizados
- Extenso sistema de sugerencias de theme para personalización de plantillas por view, tipo de entidad, campo o view mode
- Hook para alterar programáticamente la configuración de Swiper antes del renderizado
Use Cases
Galería de imágenes con carga diferida
Usa el formatter Swiper images en un campo de imagen de múltiples valores para crear una galería de imágenes responsiva. Habilita la carga diferida en la plantilla Swiper para mejorar el rendimiento de carga de la página. Configura slidesPerView para mostrar múltiples miniaturas y habilita navegación y paginación para navegación fácil.
Carrusel de contenido en página principal
Crea un bloque de Views mostrando nodes de contenido destacado y usa el plugin de estilo Swiper formatter. Configura autoplay con un retardo de 5000ms para ciclo automático a través de elementos destacados. Cada fila de resultado del view se convierte en un slide mostrando el contenido renderizado en un view mode especificado.
Lightbox de imágenes de producto
Usa el formatter Swiper images Dialog en el campo de imagen de un producto. Configura el diálogo para abrir como modal mostrando un estilo de imagen más grande. Los usuarios pueden hacer clic en miniaturas en el Swiper para ver imágenes de tamaño completo en una superposición modal.
Slider de testimonios con texto
Crea un campo text_long de múltiples valores para testimonios y aplica el formatter Swiper markup. Habilita autoplay para ciclo automático y usa el efecto fade para transiciones suaves entre testimonios.
Configuración de breakpoints responsivos
Crea múltiples plantillas Swiper: una plantilla principal y plantillas de breakpoint separadas para diferentes tamaños de viewport (ej., 480px, 960px). Configura la plantilla principal para referenciar plantillas de breakpoint, ajustando slidesPerView y visibilidad de navegación para cada tamaño de pantalla. El módulo sigue un enfoque mobile-first donde los operadores de breakpoint son >= el ancho especificado.
Slider de Paragraph
Añade un campo Paragraphs a un tipo de contenido para crear contenido de slide con formato enriquecido. Aplica el formatter Swiper Paragraphs para mostrar cada elemento paragraph como un slide. Esto permite a los editores de contenido crear slides con diseños personalizados, imágenes, texto y otros componentes de paragraph.
Galería de Media con vista previa modal
Usa el formatter Swiper entity Dialog en un campo de referencia de entidad que apunta a entidades Media. Configura slides para mostrar view mode de miniatura y diálogo para mostrar view mode completo. Los usuarios pueden navegar miniaturas y hacer clic para abrir una vista previa más grande en un panel modal u off-canvas.
Tips
- Crea plantillas Swiper dedicadas para diferentes casos de uso (ej., 'Slider hero', 'Galería de productos', 'Testimonios') para mantener configuraciones consistentes en todo el sitio.
- Usa la fuente de biblioteca 'Paquete' para sitios en producción para incluir Swiper.js con tu módulo y evitar dependencias de CDN externos.
- Para sliders verticales, establece una altura fija en la plantilla Swiper y habilita autoHeight.
- Cuando uses modo CSS para mejor rendimiento, nota que algunas características de Swiper como efectos de transición distintos a slide no están soportados.
- Usa hook_swiper_formatter_settings_alter para ajustar dinámicamente la configuración basándote en el número de slides u otras condiciones en tiempo de ejecución.
- Las sugerencias de plantilla permiten crear plantillas Twig personalizadas por view, tipo de contenido, nombre de campo, o plantilla Swiper específica para control detallado sobre el marcado.
- La opción observer es útil cuando Swiper está dentro de un contenedor oculto (pestañas, acordeones) que se hace visible después de la carga de la página.
- Para sitios en producción con preocupaciones de rendimiento, considera usar fuente de biblioteca local minificada y habilitar carga diferida para sliders con muchas imágenes.
Technical Details
Admin Pages 3
/admin/config/content/swiper-formatter
Lista todas las plantillas Swiper existentes (entidades de configuración). Desde aquí puedes ver, editar o eliminar plantillas, y crear nuevas. La plantilla predeterminada no puede eliminarse.
/admin/config/content/swiper_formatter/add
Crea una nueva plantilla de configuración Swiper con parámetros y módulos de Swiper.js personalizables.
/admin/config/content/swiper-formatter/{swiper_formatter}
Edita una plantilla de configuración Swiper existente.
Permisos 1
Hooks 1
hook_swiper_formatter_settings_alter
Permite alterar la configuración de Swiper formatter antes del renderizado. Puede usarse para modificar dinámicamente slidesPerView, configuración de cuadrícula, o cualquier otra opción de Swiper.
Troubleshooting 6
Verifica que la plantilla Swiper esté habilitada (no deshabilitada). Verifica que la fuente de biblioteca sea accesible - si usas local, asegúrate de que los archivos estén colocados en /libraries/swiper/. Revisa la consola del navegador por errores de JavaScript. Asegúrate de que haya al menos 2 slides, ya que Swiper se omite para campos de un solo elemento.
Asegúrate de que los módulos de navegación y/o paginación estén habilitados en la configuración de la plantilla Swiper. Verifica que la plantilla seleccionada en el field formatter coincida con una plantilla que tenga estas características habilitadas.
Verifica que la carga diferida esté habilitada en la plantilla Swiper. Para Views, asegúrate de que el campo de imagen tenga un estilo de imagen configurado. El módulo establece preloadImages: false y watchSlidesProgress: true automáticamente cuando la carga diferida está habilitada.
Asegúrate de que la biblioteca Ajax de Drupal apropiada esté cargada. Para modales, se requiere core/drupal.dialog.ajax; para off-canvas, se necesita core/drupal.dialog.off_canvas. El módulo debería adjuntar estas automáticamente. Verifica que la entidad que el diálogo está intentando cargar exista y sea accesible.
Recuerda que Swiper usa enfoque mobile-first - los breakpoints aplican en >= el ancho especificado. Asegúrate de que las plantillas de breakpoint estén marcadas como 'Plantilla de breakpoint' para que no aparezcan en selecciones normales del formatter. El valor del breakpoint debe ser numérico (píxeles) o comenzar con @ para valores de porcentaje.
Los formatters Swiper solo aplican a campos de múltiples valores (cardinalidad > 1). Para campos de referencia de entidad, asegúrate de que el almacenamiento del campo permita múltiples valores. Los campos de un solo valor no pueden usar formatters Swiper.