Usage example of date elements within forms

* Enable the Date API module (you might want to add a dependency in the .info file of your module). * Date API uses hook_elements() to create custom form types. You can check the file date_api_elements.inc for the list of form types available, and for other configuration options.

Adding a date form element is then easy.

<?php
/**
 * Your form builder.
 */
function mymodule_form($form_state) {
  $form = array();

  // [...snip...] add many fields to your form

  // Creating the date/time element starts here

  // Provide a default date in the format YYYY-MM-DD HH:MM:SS.
  $date = '2008-12-31 00:00:00';

  // Provide a format using regular PHP format parts (see documentation on php.net).
  // If you're using a date_select, the format will control the order of the date parts in the selector,
  // rearrange them any way you like. Parts left out of the format will not be displayed to the user.
  $format = 'Y-m-d H:i';

  $form['date2'] = array(
     '#type' => 'date_select', // types 'date_text', 'date_timezone', and 'date_year_range' are also supported. See .inc file.
     '#title' => 'select a date',
     '#default_value' => $date, 
     '#date_format' => $format,
     '#date_label_position' => 'within', // See other available attributes and what they do in date_api_elements.inc
     '#date_timezone' => 'America/Chicago', // Optional, if your date has a timezone other than the site timezone.
     '#date_increment' => 15, // Optional, used by the date_select and date_popup elements to increment minutes and seconds.
     '#date_year_range' => '-3:+3', // Optional, used to set the year range (back 3 years and forward 3 years is the default).
  );

  // [...snip...] more fields, including the 'submit' button.

  return $form;
}
?>

These are self-validating elements, you shouldn't need to do anything except include them in your form. You pass them parameters for the timezone, format, and a default value in the format YYYY-MM-DD HH:MM:SS, and it will convert your input into the format the element wants, split the date and time into different fields as needed, then accept and validate the user input and convert it back into a string in the same format you originally provided (YYYY-MM-DD HH:MM:SS). So you pass it a string and it will pass back a string by the time you get to your own validation function.

You are responsible for doing your own timezone conversion, the element uses the timezone just so it can create a date object with the right timezone for doing its formatting. So if you need to do timezone conversion, you pull your UTC date out of the database and convert it to a local date, pass that value to the Date element, then take what it returns and convert it back to UTC and store it in the database again.

If the Date Popup module is enabled, a date_popup element can be used. It works like the other elements, but splits the date and time into separate parts. You control whether it uses date or date and time by the format you supply in #date_format. If you don't have any time parts in the format, you won't get a time element. Note that the jquery widget (the 'date' part of the popup) can only accept a limited number of formats, things like Y-m-d or m/d/Y or d.m.Y.