Projet

Général

Profil

Révision ed9a13f1

Ajouté par Assos Assos il y a plus de 3 ans

Weekly update of contrib modules

Voir les différences:

drupal7/sites/all/modules/feeds/feeds.api.php
6 6
 */
7 7

  
8 8
/**
9
 * Feeds offers a CTools based plugin API. Fetchers, parsers and processors are
10
 * declared to Feeds as plugins.
9
 * @defgroup pluginapi Plugin API
10
 * @{
11
 * Feeds offers a CTools based plugin API.
12
 *
13
 * Fetchers, parsers and processors are declared to Feeds as plugins.
11 14
 *
12 15
 * @see feeds_feeds_plugins()
13 16
 * @see FeedsFetcher
14 17
 * @see FeedsParser
15 18
 * @see FeedsProcessor
16
 *
17
 * @defgroup pluginapi Plugin API
18
 * @{
19 19
 */
20 20

  
21 21
/**
22
 * Example of a CTools plugin hook that needs to be implemented to make
22
 * CTools plugin hook example.
23
 *
24
 * This example of a CTools plugin hook needs to be implemented to make
23 25
 * hook_feeds_plugins() discoverable by CTools and Feeds. The hook specifies
24 26
 * that the hook_feeds_plugins() returns Feeds Plugin API version 1 style
25 27
 * plugins.
......
31 33
}
32 34

  
33 35
/**
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.
36
 * Declare Feeds plugins.
37
 *
38
 * Implement this hook to declare Fetcher, Parser or Processor plugins for
39
 * Feeds. For a working example implementation, see feeds_feeds_plugin().
40
 * In order for this hook to be invoked, you MUST implement
41
 * hook_ctools_plugin_api() as well.
37 42
 *
38 43
 * @see feeds_feeds_plugin()
39 44
 */
......
47 52
      'parent' => 'FeedsFetcher',
48 53
      'class' => 'MyFetcher',
49 54
      'file' => 'MyFetcher.inc',
50
      'path' => drupal_get_path('module', 'my_module'), // Feeds will look for MyFetcher.inc in the my_module directory.
55
      // Feeds will look for MyFetcher.inc in the my_module directory.
56
      'path' => drupal_get_path('module', 'my_module'),
51 57
    ),
52 58
  );
53 59
  $info['MyParser'] = array(
......
55 61
    'description' => 'Parse my stuff.',
56 62
    'help' => 'More verbose description here. Will be displayed on parser selection menu.',
57 63
    'handler' => array(
58
      'parent' => 'FeedsParser', // Being directly or indirectly an extension of FeedsParser makes a plugin a parser plugin.
64
      // Being directly or indirectly an extension of FeedsParser makes a plugin
65
      // a parser plugin.
66
      'parent' => 'FeedsParser',
59 67
      'class' => 'MyParser',
60 68
      'file' => 'MyParser.inc',
61 69
      'path' => drupal_get_path('module', 'my_module'),
......
76 84
}
77 85

  
78 86
/**
79
 * @}
87
 * @} End of "defgroup pluginapi".
80 88
 */
81 89

  
82 90
/**
......
88 96
 * Invoked after a feed source has been parsed, before it will be processed.
89 97
 *
90 98
 * @param FeedsSource $source
91
 *  FeedsSource object that describes the source that has been imported.
99
 *   FeedsSource object that describes the source that has been imported.
92 100
 * @param FeedsParserResult $result
93 101
 *   FeedsParserResult object that has been parsed from the source.
94 102
 */
......
101 109
 * Invoked before a feed source import starts.
102 110
 *
103 111
 * @param FeedsSource $source
104
 *  FeedsSource object that describes the source that is going to be imported.
112
 *   FeedsSource object that describes the source that is going to be imported.
105 113
 */
106 114
function hook_feeds_before_import(FeedsSource $source) {
107 115
  // See feeds_rules module's implementation for an example.
......
114 122
 * updated or not.
115 123
 *
116 124
 * @param FeedsSource $source
117
 *  The source for the current feed.
125
 *   The source for the current feed.
118 126
 * @param array $item
119
 *  All the current item from the feed.
127
 *   All the current item from the feed.
120 128
 * @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.
129
 *   The id of the current item which is going to be updated. If this is a new
130
 *   item, then NULL is passed.
123 131
 */
124 132
function hook_feeds_before_update(FeedsSource $source, $item, $entity_id) {
125 133
  if ($entity_id) {
126 134
    $processor = $source->importer->processor;
127 135
    db_update('foo_bar')
128
      ->fields(array('entity_type' => $processor->entityType(), 'entity_id' => $entity_id, 'last_seen' => REQUEST_TIME))
136
      ->fields(array(
137
        'entity_type' => $processor->entityType(),
138
        'entity_id' => $entity_id,
139
        'last_seen' => REQUEST_TIME,
140
      ))
129 141
      ->condition('entity_type', $processor->entityType())
130 142
      ->condition('entity_id', $entity_id)
131 143
      ->execute();
132 144
  }
133 145
}
134 146

  
147
/**
148
 * Invoked before a feed item is validated.
149
 *
150
 * @param FeedsSource $source
151
 *   FeedsSource object that describes the source that is being imported.
152
 * @param object $entity
153
 *   The entity object.
154
 * @param array $item
155
 *   The parser result for this entity.
156
 * @param int|null $entity_id
157
 *   The id of the current item which is going to be updated. If this is a new
158
 *   item, then NULL is passed.
159
 */
160
function hook_feeds_prevalidate(FeedsSource $source, $entity, $item, $entity_id) {
161
  // Correct a field value to make it pass validation.
162
  if (isset($entity->myfield)) {
163
    foreach ($entity->myfield as $language => &$values) {
164
      // There are only three values allowed. Throw away the rest.
165
      if (count($values) > 3) {
166
        $values = array_slice($values, 0, 3);
167
      }
168
    }
169
  }
170
}
171

  
135 172
/**
136 173
 * Invoked before a feed item is saved.
137 174
 *
138 175
 * @param FeedsSource $source
139 176
 *   FeedsSource object that describes the source that is being imported.
140
 * @param $entity
177
 * @param object $entity
141 178
 *   The entity object.
142 179
 * @param array $item
143 180
 *   The parser result for this entity.
......
156 193
 * Invoked after a feed item has been saved.
157 194
 *
158 195
 * @param FeedsSource $source
159
 *  FeedsSource object that describes the source that is being imported.
160
 * @param $entity
196
 *   FeedsSource object that describes the source that is being imported.
197
 * @param object $entity
161 198
 *   The entity object that has just been saved.
162 199
 * @param array $item
163 200
 *   The parser result for this entity.
164 201
 * @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.
202
 *   The id of the current item which is going to be updated. If this is a new
203
 *   item, then NULL is passed.
167 204
 */
168 205
function hook_feeds_after_save(FeedsSource $source, $entity, $item, $entity_id) {
169
  // Use $entity->nid of the saved node.
170

  
171 206
  // Although the $entity object is passed by reference, any changes made in
172 207
  // this function will be ignored by the FeedsProcessor.
173 208
  $config = $source->importer->getConfig();
......
184 219
 * Invoked after a feed source has been imported.
185 220
 *
186 221
 * @param FeedsSource $source
187
 *  FeedsSource object that describes the source that has been imported.
222
 *   FeedsSource object that describes the source that has been imported.
188 223
 */
189 224
function hook_feeds_after_import(FeedsSource $source) {
190
  // See geotaxonomy module's implementation for an example.
191

  
192 225
  // We can also check for an exception in this hook. The exception should not
193 226
  // be thrown here, Feeds will handle it.
194 227
  if (isset($source->exception)) {
......
201 234
 * Invoked after a feed source has been cleared of its items.
202 235
 *
203 236
 * @param FeedsSource $source
204
 *  FeedsSource object that describes the source that has been cleared.
237
 *   FeedsSource object that describes the source that has been cleared.
205 238
 */
206 239
function hook_feeds_after_clear(FeedsSource $source) {
207 240
}
208 241

  
209 242
/**
210
 * @}
243
 * @} End of "defgroup import".
211 244
 */
212 245

  
213 246
/**
......
221 254
 * Use this hook to add additional mapping sources for any parser. Allows for
222 255
 * registering a callback to be invoked at mapping time.
223 256
 *
224
 * @see my_source_get_source().
225
 * @see locale_feeds_parser_sources_alter().
257
 * @see my_source_get_source()
258
 * @see locale_feeds_parser_sources_alter()
226 259
 */
227 260
function hook_feeds_parser_sources_alter(&$sources, $content_type) {
228 261
  $sources['my_source'] = array(
229 262
    'name' => t('Images in description element'),
230 263
    'description' => t('Images occurring in the description element of a feed item.'),
231
    'callback' => 'my_source_get_source',
264
    'callback' => 'callback_my_source_get_source',
232 265
  );
233 266
}
234 267

  
235 268
/**
236
 * Example callback specified in hook_feeds_parser_sources_alter().
269
 * Returns a value to use as a mapping source.
237 270
 *
238
 * To be invoked on mapping time.
271
 * Callback for hook_feeds_parser_sources_alter().
239 272
 *
240
 * @param $source
273
 * This function is called on mapping time.
274
 *
275
 * @param FeedsSource $source
241 276
 *   The FeedsSource object being imported.
242
 * @param $result
277
 * @param FeedsParserResult $result
243 278
 *   The FeedsParserResult object being mapped from.
244
 * @param $key
279
 * @param string $key
245 280
 *   The key specified in the $sources array in
246 281
 *   hook_feeds_parser_sources_alter().
247 282
 *
248
 * @return
283
 * @return mixed
249 284
 *   The value to be extracted from the source.
250 285
 *
251 286
 * @see hook_feeds_parser_sources_alter()
252 287
 * @see locale_feeds_get_source()
288
 *
289
 * @ingroup callbacks
253 290
 */
254
function my_source_get_source(FeedsSource $source, FeedsParserResult $result, $key) {
291
function callback_my_source_get_source(FeedsSource $source, FeedsParserResult $result, $key) {
255 292
  $item = $result->currentItem();
256 293
  return my_source_parse_images($item['description']);
257 294
}
......
310 347
    $targets['my_node_field'] = array(
311 348
      'name' => t('My custom node field'),
312 349
      'description' => t('Description of what my custom node field does.'),
313
      'callback' => 'my_module_set_target',
350
      'callback' => 'callback_my_module_set_target',
314 351
    );
315 352

  
316 353
    // Example 2: specify "real_target" if the target name is different from
......
335 372
      'description' => t('A field that can be set as an unique target.'),
336 373
      'callback' => 'my_module_set_target3',
337 374
      'optional_unique' => TRUE,
338
      'unique_callbacks' => array('my_module_mapper_unique'),
375
      'unique_callbacks' => array('callback_my_module_mapper_unique'),
339 376
    );
340 377

  
341 378
    // Example 4: use the form and summary callbacks to add additional
......
348 385
      'name' => t('My fourth custom node field'),
349 386
      'description' => t('A field with additional configuration.'),
350 387
      'callback' => 'my_module_set_target4',
351
      'form_callbacks' => array('my_module_form_callback'),
352
      'summary_callbacks' => array('my_module_summary_callback'),
388
      'form_callbacks' => array('callback_my_module_form_callback'),
389
      'summary_callbacks' => array('callback_my_module_summary_callback'),
353 390
    );
354 391

  
355 392
    // Example 5: use preprocess callbacks to set or change mapping options.
......
358 395
      'name' => t('My fifth custom node field'),
359 396
      'description' => t('A field with additional configuration.'),
360 397
      'callback' => 'my_module_set_target5',
361
      'preprocess_callbacks' => array('my_module_preprocess_callback'),
398
      'preprocess_callbacks' => array('callback_my_module_preprocess_callback'),
362 399
    );
363 400

  
364 401
    // Example 6: when you want to remove or rename previously provided targets,
......
402 439
}
403 440

  
404 441
/**
405
 * Example callback specified in hook_feeds_processor_targets().
442
 * Sets a value on a target.
443
 *
444
 * Callback for hook_feeds_processor_targets().
445
 *
446
 * This callback is specified on the 'callback' key of the target definition.
447
 * A target can for example be a field or property on an entity.
406 448
 *
407 449
 * @param FeedsSource $source
408 450
 *   Field mapper source settings.
......
413 455
 * @param array $values
414 456
 *   The value to populate the target with.
415 457
 * @param array $mapping
416
 *  Associative array of the mapping settings from the per mapping
417
 *  configuration form.
458
 *   Associative array of the mapping settings from the per mapping
459
 *   configuration form.
460
 *
461
 * @see hook_feeds_processor_targets()
462
 *
463
 * @ingroup callbacks
418 464
 */
419
function my_module_set_target(FeedsSource $source, $entity, $target, array $values, array $mapping) {
465
function callback_my_module_set_target(FeedsSource $source, $entity, $target, array $values, array $mapping) {
420 466
  $entity->{$target}[$entity->language][0]['value'] = reset($values);
421 467
  if (isset($source->importer->processor->config['input_format'])) {
422 468
    $entity->{$target}[$entity->language][0]['format'] = $source->importer->processor->config['input_format'];
......
424 470
}
425 471

  
426 472
/**
427
 * Example of the form_callback specified in hook_feeds_processor_targets().
473
 * Returns a form for configuring a target.
474
 *
475
 * Callback for hook_feeds_processor_targets().
428 476
 *
429
 * The arguments are the same that my_module_summary_callback() gets.
477
 * This callback is specified on the 'form_callbacks' key of the target
478
 * definition.
479
 * The arguments are the same that callback_my_module_summary_callback() gets.
430 480
 *
431 481
 * @return array
432 482
 *   The per mapping configuration form. Once the form is saved, $mapping will
433 483
 *   be populated with the form values.
434 484
 *
435
 * @see my_module_summary_callback()
485
 * @see hook_feeds_processor_targets()
486
 * @see callback_my_module_summary_callback()
487
 *
488
 * @ingroup callbacks
436 489
 */
437
function my_module_form_callback(array $mapping, $target, array $form, array $form_state) {
490
function callback_my_module_form_callback(array $mapping, $target, array $form, array $form_state) {
438 491
  return array(
439 492
    'my_setting' => array(
440 493
      '#type' => 'checkbox',
......
445 498
}
446 499

  
447 500
/**
448
 * Example of the summary_callback specified in hook_feeds_processor_targets().
501
 * Returns a string for displaying the target configuration.
502
 *
503
 * Callback for hook_feeds_processor_targets().
504
 *
505
 * This callback is specified on the 'summary_callbacks' key of the target
506
 * definition.
507
 * The arguments are the same that callback_my_module_form_callback() gets.
449 508
 *
450 509
 * @param array $mapping
451 510
 *   Associative array of the mapping settings.
......
462 521
 *   the full form isn't visible.
463 522
 *   If the return value is empty, no summary and no option to view the form
464 523
 *   will be displayed.
524
 *
525
 * @see hook_feeds_processor_targets()
526
 * @see callback_my_module_form_callback()
527
 *
528
 * @ingroup callbacks
465 529
 */
466
function my_module_summary_callback(array $mapping, $target, array $form, array $form_state) {
530
function callback_my_module_summary_callback(array $mapping, $target, array $form, array $form_state) {
467 531
  if (empty($mapping['my_setting'])) {
468 532
    return t('My setting <strong>not</strong> active');
469 533
  }
......
473 537
}
474 538

  
475 539
/**
476
 * Example of the unique_callbacks specified in hook_feeds_processor_targets().
540
 * Looks for an existing entity and returns an entity ID if found.
541
 *
542
 * Callback for hook_feeds_processor_targets().
543
 *
544
 * This callback is specified on the 'unique_callbacks' key of the target
545
 * definition.
477 546
 *
478 547
 * @param FeedsSource $source
479 548
 *   The Feed source.
......
491 560
 *
492 561
 * @see hook_feeds_processor_targets()
493 562
 * @see FeedsProcessor::existingEntityId()
563
 *
564
 * @ingroup callbacks
494 565
 */
495
function my_module_mapper_unique(FeedsSource $source, $entity_type, $bundle, $target, array $values) {
566
function callback_my_module_mapper_unique(FeedsSource $source, $entity_type, $bundle, $target, array $values) {
496 567
  list($field_name, $column) = explode(':', $target . ':value');
497 568
  // Example for if the target is a field.
498 569
  $query = new EntityFieldQuery();
......
508 579
}
509 580

  
510 581
/**
511
 * Example of the preprocess_callbacks specified in hook_feeds_processor_targets().
582
 * Changes or sets a mapping option.
583
 *
584
 * Callback for hook_feeds_processor_targets().
585
 *
586
 * This callback is specified on the 'preprocess_callbacks' key of the target
587
 * definition.
512 588
 *
513 589
 * @param array $target
514 590
 *   The full target definition.
......
516 592
 *   The mapping configuration.
517 593
 *
518 594
 * @see hook_feeds_processor_targets()
595
 *
596
 * @ingroup callbacks
519 597
 */
520
function my_module_preprocess_callback(array $target, array &$mapping) {
598
function callback_my_module_preprocess_callback(array $target, array &$mapping) {
521 599
  // Add in default values.
522 600
  $mapping += array('setting_value' => TRUE);
523 601
}
524 602

  
525 603
/**
526
 * This hooks allows you add additional configuration keys to a
527
 * FeedsConfigurable.
604
 * Add additional configuration keys to FeedsConfigurable.
605
 *
606
 * This hooks allows you to add additional configuration keys to a
607
 * FeedsConfigurable. This is useful if you also implement a form alter hook to
608
 * provide extra options for existing Feeds plugins. By implementing one of the
609
 * Feeds hooks that are invoked during importing, you can act upon such setting.
528 610
 *
529 611
 * @param FeedsConfigurable $configurable
530 612
 *   The configurable item to add default configuration to.
......
542 624
}
543 625

  
544 626
/**
545
 * A plugin-specific hook to add additional configuration keys instead of the
546
 * global hook_feeds_config_defaults().
627
 * A plugin-specific hook to add additional configuration keys.
628
 *
629
 * This hook can be used instead of the global hook_feeds_config_defaults() and
630
 * allows you to add additional configuration keys to a FeedsPlugin.
547 631
 *
548 632
 * The plugin type can be:
549
 * - fetcher
550
 * - parser
551
 * - processor
633
 * - fetcher;
634
 * - parser;
635
 * - processor.
552 636
 *
553 637
 * @param FeedsPlugin $plugin
554 638
 *   The plugin to add default configuration to.
555 639
 *
556 640
 * @return array
557 641
 *   Return an array of default configuration.
642
 *
643
 * @see hook_feeds_config_defaults()
558 644
 */
559 645
function hook_feeds_PLUGIN_TYPE_config_defaults(FeedsPlugin $plugin) {
560 646
  if ($plugin instanceof FeedsCSVParser) {
......
565 651
}
566 652

  
567 653
/**
568
 * @}
654
 * @} End of "defgroup mappingapi".
569 655
 */

Formats disponibles : Unified diff