Campo de Fechas Recurrentes
Proporciona un tipo de campo de fechas recurrentes/repetitivas que soporta el formato RFC 5545 RRULE para definir patrones complejos de fechas recurrentes.
date_recur
Install
composer require 'drupal/date_recur:^3.8'
Overview
El módulo Recurring Dates Field proporciona una solución completa para manejar fechas recurrentes en Drupal. Extiende el tipo de campo datetime_range del núcleo para soportar las reglas de recurrencia iCalendar RFC 5545 (RRULE), permitiendo a los usuarios definir patrones de fechas repetitivas complejos como ocurrencias diarias, semanales, mensuales o anuales con diversas restricciones.
El módulo utiliza la biblioteca rlanvin/php-rrule para analizar y generar ocurrencias a partir de cadenas RRULE. Almacena las ocurrencias en tablas de base de datos dedicadas para una integración eficiente con Views y consultas. Un sistema de intérpretes conectables permite a los administradores configurar cómo las reglas de recurrencia se convierten en texto legible para su visualización.
Las capacidades principales incluyen manejo de fechas con reconocimiento de zona horaria, soporte para patrones de recurrencia infinitos y finitos, almacenamiento en caché de ocurrencias con intervalos de precreación configurables, e integración completa con Views para filtrar y mostrar contenido con fechas recurrentes.
Features
- Proporciona un tipo de campo date_recur que extiende datetime_range con soporte RRULE para definir patrones de fechas recurrentes
- Soporte completo de reglas de recurrencia iCalendar RFC 5545 incluyendo FREQ, INTERVAL, COUNT, UNTIL, BYDAY, BYMONTH, BYMONTHDAY, BYYEARDAY, BYWEEKNO, BYHOUR, BYMINUTE, BYSECOND, BYSETPOS, WKST y EXDATE
- Almacenamiento automático en caché de ocurrencias en tablas de base de datos dedicadas para consultas eficientes e integración con Views
- Intervalo de precreación configurable para fechas recurrentes infinitas (1-5 años hacia adelante)
- Sistema de intérpretes conectables para convertir cadenas RRULE a texto legible en múltiples idiomas (de, en, es, fi, fr, it, nl)
- Widget básico con selectores de fecha inicio/fin, selector de zona horaria y área de texto para entrada de RRULE
- Formateador básico que muestra fechas, interpretación legible y número configurable de próximas ocurrencias
- Configuración granular de frecuencias y partes que permite a los administradores restringir qué características de RRULE pueden usar los usuarios
- Integración con Views incluyendo filtro de ocurrencias, relación con tabla de ocurrencias y plugins de campos de fecha
- Sistema de eventos que despacha eventos al guardar valores de campo, eliminar entidades y eliminar revisiones para procesamiento personalizado
- Almacenamiento y visualización con reconocimiento de zona horaria con conversión UTC adecuada
- Soporte para configuraciones de campo solo fecha y fecha-hora
Use Cases
Calendario de eventos con eventos recurrentes
Crea un tipo de contenido para eventos con un campo date_recur. Configura el campo para permitir frecuencias semanales y mensuales con partes BYDAY y BYMONTHDAY. Usa Views con el filtro de ocurrencias para mostrar eventos que ocurren dentro de un rango de fechas, y la relación de ocurrencias para listar todas las instancias próximas. Configura un intérprete para mostrar 'Cada lunes y miércoles' en lugar de cadenas RRULE sin procesar.
Sistema de programación de citas
Usa campos date_recur en tipos de contenido de citas para definir espacios de disponibilidad recurrentes. Establece el intervalo de precreación a 2 años para generar datos de ocurrencias para programación. Crea Views con el filtro de ocurrencias para encontrar espacios disponibles dentro de un período de tiempo seleccionado. La tabla de caché de ocurrencias permite consultas eficientes sin cálculo de RRULE en tiempo de ejecución.
Programación de clases o cursos
Define cursos que se reúnen en patrones específicos (ej., cada martes y jueves de 2-4pm). Configura los ajustes del campo para restringir frecuencias a WEEKLY y partes a BYDAY, UNTIL y COUNT para prevenir reglas excesivamente complejas. El formateador muestra el horario de clases en español claro mientras almacena el RRULE preciso para generación de ocurrencias.
Gestión de programas de mantenimiento
Rastrea programas de mantenimiento de equipos con campos date_recur. Usa frecuencia MONTHLY con BYMONTHDAY para programar mantenimiento en días específicos cada mes, o YEARLY con BYMONTH para inspecciones anuales. Suscríbete al evento FIELD_VALUE_SAVE para disparar notificaciones o crear órdenes de trabajo cuando se actualizan los programas.
Procesamiento personalizado de ocurrencias
Implementa un suscriptor de eventos para date_recur_field_value_save para sincronizar ocurrencias con sistemas de calendario externos (Google Calendar, Outlook) o para crear nodos/entidades individuales para cada ocurrencia. El evento proporciona acceso a la lista de elementos del campo y contexto de entidad para lógica de procesamiento personalizada.
Tips
- Usa el ajuste precreate sabiamente - intervalos más largos generan más filas de ocurrencias pero permiten consultar más hacia el futuro
- Al usar Views con campos date_recur, agrega primero la relación de ocurrencias, luego agrega campos/filtros de la tabla de ocurrencias para consultas basadas en ocurrencias correctas
- Configura los ajustes del intérprete para que coincidan con el idioma y preferencias de formato de fecha de tu sitio para una experiencia de usuario consistente
- Restringe las frecuencias y partes permitidas en los ajustes del campo si no necesitas la complejidad completa de RRULE - esto simplifica la experiencia del usuario
- Para reglas recurrentes infinitas, el caché de ocurrencias solo contiene fechas precreadas - planifica tu intervalo de precreación basándote en qué tan adelante necesitan consultar los usuarios
- Suscríbete a eventos date_recur para procesamiento personalizado en lugar de usar hooks de entidad, ya que los eventos proporcionan el contexto específico del campo
- El área de texto RRULE en el widget básico acepta formato iCalendar estándar - los usuarios pueden pegar RRULEs de otras aplicaciones de calendario
- Al crear formateadores o widgets personalizados, usa el método de fábrica DateRecurHelper::create() para obtener datos de ocurrencias de valores de campo
Technical Details
Admin Pages 3
/admin/config/regional/recurring-date-interpreters
Gestiona los intérpretes de fechas recurrentes que convierten cadenas RRULE en texto legible. Los intérpretes son configuraciones reutilizables que pueden seleccionarse en los ajustes del formateador de campo para controlar cómo se muestran las reglas de recurrencia a los usuarios.
/admin/config/regional/recurring-date-interpreters/add
Crea una nueva configuración de intérprete de fechas recurrentes. Primero selecciona el tipo de plugin, luego configura los ajustes específicos del plugin.
/admin/config/regional/recurring-date-interpreters/manage/{date_recur_interpreter}
Modifica la configuración de un intérprete de fechas recurrentes existente.
Permissions 1
Hooks 5
hook_theme
Define tres hooks de tema para renderizar componentes de fechas recurrentes: date_recur_basic_widget, date_recur_settings_frequency_table y date_recur_basic_formatter.
hook_field_info_alter
Marca el tipo de campo date_recur y cualquier subclase con una bandera especial (is_date_recur) usada para gestión de tablas de ocurrencias e integración con Views.
hook_field_views_data
Proporciona integración con Views para campos date_recur adjuntos, incluyendo relación con tabla de ocurrencias y manejadores de campos.
hook_views_data
Proporciona integración con Views para campos base date_recur y registro del plugin de filtro de ocurrencias.
hook_views_data_alter
Remueve manejadores predeterminados de Views de campos base date_recur que entrarían en conflicto con los manejadores personalizados del módulo.
Troubleshooting 6
Ejecuta 'composer require rlanvin/php-rrule' en el directorio raíz de tu Drupal para instalar la biblioteca requerida, luego limpia las cachés.
Asegúrate de haber agregado la relación de ocurrencias a tu View antes de agregar campos o filtros basados en ocurrencias. Verifica que la tabla de caché de ocurrencias existe (date_recur__[entity_type]__[field_name]) y contiene datos.
Crea un intérprete en /admin/config/regional/recurring-date-interpreters y selecciónalo en los ajustes del formateador de campo. Verifica que el plugin del intérprete esté correctamente configurado.
El módulo valida zonas horarias en la actualización. Ejecuta el hook de actualización proporcionado que identificará valores de zona horaria inválidos que necesitan corrección manual en la base de datos.
Verifica los ajustes del campo para asegurar que al menos una frecuencia con al menos una parte esté habilitada. Si 'Permitir todas las frecuencias y partes' está desmarcado y no hay frecuencias habilitadas, la entrada RRULE se ocultará.
Cada campo date_recur crea su propia tabla de caché de ocurrencias. Para reglas infinitas, los datos de ocurrencias se precrean basándose en el intervalo de precreación. Considera reducir el intervalo de precreación o usar límites COUNT/UNTIL en las reglas para reducir el tamaño de la base de datos.
Security Notes 4
- El módulo tiene cobertura de avisos de seguridad 'covered' del equipo de seguridad de Drupal
- Los valores de zona horaria se validan contra timezone_identifiers_list() de PHP para prevenir inyección de valores inválidos
- Las cadenas RRULE se validan usando el analizador de la biblioteca php-rrule para asegurar que solo se almacenen reglas válidas
- El ajuste de almacenamiento rrule_max_length proporciona protección contra cadenas RRULE extremadamente largas que podrían impactar el rendimiento