Date 2.0 for Drupal 6

Note! Views2 API Changes! The latest D6 -dev version uses the new Views2 API and requires the latest -dev version of Date, Calendar, CCK, and Views to work right. The changes involve some re-organization of files and folders, so empty the date folder out before adding in the updated files.

Important Notices

• The new version has several new files and is completely re-organized. To upgrade smoothly from Date 5.1 to Date 5.2, take the following steps:
  1. Disable all the Date modules (and any modules that are dependent on Date or Date API
  2. Empty the module folder completely before adding the contents of the new version. If you don't do that, Drupal may try to use some of the invalid, older files and things will not work correctly.
  3. After updating the files on your system, visit the modules page and look for the new Date/Time section and enable the new modules.
  4. Visit update.php to update your database.
• If you use the Token module, be sure to use the latest version of it. The older version was using the older Date API.
• Version 2 of the Event module is currently incompatible with the Date API, since the Event module has a different method for setting site and user timezones that keeps the Date API from working correctly. The Date Copy module has a conversion program to convert Event fields to Date fields, if you want to switch to using Date and Calendar.

New Features

• The Date API now uses PHP 5.2 date functions for better date and timezone handling (and has PHP 4 emulations for those functions so the module will work in PHP4). Although the code will work with PHP 4, it is significantly faster and more efficient under PHP 5.2 or higher, so PHP 5.2 is highly recommended.
• The database query handling has been completely re-worked to take advantage of database timezone handling when available, with a fallback to the older and less reliable method of using offsets to do timezone adjustments.
• No more need for the adodb date library, historical dates earlier than 1970 and later than 2038 are handled without any external code.
• iCal integration is greatly improved, an iCal parser can parse events, alarms, most types of dates and timezones, duration, repeat rules, and more.
• The Date API creates date elements that can be used by any module, including 'date_select', 'date_textfield', and 'date_timezone'.
• A new Date Timezone module overrides the site and user timezone selectors to allow you to select a timezone name instead of a timezone offset, and that stored name is used to properly adjust date values. It also detects the user's timezone name automatically and updates the user record with that name.
• A new Date Popup module creates a jQuery popup calendar date picker and time picker, and the element is available to other modules as a form type of 'date_popup'.
• The Date module now has lots of new ways to define default values -- you can set a the default to 'blank', 'now', or 'relative', where relative is something like '+90 days'. The To date has a separate default value, which can be the same as the From date or do something different.
• A Date Repeat API module has been added which can be used by any other module. The CCK Date module uses it to allow you to select 'repeating' as a type of multiple date, present the user with a form to select the repeat rules for their date, and then create all the multiple values that match those rules.

Date Fields

The CCK Date field uses the Date API to create date fields and widgets.

You have a choice of creating an ISO date or a unix timestamp. If you are porting information from another application you may want to create a field using a type that matches the source data. Some advantages and disadvantages of each include:

Datestamp (Unix Timestamp)

• Stores the date as an integer.
• Takes up less room in the database because it's smaller.
• Often easier to use for date calculations because you can increase or decrease it just by adding or subtracting seconds.
• It is the format used by php date functions.
• It must be filled with a complete date -- year, month, day, hour, minute, second, so you sometimes have to arbitrarily set some of these values even if they are not applicable.

Date (ISO Date)

• Stores the date in an ISO format (YYYY-MM-DDTHH:MM:SS).
• The data is in a human-readable form.
• You can use it for incomplete dates, i.e. only a year or only a year and a month, and pad the other values with zeros, so it does not appear to be any more precise than it really is.
• It is a format that is internationally-recognized, and it is used as-is on many web sites and in many applications.

Datetime

• Stores the date in the database's native date format (YYYY-MM-DD HH:MM:SS).
• The data is in a human-readable form.
• You can use it for incomplete dates, i.e. only a year or only a year and a month, and pad the other values with zeros, so it does not appear to be any more precise than it really is.
• It can take advantage of the database's date handling functions without any conversion.

Date Widgets

There are several widgets to choose from to control how users can enter data for this field.

Text Field

The Text Field date widget uses a custom format set in the field settings, like '31.12.2008'. As a fallback the widget will try to accept input allowed by the php strtotime function. This allows the user to type a date in in many natural formats, like 'March 31, 1980'.
There are limitations to strtotime, so setting a custom format is more reliable. The strtotime function will assume date shortcuts are in American format (MM/DD/YY), and strtotime will not work for dates prior to 1970.

Select List

The Select List date widget presents users with a drop-down list or textfield for each part of the date (year, month, day, hour, etc.). The whole selector is collapsed onto a single line using css (except for the timezone selector, if date-specific timezones are collected). The selector is highly configurable and you can set it up to use 5, 10, or 15 minute increments for minutes and seconds, or make some parts of the selector use textfields instead of drop-downs, useful to allow any year without creating a huge drop-down selector.

jQuery Pop-up Calendar

The Javascript Pop-up Calendar is offered as an input alternative if the Date Popup module is installed. The date is split into date and time fields, and the date field uses a jQuery popup calendar and the time field uses a jQuery timeselector widget that only allows valid time input.

If you have the Date Repeat module enabled, you will also see options for each of those widgets that include a repeat options selection form that will allow the user to choose values like 'Every week' or 'The last Tuesday'.