1 |
85ad3d82
|
Assos Assos
|
INFORMATION FOR DEVELOPERS
|
2 |
|
|
|
3 |
|
|
Once the Date API is installed, all functions in the API are available to be
|
4 |
|
|
used anywhere by any module.
|
5 |
|
|
|
6 |
|
|
The API uses the PHP 5.2 date functions to create and manipulate dates.
|
7 |
|
|
|
8 |
|
|
Example, the following will create a date for the local value in one
|
9 |
|
|
timezone, adjust it to a different timezone, then return the offset in seconds
|
10 |
|
|
in the new timezone for the input date; The offset will be adjusted for both
|
11 |
|
|
the timezone difference and daylight savings time, if necessary:
|
12 |
|
|
|
13 |
|
|
$date = date_create('2007-03-11 02:00:00', timezone_open('America/Chicago'));
|
14 |
|
|
$chicago_time = date_format($date, 'Y-m-d H:i');
|
15 |
|
|
|
16 |
|
|
print 'At '. $chicago_time .' in Chicago, the timezone offset in seconds
|
17 |
|
|
was '. date_offset_get($date);
|
18 |
|
|
|
19 |
|
|
date_timezone_set($date, timezone_open('Europe/Berlin');
|
20 |
|
|
$berlin_time = date_format($date, 'Y-m-d H:i');
|
21 |
|
|
|
22 |
|
|
print 'It was '. $berlin_time .' in Berlin when it
|
23 |
|
|
was '. $chicago_time .' in Chicago.';
|
24 |
|
|
print 'At that time in Berlin, the timezone offset in seconds was
|
25 |
|
|
'. date_offset_get($date);
|
26 |
|
|
|
27 |
|
|
A helper class is available, new DateObject($string, $timezone, $format), where
|
28 |
|
|
$string is a unixtimestamp, an ISO date, or a string like YYYY-MM-DD HH:MM:SS,
|
29 |
|
|
$timezone is the name of the timezone this date is in, and $format is the format
|
30 |
|
|
of date it is (DATE_FORMAT_UNIX, DATE_FORMAT_ISO, or DATE_FORMAT_DATETIME). It
|
31 |
|
|
creates and return a date object set to the right date and timezone.
|
32 |
|
|
|
33 |
|
|
Simpletest tests for these functions are included in the package.
|
34 |
|
|
|
35 |
|
|
Available functions include the following (more documentation is provided in
|
36 |
|
|
the files):
|
37 |
|
|
|
38 |
|
|
============================================================================
|
39 |
|
|
Preconfigured arrays
|
40 |
|
|
============================================================================
|
41 |
|
|
Both translated and untranslated values are available. The
|
42 |
|
|
date_week_days_ordered() function will shift an array of week day names so it
|
43 |
|
|
starts with the site's first day of the week, otherwise the weekday names start
|
44 |
|
|
with Sunday as the first value, which is the expected order for many php and sql
|
45 |
|
|
functions.
|
46 |
|
|
|
47 |
|
|
date_month_names();
|
48 |
|
|
date_month_names_abbr();
|
49 |
|
|
date_month_names_untranslated();
|
50 |
|
|
date_week_days();
|
51 |
|
|
date_week_days_abbr();
|
52 |
|
|
date_week_days_untranslated();
|
53 |
|
|
date_week_days_ordered();
|
54 |
|
|
date_years();
|
55 |
|
|
date_hours();
|
56 |
|
|
date_minutes();
|
57 |
|
|
date_seconds();
|
58 |
|
|
date_timezone_names();
|
59 |
|
|
date_ampm();
|
60 |
|
|
|
61 |
|
|
============================================================================
|
62 |
|
|
Miscellaneous date manipulation functions
|
63 |
|
|
============================================================================
|
64 |
|
|
Pre-defined constants and functions that will handle pre-1970 and post-2038
|
65 |
|
|
dates in both PHP 4 and PHP 5, in any OS. Dates can be converted from one
|
66 |
|
|
type to another and date parts can be extracted from any date type.
|
67 |
|
|
|
68 |
|
|
DATE_DATETIME
|
69 |
|
|
DATE_ISO
|
70 |
|
|
DATE_UNIX
|
71 |
|
|
DATE_ARRAY
|
72 |
|
|
DATE_OBJECT
|
73 |
|
|
DATE_ICAL
|
74 |
|
|
|
75 |
|
|
date_convert()
|
76 |
|
|
date_is_valid();
|
77 |
|
|
date_part_is_valid();
|
78 |
|
|
date_part_extract();
|
79 |
|
|
|
80 |
|
|
============================================================================
|
81 |
|
|
Date calculation and navigation
|
82 |
|
|
============================================================================
|
83 |
|
|
date_difference() will find the time difference between any two days, measured
|
84 |
|
|
in seconds, minutes, hours, days, months, weeks, or years.
|
85 |
|
|
|
86 |
|
|
date_days_in_month();
|
87 |
|
|
date_days_in_year();
|
88 |
|
|
date_weeks_in_year();
|
89 |
|
|
date_last_day_of_month();
|
90 |
|
|
date_day_of_week();
|
91 |
|
|
date_day_of_week_name();
|
92 |
|
|
date_difference();
|
93 |
|
|
|
94 |
|
|
============================================================================
|
95 |
|
|
Date regex and format helpers
|
96 |
|
|
============================================================================
|
97 |
|
|
Pre-defined constants, an array of date format strings and their
|
98 |
|
|
equivalent regex strings.
|
99 |
|
|
|
100 |
|
|
DATE_REGEX_LOOSE is a very loose regex that will pull date parts out
|
101 |
|
|
of an ISO date with or without separators, using either 'T' or a space
|
102 |
|
|
to separate date and time, and with or without time.
|
103 |
|
|
|
104 |
|
|
date_format_date() is similar to format_date(), except it takes a
|
105 |
|
|
date object instead of a timestamp as the first parameter.
|
106 |
|
|
|
107 |
|
|
DATE_FORMAT_ISO
|
108 |
|
|
DATE_FORMAT_DATETIME
|
109 |
|
|
DATE_FORMAT_UNIX
|
110 |
|
|
DATE_FORMAT_ICAL
|
111 |
|
|
|
112 |
|
|
DATE_REGEX_ISO
|
113 |
|
|
DATE_REGEX_DATETIME
|
114 |
|
|
DATE_REGEX_LOOSE
|
115 |
|
|
|
116 |
|
|
date_format_date();
|
117 |
|
|
date_short_formats();
|
118 |
|
|
date_medium_formats();
|
119 |
|
|
date_long_formats();
|
120 |
|
|
date_format_patterns();
|
121 |
|
|
|
122 |
|
|
============================================================================
|
123 |
|
|
Standardized ical parser and creator
|
124 |
|
|
============================================================================
|
125 |
|
|
The iCal parser is found in date_api_ical.inc, which is not included by default.
|
126 |
|
|
Include that file if you want to use these functions:
|
127 |
|
|
|
128 |
|
|
Complete rewrite of ical imports to parse vevents, vlocations, valarms,
|
129 |
|
|
and all kinds of timezone options and repeat rules for ical imports.
|
130 |
|
|
The function now sticks to parsing the ical into an array that can be used
|
131 |
|
|
in various ways. It no longer trys to convert timezones while parsing,
|
132 |
|
|
instead a date_ical_date_format() function is provided that can be used to
|
133 |
|
|
convert from the ical timezone to whatever timezone is desired in the
|
134 |
|
|
results. Repeat rules are parsed into an array which other modules can
|
135 |
|
|
manipulate however they like to create additional events from the results.
|
136 |
|
|
|
137 |
|
|
date_ical_export();
|
138 |
|
|
date_ical_import();
|
139 |
|
|
date_ical_date_format();
|
140 |
|
|
|
141 |
|
|
============================================================================
|
142 |
|
|
Helpers for portable date SQL
|
143 |
|
|
============================================================================
|
144 |
|
|
The SQL functions are found in date_api_sql.inc, which is not included by
|
145 |
|
|
default. Include that file if you want to use these functions:
|
146 |
|
|
|
147 |
|
|
date_sql();
|
148 |
|
|
date_server_zone_adj();
|
149 |
|
|
date_sql_concat();
|
150 |
|
|
date_sql_pad();
|
151 |
|
|
|
152 |
|
|
============================================================================
|
153 |
|
|
Date forms and validators
|
154 |
|
|
============================================================================
|
155 |
|
|
Reusable, configurable, self-validating FAPI date elements are found in
|
156 |
|
|
date_api_elements.inc, which is not included by default. Include it
|
157 |
|
|
if you want to use these elements. To use them, create a form element
|
158 |
|
|
and set the '#type' to one of the following:
|
159 |
|
|
|
160 |
|
|
date_select
|
161 |
|
|
The date_select element will create a collection of form elements, with a
|
162 |
|
|
separate select or textfield for each date part. The whole collection will
|
163 |
|
|
get reformatted back into a date value of the requested type during validation.
|
164 |
|
|
|
165 |
|
|
date_text
|
166 |
|
|
The date_text element will create a textfield that can contain a whole
|
167 |
|
|
date or any part of a date as text. The user input value will be re-formatted
|
168 |
|
|
back into a date value of the requested type during validation.
|
169 |
|
|
|
170 |
|
|
date_timezone
|
171 |
|
|
The date_timezone element will create a drop-down selector to pick a
|
172 |
|
|
timezone name.
|
173 |
|
|
|
174 |
|
|
The custom date elements require a few other pieces of information to work
|
175 |
|
|
correctly, like #date_format and #date_type. See the internal documentation
|
176 |
|
|
for more information.
|
177 |
|
|
|
178 |
|
|
============================================================================
|
179 |
|
|
Date Popup Module
|
180 |
|
|
============================================================================
|
181 |
|
|
|
182 |
|
|
A new module is included in the package that will enable a popup jQuery
|
183 |
|
|
calendar date picker and timepicker in date and time fields.
|
184 |
|
|
|
185 |
|
|
It is implemented as a custom form element, so set '#type' to 'date_popup'
|
186 |
|
|
to use this element. See the internal documentation for more information.
|
187 |
|
|
|
188 |
|
|
============================================================================
|
189 |
|
|
Date Repeat API
|
190 |
|
|
============================================================================
|
191 |
|
|
|
192 |
|
|
An API for repeating dates is available if installed. It can be used by
|
193 |
|
|
other modules to create a form element that will allow users to select
|
194 |
|
|
repeat rules and store those selections in an iCal RRULE string, and a
|
195 |
|
|
calculation function that will parse the RRULE and return an array of dates
|
196 |
|
|
that match those rules. The API is implemented in the Date module as a
|
197 |
|
|
new date widget if the Date Repeat API is installed.
|
198 |
|
|
|
199 |
|
|
============================================================================
|
200 |
|
|
RDF Integration
|
201 |
|
|
============================================================================
|
202 |
|
|
|
203 |
|
|
To make RDF easier to use, the base date themes (date_display_single and
|
204 |
|
|
date_display_range) have been expanded so they pass attributes and
|
205 |
|
|
RDF mappings for the field, if any, to the theme. If RDF is installed
|
206 |
|
|
and no other mappings are provided, the theme adds RDF information
|
207 |
|
|
to mark both the Start and End dates as 'xsd:dateTime' datatypes with the
|
208 |
|
|
property of 'dc:date'. This occurs in the theme preprocess layer, in
|
209 |
|
|
particular via the functions template_preprocess_date_display_single() and
|
210 |
|
|
template_preprocess_date_display_range().
|
211 |
|
|
|
212 |
|
|
To mark these as events instead, you could install the schemaorg
|
213 |
|
|
module, which will load the schema.org vocabulary. The mark the content type
|
214 |
|
|
that contains events as an 'Event', using the UI exposed by that
|
215 |
|
|
module and set the event start date field with the 'dateStart'
|
216 |
|
|
property and tag other fields in the content type with the appropriate
|
217 |
|
|
property types. The Date module theme will wrap the start and end
|
218 |
|
|
date output with appropriate markup.
|
219 |
|
|
|
220 |
|
|
If the result is not quite what you need, you should be able to implement your
|
221 |
|
|
own theme preprocess functions, e.g. MYTHEME_preprocess_date_display_single()
|
222 |
|
|
or MYTHEME_preprocess_date_display_range() and alter the attributes to use the
|
223 |
|
|
values you want. |