root / drupal7 / sites / all / modules / feeds / feeds.api.php @ 27370441
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Documentation of Feeds hooks.
|
6 |
*/
|
7 |
|
8 |
/**
|
9 |
* Feeds offers a CTools based plugin API. Fetchers, parsers and processors are
|
10 |
* declared to Feeds as plugins.
|
11 |
*
|
12 |
* @see feeds_feeds_plugins()
|
13 |
* @see FeedsFetcher
|
14 |
* @see FeedsParser
|
15 |
* @see FeedsProcessor
|
16 |
*
|
17 |
* @defgroup pluginapi Plugin API
|
18 |
* @{
|
19 |
*/
|
20 |
|
21 |
/**
|
22 |
* Example of a CTools plugin hook that needs to be implemented to make
|
23 |
* hook_feeds_plugins() discoverable by CTools and Feeds. The hook specifies
|
24 |
* that the hook_feeds_plugins() returns Feeds Plugin API version 1 style
|
25 |
* plugins.
|
26 |
*/
|
27 |
function hook_ctools_plugin_api($owner, $api) { |
28 |
if ($owner == 'feeds' && $api == 'plugins') { |
29 |
return array('version' => 1); |
30 |
} |
31 |
} |
32 |
|
33 |
/**
|
34 |
* A hook_feeds_plugins() declares available Fetcher, Parser or Processor
|
35 |
* plugins to Feeds. For an example look at feeds_feeds_plugin(). For exposing
|
36 |
* this hook hook_ctools_plugin_api() MUST be implemented, too.
|
37 |
*
|
38 |
* @see feeds_feeds_plugin()
|
39 |
*/
|
40 |
function hook_feeds_plugins() { |
41 |
$info = array(); |
42 |
$info['MyFetcher'] = array( |
43 |
'name' => 'My Fetcher', |
44 |
'description' => 'Fetches my stuff.', |
45 |
'help' => 'More verbose description here. Will be displayed on fetcher selection menu.', |
46 |
'handler' => array( |
47 |
'parent' => 'FeedsFetcher', |
48 |
'class' => 'MyFetcher', |
49 |
'file' => 'MyFetcher.inc', |
50 |
'path' => drupal_get_path('module', 'my_module'), // Feeds will look for MyFetcher.inc in the my_module directory. |
51 |
), |
52 |
); |
53 |
$info['MyParser'] = array( |
54 |
'name' => 'ODK parser', |
55 |
'description' => 'Parse my stuff.', |
56 |
'help' => 'More verbose description here. Will be displayed on parser selection menu.', |
57 |
'handler' => array( |
58 |
'parent' => 'FeedsParser', // Being directly or indirectly an extension of FeedsParser makes a plugin a parser plugin. |
59 |
'class' => 'MyParser', |
60 |
'file' => 'MyParser.inc', |
61 |
'path' => drupal_get_path('module', 'my_module'), |
62 |
), |
63 |
); |
64 |
$info['MyProcessor'] = array( |
65 |
'name' => 'ODK parser', |
66 |
'description' => 'Process my stuff.', |
67 |
'help' => 'More verbose description here. Will be displayed on processor selection menu.', |
68 |
'handler' => array( |
69 |
'parent' => 'FeedsProcessor', |
70 |
'class' => 'MyProcessor', |
71 |
'file' => 'MyProcessor.inc', |
72 |
'path' => drupal_get_path('module', 'my_module'), |
73 |
), |
74 |
); |
75 |
return $info; |
76 |
} |
77 |
|
78 |
/**
|
79 |
* @}
|
80 |
*/
|
81 |
|
82 |
/**
|
83 |
* @defgroup import Import and clear hooks
|
84 |
* @{
|
85 |
*/
|
86 |
|
87 |
/**
|
88 |
* Invoked after a feed source has been parsed, before it will be processed.
|
89 |
*
|
90 |
* @param FeedsSource $source
|
91 |
* FeedsSource object that describes the source that has been imported.
|
92 |
* @param FeedsParserResult $result
|
93 |
* FeedsParserResult object that has been parsed from the source.
|
94 |
*/
|
95 |
function hook_feeds_after_parse(FeedsSource $source, FeedsParserResult $result) { |
96 |
// For example, set title of imported content:
|
97 |
$result->title = 'Import number ' . my_module_import_id(); |
98 |
} |
99 |
|
100 |
/**
|
101 |
* Invoked before a feed source import starts.
|
102 |
*
|
103 |
* @param FeedsSource $source
|
104 |
* FeedsSource object that describes the source that is going to be imported.
|
105 |
*/
|
106 |
function hook_feeds_before_import(FeedsSource $source) { |
107 |
// See feeds_rules module's implementation for an example.
|
108 |
} |
109 |
|
110 |
/**
|
111 |
* Invoked before a feed item is updated/created/replaced.
|
112 |
*
|
113 |
* This is called every time a feed item is processed no matter if the item gets
|
114 |
* updated or not.
|
115 |
*
|
116 |
* @param FeedsSource $source
|
117 |
* The source for the current feed.
|
118 |
* @param array $item
|
119 |
* All the current item from the feed.
|
120 |
* @param int|null $entity_id
|
121 |
* The id of the current item which is going to be updated. If this is a new
|
122 |
* item, then NULL is passed.
|
123 |
*/
|
124 |
function hook_feeds_before_update(FeedsSource $source, $item, $entity_id) { |
125 |
if ($entity_id) { |
126 |
$processor = $source->importer->processor; |
127 |
db_update('foo_bar')
|
128 |
->fields(array('entity_type' => $processor->entityType(), 'entity_id' => $entity_id, 'last_seen' => REQUEST_TIME)) |
129 |
->condition('entity_type', $processor->entityType()) |
130 |
->condition('entity_id', $entity_id) |
131 |
->execute(); |
132 |
} |
133 |
} |
134 |
|
135 |
/**
|
136 |
* Invoked before a feed item is saved.
|
137 |
*
|
138 |
* @param FeedsSource $source
|
139 |
* FeedsSource object that describes the source that is being imported.
|
140 |
* @param $entity
|
141 |
* The entity object.
|
142 |
* @param array $item
|
143 |
* The parser result for this entity.
|
144 |
* @param int|null $entity_id
|
145 |
* The id of the current item which is going to be updated. If this is a new
|
146 |
* item, then NULL is passed.
|
147 |
*/
|
148 |
function hook_feeds_presave(FeedsSource $source, $entity, $item, $entity_id) { |
149 |
if ($entity->feeds_item->entity_type == 'node') { |
150 |
// Skip saving this entity.
|
151 |
$entity->feeds_item->skip = TRUE; |
152 |
} |
153 |
} |
154 |
|
155 |
/**
|
156 |
* Invoked after a feed item has been saved.
|
157 |
*
|
158 |
* @param FeedsSource $source
|
159 |
* FeedsSource object that describes the source that is being imported.
|
160 |
* @param $entity
|
161 |
* The entity object that has just been saved.
|
162 |
* @param array $item
|
163 |
* The parser result for this entity.
|
164 |
* @param int|null $entity_id
|
165 |
* The id of the current item which is going to be updated. If this is a new
|
166 |
* item, then NULL is passed.
|
167 |
*/
|
168 |
function hook_feeds_after_save(FeedsSource $source, $entity, $item, $entity_id) { |
169 |
// Use $entity->nid of the saved node.
|
170 |
|
171 |
// Although the $entity object is passed by reference, any changes made in
|
172 |
// this function will be ignored by the FeedsProcessor.
|
173 |
$config = $source->importer->getConfig(); |
174 |
|
175 |
if ($config['processor']['config']['purge_unseen_items'] && isset($entity->feeds_item)) { |
176 |
$feeds_item = $entity->feeds_item; |
177 |
$feeds_item->batch_id = feeds_delete_get_current_batch($feeds_item->feed_nid); |
178 |
|
179 |
drupal_write_record('feeds_delete_item', $feeds_item); |
180 |
} |
181 |
} |
182 |
|
183 |
/**
|
184 |
* Invoked after a feed source has been imported.
|
185 |
*
|
186 |
* @param FeedsSource $source
|
187 |
* FeedsSource object that describes the source that has been imported.
|
188 |
*/
|
189 |
function hook_feeds_after_import(FeedsSource $source) { |
190 |
// See geotaxonomy module's implementation for an example.
|
191 |
|
192 |
// We can also check for an exception in this hook. The exception should not
|
193 |
// be thrown here, Feeds will handle it.
|
194 |
if (isset($source->exception)) { |
195 |
watchdog('mymodule', 'An exception occurred during importing!', array(), WATCHDOG_ERROR); |
196 |
mymodule_panic_reaction($source);
|
197 |
} |
198 |
} |
199 |
|
200 |
/**
|
201 |
* Invoked after a feed source has been cleared of its items.
|
202 |
*
|
203 |
* @param FeedsSource $source
|
204 |
* FeedsSource object that describes the source that has been cleared.
|
205 |
*/
|
206 |
function hook_feeds_after_clear(FeedsSource $source) { |
207 |
} |
208 |
|
209 |
/**
|
210 |
* @}
|
211 |
*/
|
212 |
|
213 |
/**
|
214 |
* @defgroup mappingapi Mapping API
|
215 |
* @{
|
216 |
*/
|
217 |
|
218 |
/**
|
219 |
* Alter mapping sources.
|
220 |
*
|
221 |
* Use this hook to add additional mapping sources for any parser. Allows for
|
222 |
* registering a callback to be invoked at mapping time.
|
223 |
*
|
224 |
* @see my_source_get_source().
|
225 |
* @see locale_feeds_parser_sources_alter().
|
226 |
*/
|
227 |
function hook_feeds_parser_sources_alter(&$sources, $content_type) { |
228 |
$sources['my_source'] = array( |
229 |
'name' => t('Images in description element'), |
230 |
'description' => t('Images occuring in the description element of a feed item.'), |
231 |
'callback' => 'my_source_get_source', |
232 |
); |
233 |
} |
234 |
|
235 |
/**
|
236 |
* Example callback specified in hook_feeds_parser_sources_alter().
|
237 |
*
|
238 |
* To be invoked on mapping time.
|
239 |
*
|
240 |
* @param $source
|
241 |
* The FeedsSource object being imported.
|
242 |
* @param $result
|
243 |
* The FeedsParserResult object being mapped from.
|
244 |
* @param $key
|
245 |
* The key specified in the $sources array in
|
246 |
* hook_feeds_parser_sources_alter().
|
247 |
*
|
248 |
* @return
|
249 |
* The value to be extracted from the source.
|
250 |
*
|
251 |
* @see hook_feeds_parser_sources_alter()
|
252 |
* @see locale_feeds_get_source()
|
253 |
*/
|
254 |
function my_source_get_source(FeedsSource $source, FeedsParserResult $result, $key) { |
255 |
$item = $result->currentItem(); |
256 |
return my_source_parse_images($item['description']); |
257 |
} |
258 |
|
259 |
/**
|
260 |
* Adds mapping targets for processors.
|
261 |
*
|
262 |
* This hook allows additional target options to be added to the processors
|
263 |
* mapping form.
|
264 |
*
|
265 |
* If the key in $targets[] does not correspond to the actual key on the node
|
266 |
* object ($node->key), real_target MUST be specified. See mappers/link.inc
|
267 |
*
|
268 |
* For an example implementation, see mappers/text.inc
|
269 |
*
|
270 |
* @param string $entity_type
|
271 |
* The entity type of the target, for instance a 'node' entity.
|
272 |
* @param string $bundle
|
273 |
* The entity bundle to return targets for.
|
274 |
*
|
275 |
* @return array
|
276 |
* Array containing the targets to be offered to the user. This function must
|
277 |
* return an array, even an empty one.
|
278 |
*/
|
279 |
function hook_feeds_processor_targets($entity_type, $bundle) { |
280 |
$targets = array(); |
281 |
|
282 |
if ($entity_type == 'node') { |
283 |
$targets['my_node_field'] = array( |
284 |
'name' => t('My custom node field'), |
285 |
'description' => t('Description of what my custom node field does.'), |
286 |
'callback' => 'my_module_set_target', |
287 |
|
288 |
// Specify both summary_callback and form_callback to add a per mapping
|
289 |
// configuration form.
|
290 |
'summary_callbacks' => array('my_module_summary_callback'), |
291 |
'form_callbacks' => array('my_module_form_callback'), |
292 |
); |
293 |
$targets['my_node_field2'] = array( |
294 |
'name' => t('My Second custom node field'), |
295 |
'description' => t('Description of what my second custom node field does.'), |
296 |
'callback' => 'my_module_set_target2', |
297 |
'real_target' => 'my_node_field_two', // Specify real target field on node. |
298 |
); |
299 |
$targets['my_node_field3'] = array( |
300 |
'name' => t('My third custom node field'), |
301 |
'description' => t('Description of what my third custom node field does.'), |
302 |
'callback' => 'my_module_set_target3', |
303 |
|
304 |
// Set optional_unique to TRUE and specify unique_callbacks to allow the
|
305 |
// target to be unique. Existing entities can be updated based on unique
|
306 |
// targets.
|
307 |
'optional_unique' => TRUE, |
308 |
'unique_callbacks' => array('my_module_mapper_unique'), |
309 |
|
310 |
// Preprocess callbacks are called before the actual callback allowing you
|
311 |
// to prepare values on the entity or mapping array.
|
312 |
'preprocess_callbacks' => array('my_module_preprocess_callback'), |
313 |
); |
314 |
} |
315 |
|
316 |
return $targets; |
317 |
} |
318 |
|
319 |
/**
|
320 |
* Alters the target array.
|
321 |
*
|
322 |
* This hook allows modifying the target array.
|
323 |
*
|
324 |
* @param array &$targets
|
325 |
* Array containing the targets to be offered to the user. Add to this array
|
326 |
* to expose additional options.
|
327 |
* @param string $entity_type
|
328 |
* The entity type of the target, for instance a 'node' entity.
|
329 |
* @param string $bundle
|
330 |
* The entity bundle to return targets for.
|
331 |
*
|
332 |
* @see hook_feeds_processor_targets()
|
333 |
*/
|
334 |
function hook_feeds_processor_targets_alter(array &$targets, $entity_type, $bundle) { |
335 |
if ($entity_type == 'node' && $bundle == 'article') { |
336 |
if (isset($targets['nid'])) { |
337 |
$targets['nid']['unique_callbacks'][] = 'my_module_mapper_unique'; |
338 |
$targets['nid']['optional_unique'] = TRUE; |
339 |
} |
340 |
} |
341 |
} |
342 |
|
343 |
/**
|
344 |
* Example callback specified in hook_feeds_processor_targets().
|
345 |
*
|
346 |
* @param FeedsSource $source
|
347 |
* Field mapper source settings.
|
348 |
* @param object $entity
|
349 |
* An entity object, for instance a node object.
|
350 |
* @param string $target
|
351 |
* A string identifying the target on the node.
|
352 |
* @param array $values
|
353 |
* The value to populate the target with.
|
354 |
* @param array $mapping
|
355 |
* Associative array of the mapping settings from the per mapping
|
356 |
* configuration form.
|
357 |
*/
|
358 |
function my_module_set_target(FeedsSource $source, $entity, $target, array $values, array $mapping) { |
359 |
$entity->{$target}[$entity->language][0]['value'] = reset($values); |
360 |
if (isset($source->importer->processor->config['input_format'])) { |
361 |
$entity->{$target}[$entity->language][0]['format'] = $source->importer->processor->config['input_format']; |
362 |
} |
363 |
} |
364 |
|
365 |
/**
|
366 |
* Example of the summary_callback specified in hook_feeds_processor_targets().
|
367 |
*
|
368 |
* @param array $mapping
|
369 |
* Associative array of the mapping settings.
|
370 |
* @param string $target
|
371 |
* Array of target settings, as defined by the processor or
|
372 |
* hook_feeds_processor_targets_alter().
|
373 |
* @param array $form
|
374 |
* The whole mapping form.
|
375 |
* @param array $form_state
|
376 |
* The form state of the mapping form.
|
377 |
*
|
378 |
* @return string
|
379 |
* Returns, as a string that may contain HTML, the summary to display while
|
380 |
* the full form isn't visible.
|
381 |
* If the return value is empty, no summary and no option to view the form
|
382 |
* will be displayed.
|
383 |
*/
|
384 |
function my_module_summary_callback(array $mapping, $target, array $form, array $form_state) { |
385 |
if (empty($mapping['my_setting'])) { |
386 |
return t('My setting <strong>not</strong> active'); |
387 |
} |
388 |
else {
|
389 |
return t('My setting <strong>active</strong>'); |
390 |
} |
391 |
} |
392 |
|
393 |
/**
|
394 |
* Example of the form_callback specified in hook_feeds_processor_targets().
|
395 |
*
|
396 |
* The arguments are the same that my_module_summary_callback() gets.
|
397 |
*
|
398 |
* @return array
|
399 |
* The per mapping configuration form. Once the form is saved, $mapping will
|
400 |
* be populated with the form values.
|
401 |
*
|
402 |
* @see my_module_summary_callback()
|
403 |
*/
|
404 |
function my_module_form_callback(array $mapping, $target, array $form, array $form_state) { |
405 |
return array( |
406 |
'my_setting' => array( |
407 |
'#type' => 'checkbox', |
408 |
'#title' => t('My setting checkbox'), |
409 |
'#default_value' => !empty($mapping['my_setting']), |
410 |
), |
411 |
); |
412 |
} |
413 |
|
414 |
/**
|
415 |
* Example of the unique_callbacks specified in hook_feeds_processor_targets().
|
416 |
*
|
417 |
* @param FeedsSource $source
|
418 |
* The Feed source.
|
419 |
* @param string $entity_type
|
420 |
* Entity type for the entity to be processed.
|
421 |
* @param string $bundle
|
422 |
* Bundle name for the entity to be processed.
|
423 |
* @param string $target
|
424 |
* A string identifying the unique target on the entity.
|
425 |
* @param array $values
|
426 |
* The unique values to be checked.
|
427 |
*
|
428 |
* @return int|null
|
429 |
* The existing entity id, or NULL if no existing entity is found.
|
430 |
*
|
431 |
* @see hook_feeds_processor_targets()
|
432 |
* @see FeedsProcessor::existingEntityId()
|
433 |
*/
|
434 |
function my_module_mapper_unique(FeedsSource $source, $entity_type, $bundle, $target, array $values) { |
435 |
list($field_name, $column) = explode(':', $target . ':value'); |
436 |
// Example for if the target is a field.
|
437 |
$query = new EntityFieldQuery(); |
438 |
$result = $query |
439 |
->entityCondition('entity_type', $entity_type) |
440 |
->entityCondition('bundle', $bundle) |
441 |
->fieldCondition($field_name, $column, $values) |
442 |
->execute(); |
443 |
|
444 |
if (!empty($result[$entity_type])) { |
445 |
return key($result[$entity_type]); |
446 |
} |
447 |
} |
448 |
|
449 |
/**
|
450 |
* Example of the preprocess_callbacks specified in hook_feeds_processor_targets().
|
451 |
*
|
452 |
* @param FeedsSource $source
|
453 |
* The Feed source.
|
454 |
* @param object $entity
|
455 |
* The entity being processed.
|
456 |
* @param array $target
|
457 |
* The full target definition.
|
458 |
* @param array &$mapping
|
459 |
* The mapping configuration.
|
460 |
*
|
461 |
* @see hook_feeds_processor_targets()
|
462 |
*/
|
463 |
function my_module_preprocess_callback(FeedsSource $source, $entity, array $target, array &$mapping) { |
464 |
// Add in default values.
|
465 |
$mapping += array('setting_value' => TRUE); |
466 |
} |
467 |
|
468 |
/**
|
469 |
* @}
|
470 |
*/
|