Stripping CVS keywords
[project/feeds.git] / 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 */