date_ical.api.php 9.91 KB
Newer Older
Robert Rollins's avatar
Robert Rollins committed
1
<?php
2
/**
3 4
 * @file
 * Documentation for the hooks provided by Date iCal.
5
 */
6

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

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

}

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

84 85 86
  // Example: Retrieving information from additional fields in the View (using
  // the Fields plugin).
  $event['comment'] = $view->style_plugin->get_field($context['row_index'], 'field_comment');
Robert Rollins's avatar
Robert Rollins committed
87 88 89 90 91
}

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

}

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

}

122
/**
123
 * Alter the final rendered text of an iCal feed before it gets exported.
124
 *
125 126 127 128 129 130
 * This is a last resort hook, allowing you to alter the output of the feed
 * in case nothing else works.
 *
 * @param string $rendered_calendar
 *   A reference to the string containing the rendered the iCal feed.
 * @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 139 140
/******************************************************************************
 * ALTER HOOKS FOR IMPORTED ICAL FEEDS
 *****************************************************************************/

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

Robert Rollins's avatar
Robert Rollins committed
153 154 155
}

/**
156
 * Alter a calendar component imported from an iCal feed.
Robert Rollins's avatar
Robert Rollins committed
157
 *
158 159 160 161
 * @param object $component
 *   This will usually be an iCalcreator vevent object, but Date iCal also
 *   experimentally supports vtodo, vjournal, vfreebusy, and valarm.
 * @param array $context
Robert Rollins's avatar
Robert Rollins committed
162
 *   An associative array of context, with the following keys and values:
163 164 165
 *   - 'calendar': The iCalcreator vcalendar parent object of this component.
 *   - 'source': FeedsSource object for this Feed.
 *   - 'fetcher_result': The FeedsFetcherResult object for this Feed.
Robert Rollins's avatar
Robert Rollins committed
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...
Robert Rollins's avatar
Robert Rollins committed
171
  }
172 173
  elseif ($component->objName == 'valarm') {
    // Do something different for valarms...
Robert Rollins's avatar
Robert Rollins committed
174 175
  }
}
176

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

Robert Rollins's avatar
Robert Rollins committed
195
/**
196
 * Alter the timezone string from an imported iCal Feed.
Robert Rollins's avatar
Robert Rollins committed
197
 *
198
 * This is useful for when an iCal feed you're trying to import uses deprecated
199 200
 * timezone names, like "Eastern Standard Time" rather than "America/New_York",
 * or has date values with missing timezone information.
201
 *
202 203
 * @param string $tzid
 *   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 208 209 210 211 212 213 214
 *   - 'property_key': The name of the property (e.g. DTSTART). Can be NULL.
 *   - 'calendar_component': The iCalcreator object (e.g VEVENT). Can be NULL.
 *   - 'calendar': The iCalcreater vcalendar object created from the feed.
 *   - 'feeds_source': A FeedsSource object with this feed's metadata.
 *   - 'feeds_detcher_result': The FeedsFeatcherResult for this import.
 *
 *   If property_key and calendar_component are NULL, this is the X-WR-TIMEZONE
 *   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 219 220 221
  if ($tzid == 'Eastern Standard Time') {
    // "Eastern Standard Time" is a deprecated tzid, which PHP doesn't accept.
    // However, it's equivalent to "America/New_York", which PHP is fine with.
    $tzid = 'America/New_York';
222 223
  }
}
224 225 226 227 228 229 230 231 232 233 234 235 236

/**
 * Add an additional custom source to be mapped by a feed.
 *
 * This is useful when you need to map fields from an iCal feed which
 * the Date iCal module does not currently support.
 *
 * @param array $sources
 *   An associative array containing the source's properties, as follows:
 *     name: The name that will appear in the feed importer Mapping page.
 *     description: The description of this field shown in the Mapping page.
 *     date_ical_parse_handler: The function in the ParserVcalendar class
 *       which should be used to parse this iCal property into a Drupal field.
237 238 239 240 241 242 243
 *
 * Available date_ical_parse_handlers are:
 *   parseTextProperty
 *   parseDateTimeProperty
 *   parseRepeatProperty
 *   parseMultivalueProperty
 *   parsePropertyParameter
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259
 */
function hook_date_ical_mapping_sources_alter(&$sources) {
  // Example of what might be done with this alter hook:
  // Add the "ATTENDEE" iCal property to the mapping sources.
  $sources['ATTENDEE'] = array(
    'name' => t('Attendee'),
    'description' => t('The ATTENDEE property.'),
    'date_ical_parse_handler' => 'parseTextProperty',
  );
  // Add "ATTENDEE:CN" parameter to the mapping sources.
  $sources['ATTENDEE:CN'] = array(
    'name' => t('Attendee: CN'),
    'description' => t("The CN parameter of the ATTENDEE property: the attendee's Common Name."),
    'date_ical_parse_handler' => 'parsePropertyParameter',
  );
}