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 |
} |