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'.

Comments

Sunshiney’s picture

For those of us who are newbies, I find it helpful to know what's obvious to others but very important to my world. In this instance, I find it helpful to know:

datetime field --> The DATETIME type is used when you need values that contain both date and time information
date field --> The DATE type is used when you need values that contain only date information

Seemed intuitive until I read that date field was used for incomplete dates. ...made me wonder if I could use it for complete dates.

MaskedMarauder’s picture

also for us newbies, are there any hints on how to theme dates? In particular, repeating dates?

Using repeating dates for a regular event can generate nodes that go on for miles. It'd be a big help to have a theme for repeated dates that just returns NULL, but I can't figure out how to interdict the rendering just there.

GreenSpiderDesign’s picture

I am using a Date field to track starting and expiring dates for coupons and in order to have a coupon always appear "fresh," rather than simply having an expiration date of next year sometime, I am using the Repeat option. So a coupon basically renews every month. On the node for the coupon itself I want to only display the expiration date for the current month. So I have tried putting a 1 in the "show ___ value(s)" field, but I cannot figure out what to put in either the "starting from _______" or the "ending on _______" fields in order to only get the next expiration (or "To") date. I have tried >= now, >= "now", now, etc. but nothing works for me.

Can anyone point me to what options can be used in these fields? Thus far I have found ZERO documentation on these two fields.

Oh, and I also select Hide repeat rule in order to keep all of the dates from showing, which I think is the answer to one of the other questons here posted in early August 2009. :)

nicknickoli’s picture

This might be helpful for themeing info- http://drupal.org/node/295105

philsward’s picture

Yes, I know the subject sort probably incorrectly displays some functions but I'm trying to get this SEO'd... Why this is not explained in the docs is beyond me, but I ran across a website that explains all of the string based options that can be used in the To / From date options. I searched on this in the past and couldn't find anything on it but just so happened to run across a site that does a great job explaining what you can plugin to those fields, beyond the generic examples of "now" or "now +1 month".

http://hostharbour.com/php_date.php

Additional Resources: (Actual PHP Manual Stuff)
Support Date and Time Formats
- Time Formats
- Date Formats
- Compound Formats
- Relative Formats

jshock’s picture

Is there a trick to filtering dates, or using arguments to select Dates in Views? For example, I have a custom field called event_date that lets me enter a date using the jquery popup calendar. I am using Views to select all the events in a particular year. It doesn't work. I am beginning to think that simply using the argument "2009" isn't enough (I have Views granularity set to "Year"). Does the Date module store the data in some wierd way that Views can't understand, like epoch/seconds or something?

Yes, I'm a noob, however I have spent many hours trying to figure this out by reading the documentation, visiting the forums etc. I think I am missing some basic understanding of Dates that everyone else take for granted : )

Balu Ramamurthy’s picture

Hi,

I am trying to create a popup for a date field in form api i have created. I am getting just a empty text box,the pop up doesn't appear when I use the following code. I have drupal 6.22 with date api 2.0 and I also have the latest cck.

   
  $form['sd'] = array(
  '#type' => 'date_popup',
  '#date_format' => 'm-d-Y',
  '#date_label_position' => 'within',
  '#date_year_range' => '-100:+0',
  '#prefix' => '<tr> <td> Start Date : </td> <td>',
  '#suffix' => '</td>',
  );

Please can someone help me with this. I am not sure what I am doing wrong in this and I am not able to find any help regarding this online too

Thanks and regards,
Balu