Duration Field
Crea un campo de la Field API para duraciones que recopila períodos de tiempo con granularidad configurable incluyendo años, meses, días, horas, minutos y segundos.
duration_field
Instalar
composer require 'drupal/duration_field:8.x-2.2'
composer require 'drupal/duration_field:8.x-2.1'
Overview
El módulo Duration Field proporciona una solución integral para recopilar y mostrar períodos de tiempo en Drupal. Crea tanto un elemento de formulario de la Form API como un campo de la Field API de tipo 'duration'. Una duración representa un período de tiempo con granularidad configurable, permitiendo a los sitios recopilar cualquier combinación de años, meses, días, horas, minutos y segundos.
Los valores de duración se almacenan internamente como cadenas de duración ISO 8601 (por ejemplo, P1Y2M3DT4H5M6S), que proporcionan un formato estandarizado para representar intervalos de tiempo. Además, el módulo almacena la duración en segundos para permitir consultas de comparación matemática en la base de datos.
El módulo no hace suposiciones sobre qué unidades de tiempo necesita recopilar un usuario, ofreciendo flexibilidad completa. Por ejemplo, un sitio podría configurar un campo para recopilar solo horas y minutos para la duración de un turno de trabajo, o años y meses para un período de contrato. El módulo también soporta un campo opcional de semanas para casos de uso que requieren cálculos basados en semanas.
Features
- Proporciona un tipo de campo 'duration' para entidades con granularidad de unidad de tiempo configurable (años, meses, días, horas, minutos, segundos)
- Almacena duraciones en formato ISO 8601 para estandarización y como segundos para consultas de comparación en base de datos
- Ofrece tres formateadores de visualización: Amigable para humanos (ej., '2 years 3 months'), Cadena de duración (ISO 8601) y Formato de tiempo (AA/MM/DD HH:MM:SS)
- Incluye elementos de la Form API tanto para entrada de duración como para configuración de granularidad
- Soporta campo opcional de semanas además de los componentes estándar de duración ISO 8601
- Proporciona la etiqueta de consulta 'duration_string' para comparar duraciones usando cadenas ISO 8601 en consultas de base de datos
- Incluye servicios para convertir entre formatos de duración, validar cadenas ISO 8601 y calcular segundos desde intervalos
- Separadores de formateador extensibles mediante hook_duration_field_separators() y hook_duration_field_labels()
- Comando Drush para preparar de forma segura la desinstalación del módulo eliminando todos los datos de campos de duración
- Soporte completo para AJAX y #states en elementos de formulario de duración
- Pasos de incremento configurables para entrada de duración (ej., intervalos de 15 minutos)
- Soporte para JSON API y serialización mediante el normalizador DateIntervalData
Use Cases
Duración de turno de trabajo de empleado
Crea un campo de duración con granularidad configurada en horas y minutos (h:i) para recopilar la duración de los turnos de trabajo. Usa el formateador Amigable para humanos para mostrar valores como '8 hours 30 minutes' en los horarios de empleados.
Tiempo de cocción de receta
Añade un campo de duración a un tipo de contenido Receta con granularidad de horas y minutos. Configura el formateador con longitud de texto corta y separador de coma para mostrar '1 hr, 30 min' para el tiempo total de cocción de una receta.
Estimaciones de cronograma de proyecto
Crea un campo de duración con semanas habilitadas y granularidad de meses/semanas/días para gestión de proyectos. El campo de semanas permite una planificación de proyectos más natural mientras mantiene la compatibilidad con ISO 8601.
Duración de contenido de video/audio
Usa granularidad de horas, minutos y segundos (h:i:s) para contenido multimedia. El formateador de Formato de tiempo muestra valores como '01:45:30' que es familiar para los usuarios para tiempos de reproducción de medios.
Configuración de período de suscripción
Configura un campo de duración con granularidad de años y meses para servicios de suscripción. El almacenamiento de cadena ISO 8601 (ej., 'P1Y6M') proporciona un formato estandarizado para procesamiento programático.
Duración de evento con consultas de base de datos
Crea un listado de eventos que filtra por duración. Usa la etiqueta de consulta 'duration_string' para encontrar eventos más largos de 2 horas usando una condición ISO 8601 como 'PT2H' que automáticamente compara contra el valor almacenado en segundos.
Tips
- Usa la propiedad #date_increment en elementos de formulario de duración para restringir la entrada a intervalos específicos (ej., 900 para incrementos de 15 minutos, 3600 para incrementos por hora)
- El elemento 'duration' de la Form API puede usarse independientemente en formularios personalizados - simplemente añade '#type' => 'duration' con propiedades opcionales #granularity y #required_elements
- Para acceso programático, usa el duration_field.service para convertir entre cadenas ISO 8601, objetos PHP DateInterval y segundos según sea necesario
- Al consultar duraciones, etiqueta tu consulta con 'duration_string' para comparar usando valores ISO 8601 legibles para humanos en lugar de segundos crudos
- Los separadores personalizados para el formateador Amigable para humanos pueden añadirse implementando tanto hook_duration_field_separators() como hook_duration_field_labels() en tu módulo
Technical Details
Hooks 3
hook_duration_field_separators
Permite a los módulos añadir separadores personalizados entre valores de tiempo en el formateador Amigable para humanos. Debe implementarse junto con hook_duration_field_labels().
hook_duration_field_labels
Proporciona etiquetas traducidas para separadores personalizados añadidos mediante hook_duration_field_separators(). Debe implementarse cuando se añaden separadores personalizados.
hook_query_duration_string_alter
Implementación de hook interno que permite consultar campos de duración usando cadenas ISO 8601 convirtiéndolas a segundos para comparación. Etiqueta las consultas con 'duration_string' para habilitar este comportamiento.
Drush Commands 1
drush duration_field:prepare_uninstall
Prepara el módulo Duration Field para la desinstalación eliminando todos los datos de campos de duración y las configuraciones de campos. Esta es una operación destructiva con solicitud de confirmación.
Troubleshooting 4
Ejecuta los update hooks (drush updatedb) que manejan la migración desde la antigua columna 'value' a las nuevas columnas 'duration' y 'seconds', y convierten las configuraciones de granularidad de formato array a cadena.
Usa el comando Drush 'drush duration_field:prepare_uninstall' (o alias 'drush df-pu') para eliminar todas las configuraciones de campo de duración y datos antes de intentar desinstalar el módulo.
Asegúrate de que las consultas estén etiquetadas con 'duration_string' para habilitar la conversión automática de condiciones de duración ISO 8601 a comparaciones basadas en segundos. El módulo usa la columna 'seconds' para operaciones matemáticas.
Habilita 'Include weeks' en las configuraciones del campo. Las semanas se almacenan separadamente de la cadena de duración ISO 8601 (que no soporta semanas) y deben habilitarse explícitamente por campo.