Smart Date
Provides an enhanced date range field type with intelligent admin UI, all-day event support, sophisticated formatting options, and timestamp-based storage for optimal performance.
smart_date
Install
composer require 'drupal/smart_date:^4.2'
Overview
Smart Date is a comprehensive Drupal module that upgrades the datetime functionality in core with a more user-friendly approach. It provides a date range field type that stores start and end times as timestamps, enabling excellent performance when filtering or sorting.
The module introduces the concept of duration in the admin interface, allowing fields to have a default duration (e.g., 1 hour) where the end time is automatically populated based on the start. This creates an intuitive time range/event data entry experience similar to calendar applications that editors are familiar with.
Smart Date also provides rich formatting options through a new configuration entity called "Smart Date Format". This allows site builders to control how date ranges are output at a very granular level, including options for showing dates compactly (e.g., showing the date only once when start and end are on the same day), customizing separators, and handling all-day events with configurable labels.
An optional submodule (Smart Date Recurring) extends the functionality to support recurring events using iCalendar RRULE specifications, with a comprehensive UI for managing individual instances.
Features
- Smart date range field type storing start/end times as timestamps for maximum performance
- Duration-based admin UI with auto-population of end times based on configurable default durations
- All-day event support with one-click toggle, similar to calendar applications
- Sophisticated formatting options through Smart Date Format configuration entities
- Intelligent date range display that avoids redundant output (e.g., single date shown when start/end are same day)
- AM/PM reduction following Associated Press style guide recommendations
- Multiple widget options: Classic, Inline range, Date-only range, Inline with timezone, and Select list
- Multiple formatter options: Default, Plain (ISO 8601), Custom, and Duration-based
- Views integration with enhanced date filters supporting granularity and date range operators
- Token integration for Smart Date fields
- Twig extension for formatting dates in templates
- Support for core daterange fields using Smart Date widgets
- Timezone override capabilities at both field and display levels
- JavaScript localization for automatic timezone conversion in the browser
- Drush command for migrating core datetime fields to Smart Date fields
- Feeds module integration for importing Smart Date values
- Diff module integration for comparing Smart Date field revisions
- Full Calendar View processor integration
Use Cases
Event Management
Use Smart Date for event content types where you need to store event start/end times with duration. The all-day checkbox makes it easy to create full-day events, while the duration selector speeds up data entry for events with standard lengths (30 min, 1 hour, 2 hours).
Recurring Events
Enable the Smart Date Recurring submodule to create events that repeat on a schedule. Support for daily, weekly, monthly, and yearly recurrence patterns with options to end after a number of occurrences or on a specific date. Individual instances can be rescheduled or cancelled without affecting the entire series.
Multi-timezone Events
Use the Inline range with timezone widget to allow content editors to specify the timezone for each event. The formatter can then display times in the stored timezone with an option to also show the equivalent time in the user's local timezone.
Date Range Filtering
Leverage the enhanced Views date filter for powerful date range queries. Filter events that contain a specific date, overlap with a date range, or start/end within a period. Granularity options allow filtering by year, month, day, hour, minute, or second.
Migrating from Core Date Fields
Use the included Drush command to migrate existing datetime or daterange fields to Smart Date. This preserves your existing data while gaining access to Smart Date's enhanced formatting and widget options.
Consistent Date Formatting
Create Smart Date Format configurations to ensure consistent date display across your site. Formats can be translated for multilingual sites, and the configurable options handle edge cases like AM/PM reduction and date deduplication automatically.
Tips
- Use the 'Compact' format for space-constrained displays like teasers or lists
- Enable JavaScript localization to automatically show times in the visitor's local timezone
- When migrating from core Date fields, run the Drush command on a staging environment first to verify the migration
- Configure duration increments to match your common event lengths to speed up content entry
- Use the 'Reduce output duplication' option to follow AP style guide recommendations for cleaner date range display
- For hourly or minutely recurring events, the Daily Range formatter provides optimized output grouping instances by day
Technical Details
Admin Pages 3
/admin/config/regional/smart-date
Manage Smart Date Format configuration entities. View, add, edit, and delete format configurations that control how date ranges are displayed throughout the site.
/admin/config/regional/smart-date/add
Create a new Smart Date Format configuration entity with custom date and time formatting options.
/admin/config/regional/smart-date/{smart_date_format}/configure
Modify an existing Smart Date Format configuration.
Permissions 1
Hooks 1
hook_smart_date_format_alter
Allows modules to alter Smart Date formatting before output.
Drush Commands 1
drush smart_date:migrate
Migrate core datetime/daterange fields to Smart Date fields. Copies data from source fields to a destination Smart Date field.
Troubleshooting 5
Ensure the Smart Date field is configured with unlimited cardinality. Recurring values can only be used on fields that allow unlimited values. Check that the 'Allow recurring date values' option is enabled in the field configuration.
All-day events are stored with a specific timezone. If events appear on the wrong date, check that the timezone is being stored correctly. The widget stores the site's timezone for all-day events to ensure consistent display.
Verify that the duration increments are properly configured in the field default value settings. The format should be one value per line, with optional labels separated by a pipe character (e.g., '60|1 hour'). Include 'custom' to allow arbitrary end time entry.
The Smart Date views filter includes granularity options. Check that the granularity is set appropriately for your use case. For date-only comparisons, use 'Day' granularity rather than 'Second'.
Use the Drush command 'drush smart_date_recur:prune-invalid-rules' to remove invalid or orphaned recurrence rules from the database.
Security Notes 2
- The 'administer smart date formats' permission is marked as restricted access and should only be granted to trusted administrators
- Smart Date Recurring permissions (make smart dates recur, reschedule instances, cancel instances) should be carefully assigned based on editorial workflows