[Summary view] [Print] [Text view]

   1  INFORMATION FOR DEVELOPERS
   2  
   3  Once the Date API is installed, all functions in the API are available to be used 
   4  anywhere by any module. If the Date Timezone module is installed, the system site 
   5  timezone selector and the user timezone selectors are overwritten to allow the 
   6  selection of timezone names instead of offsets. Proper timezone conversion 
   7  requires knowledge of those timezone names, something that is not currently 
   8  available in Drupal core, and the change in selectors makes it possible to track it.
   9  
  10  In most cases, you should enable the Date Timezone module any time you use the
  11  Date API to be able to set the site and user timezone names. It is not enabled by 
  12  default in case another module is setting timezone names in the database.
  13  
  14  The API uses the PHP 5.2 date functions to create and manipulate dates, and 
  15  contains an option module that will emulate those functions in earlier versions
  16  of PHP.
  17  
  18  If you are using PHP 4 or PHP 5.0 or 5.1, native date handling won't work right.
  19  Install the Date_PHP4 module to enable wrapper functions so this code will work
  20  in old PHP versions. 
  21  
  22  Example, the following will create a date for the local value in one 
  23  timezone, adjust it to a different timezone, then return the offset in seconds 
  24  in the new timezone for the input date; The offset will be adjusted for both 
  25  the timezone difference and daylight savings time, if necessary:
  26  
  27  $date = date_create('2007-03-11 02:00:00', timezone_open('America/Chicago'));
  28  $chicago_time = date_format($date, 'Y-m-d H:i');
  29  
  30  print 'At '. $chicago_time .' in Chicago, the timezone offset in seconds 
  31    was '. date_offset_get($date);
  32  
  33  date_timezone_set($date, timezone_open('Europe/Berlin');
  34  $berlin_time = date_format($date, 'Y-m-d H:i');
  35  
  36  print 'It was '. $berlin_time .' in Berlin when it 
  37    was '. $chicago_time .' in Chicago.';
  38  print 'At that time in Berlin, the timezone offset in seconds was 
  39    '. date_offset_get($date);
  40  
  41  A helper function is available, date_make_date($string, $timezone, $type),
  42  where $string is a unixtimestamp, an ISO date, or a string like YYYY-MM-DD HH:MM:SS,
  43  $timezone is the name of the timezone this date is in, and $type is the type
  44  of date it is (DATE_UNIX, DATE_ISO, or DATE_DATETIME). It create and return
  45  a date object set to the right date and timezone.
  46  
  47  Simpletest tests for these functions are included in the package.
  48  
  49  Available functions include the following (more documentation is provided in 
  50  the files):
  51  
  52  ============================================================================
  53  Date PHP4 Module
  54  ============================================================================
  55  PHP 4 substitutions for the PHP 5 date functions are supplied. Use the PHP 5 
  56  functions in your code as they would normally be used and the PHP 4 
  57  alternatives will be automatically be substituted in when needed. 
  58  
  59  You cannot do everything with these functions that can be done in PHP 5, but 
  60  you can create dates, find timezone offsets, and format the results. 
  61  Timezone handling uses native PHP 5 functions when available and degrades 
  62  automatically for PHP 4 to use substitutions like those 
  63  provided in previous versions of the Date and Event modules.
  64  
  65  Read the doxygen documentation in this module for more information 
  66  about using the functions in ways that will work in PHP 4.
  67  
  68  Simpletest tests for the PHP 4 equivalent functions are included in the package.
  69  
  70  The following functions are emulated in PHP4:
  71  date_create()
  72  date_date_set()
  73  date_format()
  74  date_offset_get()
  75  date_timezone_set()
  76  timezone_abbreviations_list()
  77  timezone_identifiers_list()
  78  timezone_offset_get()
  79  timezone_open()
  80  
  81  ============================================================================
  82  Preconfigured arrays
  83  ============================================================================
  84  Both translated and untranslated values are available. The date_week_days_ordered()
  85  function will shift an array of week day names so it starts with the site's
  86  first day of the week, otherwise the weekday names start with Sunday as the first
  87  value, the expected order for many php and sql functions.
  88  
  89  date_month_names();
  90  date_month_names_abbr();
  91  date_month_names_untranslated();
  92  date_week_days();
  93  date_week_days_abbr();
  94  date_week_days_untranslated();
  95  date_week_days_ordered();
  96  date_years();
  97  date_hours();
  98  date_minutes();
  99  date_seconds();
 100  date_timezone_names();
 101  date_ampm();
 102  
 103  ============================================================================
 104  Miscellaneous date manipulation functions 
 105  ============================================================================
 106  Pre-defined constants and functions that will handle pre-1970 and post-2038 
 107  dates in both PHP 4 and PHP 5, in any OS. Dates can be converted from one 
 108  type to another and date parts can be extracted from any date type.
 109  
 110  DATE_DATETIME
 111  DATE_ISO
 112  DATE_UNIX
 113  DATE_ARRAY
 114  DATE_OBJECT
 115  DATE_ICAL
 116  
 117  date_convert()
 118  date_is_valid();
 119  date_part_is_valid();
 120  date_part_extract();
 121  
 122  ============================================================================
 123  Date calculation and navigation
 124  ============================================================================
 125  date_difference() will find the time difference between any two days, measured
 126  in seconds, minutes, hours, days, months, weeks, or years.
 127  
 128  date_days_in_month();
 129  date_days_in_year();
 130  date_weeks_in_year();
 131  date_last_day_of_month();
 132  date_day_of_week();
 133  date_day_of_week_name();
 134  date_difference();
 135  
 136  ============================================================================
 137  Date regex and format helpers 
 138  ============================================================================
 139  Pre-defined constants, an array of date format strings and their 
 140  equivalent regex strings.
 141  
 142  DATE_REGEX_LOOSE is a very loose regex that will pull date parts out
 143  of an ISO date with or without separators, using either 'T' or a space
 144  to separate date and time, and with or without time.
 145  
 146  date_format_date() is similar to format_date(), except it takes a 
 147  date object instead of a timestamp as the first parameter.
 148  
 149  DATE_FORMAT_ISO
 150  DATE_FORMAT_DATETIME
 151  DATE_FORMAT_UNIX
 152  DATE_FORMAT_ICAL
 153  
 154  DATE_REGEX_ISO
 155  DATE_REGEX_DATETIME
 156  DATE_REGEX_LOOSE
 157  
 158  date_format_date();
 159  date_t()
 160  date_short_formats();
 161  date_medium_formats();
 162  date_long_formats();
 163  date_format_patterns();
 164  
 165  ============================================================================
 166  Standardized ical parser and creator 
 167  ============================================================================
 168  The iCal parser is found in date_api_ical.inc, which is not included by default. 
 169  Include that file if you want to use these functions:
 170  
 171  Complete rewrite of ical imports to parse vevents, vlocations, valarms, 
 172  and all kinds of timezone options and repeat rules for ical imports. 
 173  The function now sticks to parsing the ical into an array that can be used 
 174  in various ways. It no longer trys to convert timezones while parsing, 
 175  instead a date_ical_date_format() function is provided that can be used to 
 176  convert from the ical timezone to whatever timezone is desired in the 
 177  results. Repeat rules are parsed into an array which other modules can 
 178  manipulate however they like to create additional events from the results.
 179  
 180  date_ical_export();
 181  date_ical_import();
 182  date_ical_date_format();
 183  
 184  ============================================================================
 185  Helpers for portable date SQL 
 186  ============================================================================
 187  The SQL functions are found in date_api_sql.inc, which is not included by default. 
 188  Include that file if you want to use these functions:
 189  
 190  date_sql();
 191  date_server_zone_adj();
 192  date_sql_concat();
 193  date_sql_pad();
 194  
 195  ============================================================================
 196  Date forms and validators
 197  ============================================================================
 198  Reusable, configurable, self-validating FAPI date elements are found in 
 199  date_api_elements.inc, which is not included by default. Include it
 200  if you want to use these elements. To use them, create a form element
 201  and set the '#type' to one of the following:
 202  
 203  date_select 
 204    The date_select element will create a collection of form elements, with a
 205    separate select or textfield for each date part. The whole collection will
 206    get re-formatted back into a date value of the requested type during validation.
 207  
 208  date_text
 209   The date_text element will create a textfield that can contain a whole
 210   date or any part of a date as text. The user input value will be re-formatted
 211   back into a date value of the requested type during validation.
 212  
 213  date_timezone
 214   The date_timezone element will create a drop-down selector to pick a
 215   timezone name.
 216  
 217  The custom date elements require a few other pieces of information to work
 218  correctly, like #date_format and #date_type. See the internal documentation
 219  for more information.
 220  
 221  ============================================================================
 222  Date Popup Module
 223  ============================================================================
 224  
 225  A new module is included in the package that will enable a popup jQuery 
 226  calendar date picker and timepicker in date and time fields.
 227  
 228  It is implemented as a custom form element, so set '#type' to 'date_popup'
 229  to use this element. See the internal documentation for more information.
 230  
 231  ============================================================================
 232  Date Repeat API
 233  ============================================================================
 234  
 235  An API for repeating dates is available if installed. It can be used by 
 236  other modules to create a form element that will allow users to select
 237  repeat rules and store those selections in an iCal RRULE string, and a
 238  calculation function that will parse the RRULE and return an array of dates
 239  that match those rules. The API is implemented in the Date module as a
 240  new date widget if the Date Repeat API is installed.
 241  
 242  ============================================================================
 243  Install file for dependent modules
 244  ============================================================================
 245  
 246  The following code is an example of what should go in the .install file for
 247  any module that uses the new Date API. This is needed to be sure the system 
 248  is not using an earlier version of the API that didn't include all these new 
 249  features. Testing for version '5.2' will pick up any version on or after the 
 250  change to the new API.
 251  
 252  /**
 253   * Implementation of hook_requirements().
 254   */
 255  function calendar_requirements($phase) {
 256    $requirements = array();
 257    $t = get_t();
 258  
 259    // This is the minimum required version for the Date API so that it will 
 260       work with this module.
 261    $required_version = 5.2;
 262  
 263    // Make sure the matching version of date_api is installed.
 264    // Use info instead of an error at install time since the problem may
 265    // just be that they were installed in the wrong order.
 266    switch ($phase) {
 267      case 'runtime':
 268        if (variable_get('date_api_version', 0) < $required_version) {
 269          $requirements['calendar_api_version'] = array(
 270            'title' => $t('Calendar requirements'),
 271            'value' => $t('The Calendar module requires a more current version 
 272               of the Date API. Please check for a newer version.'),
 273            'severity' => REQUIREMENT_ERROR,
 274            );
 275        }
 276        break;
 277       case 'install':
 278        if (variable_get('date_api_version', 0) < $required_version) {
 279          $requirements['calendar_api_version'] = array(
 280            'title' => $t('Calendar requirements'),
 281            'value' => $t('The Calendar module requires the latest version 
 282               of the Date API, be sure you are installing the latest versions 
 283               of both modules.'),
 284            'severity' => REQUIREMENT_INFO,
 285            );
 286        }
 287        break;
 288    }
 289    return $requirements;
 290  }
 291  
 292  /**
 293   * Implementation of hook_install().
 294   */
 295  function calendar_install() {
 296    // Make sure this module loads after date_api.
 297    db_query("UPDATE {system} SET weight = 1 WHERE name = 'calendar'");
 298  }
 299  
 300  /**
 301   * Implementation of hook_update().
 302   */
 303  function calendar_update_5000() {
 304    $ret = array();
 305    $ret[] = update_sql("UPDATE {system} SET weight = 1 WHERE name = 'calendar'");
 306    return $ret;
 307  }