Projet

Général

Profil

Révision 599a39cd

Ajouté par Assos Assos il y a environ 3 ans

Weekly update of contrib modules

Voir les différences:

drupal7/sites/all/modules/date/README.txt
1
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.
1
Date
2
----
3
The Date module suite provides an API for handling date values, a field for
4
Drupal 7's Field API system, and a wealth of submodules for various purposes.
5

  
6
The following modules are included in the Date package, many of which have their
7
own README.txt files with further information:
8

  
9
* date_api/date_api.module:
10
  A dependency for all of the other modules, provides a slew of APIs for the
11
  other modules to leverage.
12

  
13
* date.module:
14
  Provides the Field API integration necessary to use date fields in the Drupal
15
  7 UI, or in custom modules.
16

  
17
* date_all_day/date_all_day.module:
18
  Provides the option to add an 'All Day' checkbox to toggle time on and off
19
  for date fields. It also contains the theme that displays the 'All Day' text
20
  on fields that have no time.
21

  
22
* date_context/date_context.module
23
  Provides integration with the Context module [1], allowing the date to be used
24
  as a condition on context definitions.
25

  
26
* date_popup/date_popup.module
27
  Adds a field widget for use with date and time fields that uses a jQuery-based
28
  calendar-style date picker and timepicker.
29

  
30
* date_repeat/date_repeat.module
31
  Provides an API for calculating repeating dates and times from iCal rules.
32

  
33
* date_repeat/date_repeat_field.module
34
  Creates the option of repeating date fields and manages Date fields that use
35
  the Date Repeat API.
36

  
37
* date_tools/date_tools.module
38
  Provides functionality for importing content with dates.
39

  
40
* date_views/date_views.module
41
  Adds integration with the Views module [2] for adding date fields and filters
42
  to views.
43

  
44

  
45
Credits / contact
46
--------------------------------------------------------------------------------
47
Currently maintained by Andrii Podanenko [3], Alex Schedrov [4], Damien McKenna
48
[5] and Vijaya Chandran Mani [6]. Previous maintainers included Angie Byron
49
[7], Arlin Sandbulte [8], David Goode [9], Derek Wright [10], developer-x [11]
50
and Peter Lieverdink [12].
51

  
52
Originally written and maintained by Karen Stevenson [13].
53

  
54
The best way to contact the authors is to submit an issue, be it a support
55
request, a feature request or a bug report, in the project issue queue:
56
  https://www.drupal.org/project/issues/date
57

  
58

  
59
References
60
--------------------------------------------------------------------------------
61
1: https://www.drupal.org/project/context
62
2: https://www.drupal.org/project/views
63
3: https://www.drupal.org/u/podarok
64
4: https://www.drupal.org/u/sanchiz
65
5: https://www.drupal.org/u/damienmckenna
66
6: https://www.drupal.org/u/vijaycs85
67
7: https://www.drupal.org/u/webchick
68
8: https://www.drupal.org/u/arlinsandbulte
69
9: https://www.drupal.org/user/291318
70
10: https://www.drupal.org/u/dww
71
11: https://www.drupal.org/user/399625
72
12: https://www.drupal.org/u/cafuego
73
13: https://www.drupal.org/u/karens

Formats disponibles : Unified diff