root / drupal7 / sites / all / modules / date_ical / date_ical.api.php @ ebcc4118
1 | 85ad3d82 | Assos Assos | <?php
|
---|---|---|---|
2 | /**
|
||
3 | 8a7e43dd | Florent Torregrosa | * @file
|
4 | * Documentation for the hooks provided by Date iCal.
|
||
5 | 85ad3d82 | Assos Assos | */
|
6 | |||
7 | 8a7e43dd | Florent Torregrosa | /******************************************************************************
|
8 | * ALTER HOOKS FOR EXPORTED ICAL FEEDS
|
||
9 | *****************************************************************************/
|
||
10 | 85ad3d82 | Assos Assos | |
11 | /**
|
||
12 | 8a7e43dd | Florent Torregrosa | * 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 | 204e4d33 | Assos Assos | * <p>, <h*>, and <div> tags are changed to newlines by the plaintext converter.
|
19 | 85ad3d82 | Assos Assos | *
|
20 | 8a7e43dd | Florent Torregrosa | * @param array $text_fields
|
21 | 85ad3d82 | Assos Assos | * 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 | 8a7e43dd | Florent Torregrosa | * @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 | 85ad3d82 | Assos Assos | * - 'language': The language code that indicates which translation of field
|
35 | * data should be used.
|
||
36 | 8a7e43dd | Florent Torregrosa | *
|
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 | 85ad3d82 | Assos Assos | */
|
44 | 8a7e43dd | Florent Torregrosa | function hook_date_ical_export_html_alter(&$text_fields, $view, $context) { |
45 | 85ad3d82 | Assos Assos | |
46 | } |
||
47 | |||
48 | /**
|
||
49 | 8a7e43dd | Florent Torregrosa | * Modify an event's raw data.
|
50 | 85ad3d82 | Assos Assos | *
|
51 | 8a7e43dd | Florent Torregrosa | * This hook is invoked after Date iCal has gathered all the data it will use
|
52 | * to build an event object.
|
||
53 | 85ad3d82 | Assos Assos | *
|
54 | 8a7e43dd | Florent Torregrosa | * @param array $event
|
55 | * A reference to an associative array containing the event's raw data.
|
||
56 | * @param object $view
|
||
57 | 85ad3d82 | Assos Assos | * The view object that is being executed to render the iCal feed.
|
58 | 8a7e43dd | Florent Torregrosa | * @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 | 85ad3d82 | Assos Assos | * - 'entity': The fully loaded entity being rendered.
|
65 | * - 'language': The language code that indicates which translation of field
|
||
66 | * data should be used.
|
||
67 | 8a7e43dd | Florent Torregrosa | *
|
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 | 85ad3d82 | Assos Assos | */
|
75 | 8a7e43dd | Florent Torregrosa | 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 | 85ad3d82 | Assos Assos | } |
82 | } |
||
83 | 204e4d33 | Assos Assos | |
84 | 8a7e43dd | Florent Torregrosa | // 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 | 85ad3d82 | Assos Assos | } |
88 | |||
89 | /**
|
||
90 | * Alter an iCal representation of an event.
|
||
91 | *
|
||
92 | 8a7e43dd | Florent Torregrosa | * 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 | 85ad3d82 | Assos Assos | *
|
96 | 8a7e43dd | Florent Torregrosa | * @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 | 85ad3d82 | Assos Assos | * The array representation of the event that's been rendered to the $vevent.
|
102 | */
|
||
103 | 8a7e43dd | Florent Torregrosa | function hook_date_ical_export_vevent_alter(&$vevent, $view, $event_array) { |
104 | 85ad3d82 | Assos Assos | |
105 | } |
||
106 | |||
107 | /**
|
||
108 | 8a7e43dd | Florent Torregrosa | * 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 | 85ad3d82 | Assos Assos | */
|
118 | 8a7e43dd | Florent Torregrosa | function hook_date_ical_export_vcalendar_alter(&$vcalendar, $view) { |
119 | 85ad3d82 | Assos Assos | |
120 | } |
||
121 | |||
122 | /**
|
||
123 | 8a7e43dd | Florent Torregrosa | * Alter the final rendered text of an iCal feed before it gets exported.
|
124 | 85ad3d82 | Assos Assos | *
|
125 | 8a7e43dd | Florent Torregrosa | * 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 | 85ad3d82 | Assos Assos | */
|
133 | 8a7e43dd | Florent Torregrosa | function hook_date_ical_export_post_render_alter(&$rendered_calendar, $view) { |
134 | 85ad3d82 | Assos Assos | |
135 | } |
||
136 | |||
137 | 8a7e43dd | Florent Torregrosa | /******************************************************************************
|
138 | * ALTER HOOKS FOR IMPORTED ICAL FEEDS
|
||
139 | *****************************************************************************/
|
||
140 | |||
141 | 85ad3d82 | Assos Assos | /**
|
142 | 55670b15 | Assos Assos | * Alter the vcalendar object imported from an iCal feed.
|
143 | 85ad3d82 | Assos Assos | *
|
144 | 8a7e43dd | Florent Torregrosa | * @param object $calendar
|
145 | * An instance of the iCalcreator library's vcalendar class.
|
||
146 | * @param array $context
|
||
147 | 85ad3d82 | Assos Assos | * An associative array of context, with the following keys and values:
|
148 | 8a7e43dd | Florent Torregrosa | * - 'source' FeedsSource object for this Feed.
|
149 | * - 'fetcher_result': The FeedsFetcherResult object for this Feed.
|
||
150 | 85ad3d82 | Assos Assos | */
|
151 | 8a7e43dd | Florent Torregrosa | function hook_date_ical_import_vcalendar_alter(&$calendar, $context) { |
152 | |||
153 | 85ad3d82 | Assos Assos | } |
154 | |||
155 | /**
|
||
156 | 55670b15 | Assos Assos | * Alter a calendar component imported from an iCal feed.
|
157 | 85ad3d82 | Assos Assos | *
|
158 | 8a7e43dd | Florent Torregrosa | * @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 | 85ad3d82 | Assos Assos | * An associative array of context, with the following keys and values:
|
163 | 8a7e43dd | Florent Torregrosa | * - '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 | 85ad3d82 | Assos Assos | */
|
167 | 8a7e43dd | Florent Torregrosa | 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 | 85ad3d82 | Assos Assos | } |
172 | 8a7e43dd | Florent Torregrosa | elseif ($component->objName == 'valarm') { |
173 | // Do something different for valarms...
|
||
174 | 85ad3d82 | Assos Assos | } |
175 | } |
||
176 | |||
177 | 55670b15 | Assos Assos | /**
|
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 | 85ad3d82 | Assos Assos | /**
|
196 | 8a7e43dd | Florent Torregrosa | * Alter the timezone string from an imported iCal Feed.
|
197 | 85ad3d82 | Assos Assos | *
|
198 | * This is useful for when an iCal feed you're trying to import uses deprecated
|
||
199 | 8a7e43dd | Florent Torregrosa | * timezone names, like "Eastern Standard Time" rather than "America/New_York",
|
200 | * or has date values with missing timezone information.
|
||
201 | 85ad3d82 | Assos Assos | *
|
202 | 8a7e43dd | Florent Torregrosa | * @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 | 85ad3d82 | Assos Assos | * An associative array of context, with the following keys and values:
|
207 | 8a7e43dd | Florent Torregrosa | * - '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 | 85ad3d82 | Assos Assos | */
|
216 | 8a7e43dd | Florent Torregrosa | function hook_date_ical_import_timezone_alter(&$tzid, $context) { |
217 | 85ad3d82 | Assos Assos | // Example of what might be done with this alter hook:
|
218 | 8a7e43dd | Florent Torregrosa | 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 | 85ad3d82 | Assos Assos | } |
223 | } |
||
224 | ca0757b9 | Assos Assos | |
225 | /**
|
||
226 | * Add an additional custom source to be mapped by a feed.
|
||
227 | *
|
||
228 | * This is useful when you need to map fields from an iCal feed which
|
||
229 | * the Date iCal module does not currently support.
|
||
230 | *
|
||
231 | * @param array $sources
|
||
232 | * An associative array containing the source's properties, as follows:
|
||
233 | * name: The name that will appear in the feed importer Mapping page.
|
||
234 | * description: The description of this field shown in the Mapping page.
|
||
235 | * date_ical_parse_handler: The function in the ParserVcalendar class
|
||
236 | * which should be used to parse this iCal property into a Drupal field.
|
||
237 | c7b88c87 | Assos Assos | *
|
238 | * Available date_ical_parse_handlers are:
|
||
239 | * parseTextProperty
|
||
240 | * parseDateTimeProperty
|
||
241 | * parseRepeatProperty
|
||
242 | * parseMultivalueProperty
|
||
243 | * parsePropertyParameter
|
||
244 | ca0757b9 | Assos Assos | */
|
245 | function hook_date_ical_mapping_sources_alter(&$sources) { |
||
246 | // Example of what might be done with this alter hook:
|
||
247 | // Add the "ATTENDEE" iCal property to the mapping sources.
|
||
248 | $sources['ATTENDEE'] = array( |
||
249 | 'name' => t('Attendee'), |
||
250 | 'description' => t('The ATTENDEE property.'), |
||
251 | 'date_ical_parse_handler' => 'parseTextProperty', |
||
252 | ); |
||
253 | // Add "ATTENDEE:CN" parameter to the mapping sources.
|
||
254 | $sources['ATTENDEE:CN'] = array( |
||
255 | 'name' => t('Attendee: CN'), |
||
256 | 'description' => t("The CN parameter of the ATTENDEE property: the attendee's Common Name."), |
||
257 | 'date_ical_parse_handler' => 'parsePropertyParameter', |
||
258 | ); |
||
259 | } |