feeds.api.php

   1 <?php
   2
   3 /**
   4  * @mainpage
   5  *
   6  * @verbinclude README.txt
   7  */
   8
   9 /**
  10  * Feeds offers a CTools based plugin API. Fetchers, parsers and processors are
  11  * declared to Feeds as plugins.
  12  *
  13  * @see feeds_feeds_plugins()
  14  * @see FeedsFetcher
  15  * @see FeedsParser
  16  * @see FeedsProcessor
  17  *
  18  * @defgroup pluginapi Plugin API
  19  * @{
  20  */
  21
  22 /**
  23  * Example of a CTools plugin hook that needs to be implemented to make
  24  * hook_feeds_plugins() discoverable by CTools and Feeds. The hook specifies
  25  * that the hook_feeds_plugins() returns Feeds Plugin API version 1 style
  26  * plugins.
  27  */
  28 function hook_ctools_plugin_api($owner, $api) {
  29   if ($owner == 'feeds' && $api == 'plugins') {
  30     return array('version' => 1);
  31   }
  32 }
  33
  34 /**
  35  * A hook_feeds_plugins() declares available Fetcher, Parser or Processor
  36  * plugins to Feeds. For an example look at feeds_feeds_plugin(). For exposing
  37  * this hook hook_ctools_plugin_api() MUST be implemented, too.
  38  *
  39  * @see feeds_feeds_plugin()
  40  */
  41 function hook_feeds_plugins() {
  42   $info = array();
  43   $info['MyFetcher'] = array(
  44     'name' => 'My Fetcher',
  45     'description' => 'Fetches my stuff.',
  46     'help' => 'More verbose description here. Will be displayed on fetcher selection menu.',
  47     'handler' => array(
  48       'parent' => 'FeedsFetcher',
  49       'class' => 'MyFetcher',
  50       'file' => 'MyFetcher.inc',
  51       'path' => drupal_get_path('module', 'my_module'), // Feeds will look for MyFetcher.inc in the my_module directory.
  52     ),
  53   );
  54   $info['MyParser'] = array(
  55     'name' => 'ODK parser',
  56     'description' => 'Parse my stuff.',
  57     'help' => 'More verbose description here. Will be displayed on parser selection menu.',
  58     'handler' => array(
  59       'parent' => 'FeedsParser', // Being directly or indirectly an extension of FeedsParser makes a plugin a parser plugin.
  60       'class' => 'MyParser',
  61       'file' => 'MyParser.inc',
  62       'path' => drupal_get_path('module', 'my_module'),
  63     ),
  64   );
  65   $info['MyProcessor'] = array(
  66     'name' => 'ODK parser',
  67     'description' => 'Process my stuff.',
  68     'help' => 'More verbose description here. Will be displayed on processor selection menu.',
  69     'handler' => array(
  70       'parent' => 'FeedsProcessor',
  71       'class' => 'MyProcessor',
  72       'file' => 'MyProcessor.inc',
  73       'path' => drupal_get_path('module', 'my_module'),
  74     ),
  75   );
  76   return $info;
  77 }
  78
  79 /**
  80  * @}
  81  */
  82
  83 /**
  84  * @defgroup import Import and clear hooks
  85  * @{
  86  */
  87
  88 /**
  89  * Invoked after a feed source has been parsed, before it will be processed.
  90  *
  91  * @param $importer
  92  *   FeedsImporter object that has been used for importing the feed.
  93  * @param $source
  94  *  FeedsSource object that describes the source that has been imported.
  95  */
  96 function hook_feeds_after_parse(FeedsImporter $importer, FeedsSource $source) {
  97   // For example, set title of imported content:
  98   $source->batch->setTitle('Import number '. my_module_import_id());
  99 }
 100
 101 /**
 102  * Invoked after a feed source has been imported.
 103  *
 104  * @param $importer
 105  *   FeedsImporter object that has been used for importing the feed.
 106  * @param $source
 107  *  FeedsSource object that describes the source that has been imported.
 108  */
 109 function hook_feeds_after_import(FeedsImporter $importer, FeedsSource $source) {
 110   // See geotaxonomy module's implementation for an example.
 111 }
 112
 113 /**
 114  * Invoked after a feed source has been cleared of its items.
 115  *
 116  * @param $importer
 117  *   FeedsImporter object that has been used for clearing the feed.
 118  * @param $source
 119  *  FeedsSource object that describes the source that has been cleared.
 120  */
 121 function hook_feeds_after_clear(FeedsImporter $importer, FeedsSource $source) {
 122 }
 123
 124 /**
 125  * @}
 126  */
 127
 128 /**
 129  * @defgroup mappingapi Mapping API
 130  * @{
 131  */
 132
 133 /**
 134  * Alter mapping sources.
 135  *
 136  * Use this hook to add additional mapping sources for any parser. Allows for
 137  * registering a callback to be invoked at mapping time.
 138  *
 139  * my_callback(FeedsImportBatch $batch, $key)
 140  *
 141  * @see my_source_get_source().
 142  * @see locale_feeds_parser_sources_alter().
 143  */
 144 function hook_feeds_parser_sources_alter(&$sources, $content_type) {
 145   $sources['my_source'] = array(
 146     'name' => t('Images in description element'),
 147     'description' => t('Images occuring in the description element of a feed item.'),
 148     'callback' => 'my_source_get_source',
 149   );
 150 }
 151
 152 /**
 153  * Example callback specified in hook_feeds_parser_sources_alter().
 154  *
 155  * To be invoked on mapping time.
 156  *
 157  * @param $batch
 158  *   The FeedsImportBatch object being mapped from.
 159  * @param $key
 160  *   The key specified in the $sources array in
 161  *   hook_feeds_parser_sources_alter().
 162  *
 163  * @return
 164  *   The value to be extracted from the source.
 165  *
 166  * @see hook_feeds_parser_sources_alter().
 167  * @see locale_feeds_get_source().
 168  */
 169 function my_source_get_source(FeedsImportBatch $batch, $key) {
 170   $item = $batch->currentItem();
 171   return my_source_parse_images($item['description']);
 172 }
 173
 174 /**
 175  * Alter mapping targets for entities. Use this hook to add additional target
 176  * options to the mapping form of Node processors.
 177  *
 178  * If the key in $targets[] does not correspond to the actual key on the node
 179  * object ($node->key), real_target MUST be specified. See mappers/link.inc
 180  *
 181  * For an example implementation, see mappers/content.inc
 182  *
 183  * @param &$targets
 184  *   Array containing the targets to be offered to the user. Add to this array
 185  *   to expose additional options. Remove from this array to suppress options.
 186  *   Remove with caution.
 187  * @param $entity_type
 188  *   The entity type of the target, for instance a 'node' entity.
 189  * @param $content_type
 190  *   The content type of the target node.
 191  */
 192 function hook_feeds_processor_targets_alter(&$targets, $entity_type, $content_type) {
 193   if ($entity_type == 'node') {
 194     $targets['my_node_field'] = array(
 195       'name' => t('My custom node field'),
 196       'description' => t('Description of what my custom node field does.'),
 197       'callback' => 'my_module_set_target',
 198     );
 199     $targets['my_node_field2'] = array(
 200       'name' => t('My Second custom node field'),
 201       'description' => t('Description of what my second custom node field does.'),
 202       'callback' => 'my_module_set_target2',
 203       'real_target' => 'my_node_field_two', // Specify real target field on node.
 204     );
 205   }
 206 }
 207
 208 /**
 209  * Example callback specified in hook_feeds_processor_targets_alter().
 210  *
 211  * @param $entity
 212  *   An entity object, for instance a node object.
 213  * @param $target
 214  *   A string identifying the target on the node.
 215  * @param $value
 216  *   The value to populate the target with.
 217  *
 218  */
 219 function my_module_set_target($entity, $target, $value) {
 220   $entity->$target['und'][0]['value'] = $value;
 221 }
 222
 223 /**
 224  * @}
 225  */