Project

General

Profile

Paste
Download (8.53 KB) Statistics
| Branch: | Revision:

root / drupal7 / sites / all / modules / date_ical / date_ical.api.php @ 55670b15

1
<?php
2
/**
3
 * @file
4
 * Documentation for the hooks provided by Date iCal.
5
 */
6

    
7
/******************************************************************************
8
 * ALTER HOOKS FOR EXPORTED ICAL FEEDS
9
*****************************************************************************/
10

    
11
/**
12
 * Alter the HTML from an event's text fields before they get exported.
13
 *
14
 * Because HTML must be converted to plaintext for iCal spec compliance, this
15
 * hook exists to allow users to alter the original HTML to ensure that it
16
 * gets converted into pretty plaintext.
17
 *
18
 * ONLY <p> tags will be converted to newlines by the plaintext conversion.
19
 *
20
 * @param array $text_fields
21
 *   A reference to an associative array with the following keys and values:
22
 *   - 'description': The description field string.
23
 *   - 'summary': The title field string
24
 *   - 'location': The location field string.
25
 * @param object $view
26
 *   The view object that is being executed to render the iCal feed.
27
 * @param array $context
28
 *   Depending on whether this event is being constructed using the Fields or
29
 *   Entity plugins, this context array will have different keys and values.
30
 *
31
 *   Entity Plugin:
32
 *   - 'entity_type': The type of entity being rendered (e.g. 'node').
33
 *   - 'entity': The fully loaded entity being rendered.
34
 *   - 'language': The language code that indicates which translation of field
35
 *     data should be used.
36
 *
37
 *   Fields Plugin:
38
 *   - 'row': The full Views row object being converted to an event.
39
 *   - 'row_index': The index into the query results for this view.
40
 *   - 'language': The language code that indicates which translation of field
41
 *     data should be used.
42
 *   - 'options': The Fields plugin options.
43
 */
44
function hook_date_ical_export_html_alter(&$text_fields, $view, $context) {
45

    
46
}
47

    
48
/**
49
 * Modify an event's raw data.
50
 *
51
 * This hook is invoked after Date iCal has gathered all the data it will use
52
 * to build an event object.
53
 *
54
 * @param array $event
55
 *   A reference to an associative array containing the event's raw data.
56
 * @param object $view
57
 *   The view object that is being executed to render the iCal feed.
58
 * @param array $context
59
 *   Depending on whether this event is being constructed using the Fields or
60
 *   Entity plugins, this context array will have different keys and values.
61
 *
62
 *   Entity Plugin:
63
 *   - 'entity_type': The type of entity being rendered (e.g. 'node').
64
 *   - 'entity': The fully loaded entity being rendered.
65
 *   - 'language': The language code that indicates which translation of field
66
 *     data should be used.
67
 *
68
 *   Fields Plugin:
69
 *   - 'row': The full Views row object being converted to an event.
70
 *   - 'row_index': The index into the query results for this view.
71
 *   - 'language': The language code that indicates which translation of field
72
 *     data should be used.
73
 *   - 'options': The Fields plugin options.
74
 */
75
function hook_date_ical_export_raw_event_alter(&$event, $view, $context) {
76
  // Example: adding a comment to an event from a simple
77
  // textfield called 'field_comment' (using the Entity plugin).
78
  if ($comments = field_get_items($context['entity_type'], $context['entity'], 'field_comment', $context['language'])) {
79
    foreach ($comments as $comment) {
80
      $event['comment'] = check_plain($comment['value']);
81
    }
82
  }
83
  
84
  // Example: Retrieving information from additional fields in the View (using
85
  // the Fields plugin).
86
  $event['comment'] = $view->style_plugin->get_field($context['row_index'], 'field_comment');
87
}
88

    
89
/**
90
 * Alter an iCal representation of an event.
91
 *
92
 * This hook allows you to modify an event as it is added to the iCal calendar.
93
 * If Date iCal doesn't support an iCal property that you want your feed to
94
 * include, you can add it to the event using this hook.
95
 *
96
 * @param object $vevent
97
 *   A reference to an iCalcreator vevent which will be exported in this feed.
98
 * @param object $view
99
 *   The view object that is being executed to render the iCal feed.
100
 * @param object $event_array
101
 *   The array representation of the event that's been rendered to the $vevent.
102
 */
103
function hook_date_ical_export_vevent_alter(&$vevent, $view, $event_array) {
104

    
105
}
106

    
107
/**
108
 * Alter the iCalcreator vcalendar object before it's exported as an iCal feed.
109
 *
110
 * You can use this hook to add sections to the generated iCal feed which Date
111
 * iCal might not support.
112
 *
113
 * @param object $vcalendar
114
 *   A reference to the iCalcreator vcalendar object representing this feed.
115
 * @param object $view
116
 *   The view object that is being executed to render the iCal feed.
117
 */
118
function hook_date_ical_export_vcalendar_alter(&$vcalendar, $view) {
119

    
120
}
121

    
122
/**
123
 * Alter the final rendered text of an iCal feed before it gets exported.
124
 *
125
 * This is a last resort hook, allowing you to alter the output of the feed
126
 * in case nothing else works.
127
 *
128
 * @param string $rendered_calendar
129
 *   A reference to the string containing the rendered the iCal feed.
130
 * @param object $view
131
 *   The view that is being executed to render this iCal feed.
132
 */
133
function hook_date_ical_export_post_render_alter(&$rendered_calendar, $view) {
134

    
135
}
136

    
137
/******************************************************************************
138
 * ALTER HOOKS FOR IMPORTED ICAL FEEDS
139
 *****************************************************************************/
140

    
141
/**
142
 * Alter the vcalendar object imported from an iCal feed.
143
 *
144
 * @param object $calendar
145
 *   An instance of the iCalcreator library's vcalendar class.
146
 * @param array $context
147
 *   An associative array of context, with the following keys and values:
148
 *   - 'source' FeedsSource object for this Feed.
149
 *   - 'fetcher_result': The FeedsFetcherResult object for this Feed.
150
 */
151
function hook_date_ical_import_vcalendar_alter(&$calendar, $context) {
152

    
153
}
154

    
155
/**
156
 * Alter a calendar component imported from an iCal feed.
157
 *
158
 * @param object $component
159
 *   This will usually be an iCalcreator vevent object, but Date iCal also
160
 *   experimentally supports vtodo, vjournal, vfreebusy, and valarm.
161
 * @param array $context
162
 *   An associative array of context, with the following keys and values:
163
 *   - 'calendar': The iCalcreator vcalendar parent object of this component.
164
 *   - 'source': FeedsSource object for this Feed.
165
 *   - 'fetcher_result': The FeedsFetcherResult object for this Feed.
166
 */
167
function hook_date_ical_import_component_alter(&$component, $context) {
168
  // Example of what might be done with this alter hook.
169
  if ($component->objName == 'vevent') {
170
    // Do something for vevents...
171
  }
172
  elseif ($component->objName == 'valarm') {
173
    // Do something different for valarms...
174
  }
175
}
176

    
177
/**
178
 * Alter the parsed data for an event imported from an iCal feed.
179
 *
180
 * @param array $data
181
 *   An associative array of field data that represents an imported event.
182
 * @param array $context
183
 *   An associative array of context, with the following keys and values:
184
 *   - 'calendar': The iCalcreator vcalendar parent object of this component.
185
 *   - 'source': FeedsSource object for this Feed.
186
 *   - 'fetcher_result': The FeedsFetcherResult object for this Feed.
187
 */
188
function hook_date_ical_import_post_parse_alter(&$data, $context) {
189
  // Example of what might be done with this alter hook.
190
  if (!empty($context['calendar']->xprop['X-WR-CALNAME']['value'])) {
191
    // Do something with the calendar name....
192
  }
193
}
194

    
195
/**
196
 * Alter the timezone string from an imported iCal Feed.
197
 *
198
 * This is useful for when an iCal feed you're trying to import uses deprecated
199
 * timezone names, like "Eastern Standard Time" rather than "America/New_York",
200
 * or has date values with missing timezone information.
201
 *
202
 * @param string $tzid
203
 *   The timezone id sting to be altered (e.g. "America/Los_Angeles").
204
 *   If this value is NULL, not timezone id was set in the feed.
205
 * @param array $context
206
 *   An associative array of context, with the following keys and values:
207
 *   - 'property_key': The name of the property (e.g. DTSTART). Can be NULL.
208
 *   - 'calendar_component': The iCalcreator object (e.g VEVENT). Can be NULL.
209
 *   - 'calendar': The iCalcreater vcalendar object created from the feed.
210
 *   - 'feeds_source': A FeedsSource object with this feed's metadata.
211
 *   - 'feeds_detcher_result': The FeedsFeatcherResult for this import.
212
 *
213
 *   If property_key and calendar_component are NULL, this is the X-WR-TIMEZONE
214
 *   string for the entire feed.
215
 */
216
function hook_date_ical_import_timezone_alter(&$tzid, $context) {
217
  // Example of what might be done with this alter hook:
218
  if ($tzid == 'Eastern Standard Time') {
219
    // "Eastern Standard Time" is a deprecated tzid, which PHP doesn't accept.
220
    // However, it's equivalent to "America/New_York", which PHP is fine with.
221
    $tzid = 'America/New_York';
222
  }
223
}