root / drupal7 / modules / aggregator / aggregator.api.php @ 01f36513
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Documentation for aggregator API.
|
6 |
*/
|
7 |
|
8 |
/**
|
9 |
* @addtogroup hooks
|
10 |
* @{
|
11 |
*/
|
12 |
|
13 |
/**
|
14 |
* Create an alternative fetcher for aggregator.module.
|
15 |
*
|
16 |
* A fetcher downloads feed data to a Drupal site. The fetcher is called at the
|
17 |
* first of the three aggregation stages: first, data is downloaded by the
|
18 |
* active fetcher; second, it is converted to a common format by the active
|
19 |
* parser; and finally, it is passed to all active processors, which manipulate
|
20 |
* or store the data.
|
21 |
*
|
22 |
* Modules that define this hook can be set as the active fetcher within the
|
23 |
* configuration page. Only one fetcher can be active at a time.
|
24 |
*
|
25 |
* @param $feed
|
26 |
* A feed object representing the resource to be downloaded. $feed->url
|
27 |
* contains the link to the feed. Download the data at the URL and expose it
|
28 |
* to other modules by attaching it to $feed->source_string.
|
29 |
*
|
30 |
* @return
|
31 |
* TRUE if fetching was successful, FALSE otherwise.
|
32 |
*
|
33 |
* @see hook_aggregator_fetch_info()
|
34 |
* @see hook_aggregator_parse()
|
35 |
* @see hook_aggregator_process()
|
36 |
*
|
37 |
* @ingroup aggregator
|
38 |
*/
|
39 |
function hook_aggregator_fetch($feed) { |
40 |
$feed->source_string = mymodule_fetch($feed->url); |
41 |
} |
42 |
|
43 |
/**
|
44 |
* Specify the title and short description of your fetcher.
|
45 |
*
|
46 |
* The title and the description provided are shown within the configuration
|
47 |
* page. Use as title the human readable name of the fetcher and as description
|
48 |
* a brief (40 to 80 characters) explanation of the fetcher's functionality.
|
49 |
*
|
50 |
* This hook is only called if your module implements hook_aggregator_fetch().
|
51 |
* If this hook is not implemented aggregator will use your module's file name
|
52 |
* as title and there will be no description.
|
53 |
*
|
54 |
* @return
|
55 |
* An associative array defining a title and a description string.
|
56 |
*
|
57 |
* @see hook_aggregator_fetch()
|
58 |
*
|
59 |
* @ingroup aggregator
|
60 |
*/
|
61 |
function hook_aggregator_fetch_info() { |
62 |
return array( |
63 |
'title' => t('Default fetcher'), |
64 |
'description' => t('Default fetcher for resources available by URL.'), |
65 |
); |
66 |
} |
67 |
|
68 |
/**
|
69 |
* Create an alternative parser for aggregator module.
|
70 |
*
|
71 |
* A parser converts feed item data to a common format. The parser is called
|
72 |
* at the second of the three aggregation stages: first, data is downloaded
|
73 |
* by the active fetcher; second, it is converted to a common format by the
|
74 |
* active parser; and finally, it is passed to all active processors which
|
75 |
* manipulate or store the data.
|
76 |
*
|
77 |
* Modules that define this hook can be set as the active parser within the
|
78 |
* configuration page. Only one parser can be active at a time.
|
79 |
*
|
80 |
* @param $feed
|
81 |
* An object describing the resource to be parsed. $feed->source_string
|
82 |
* contains the raw feed data. The hook implementation should parse this data
|
83 |
* and add the following properties to the $feed object:
|
84 |
* - description: The human-readable description of the feed.
|
85 |
* - link: A full URL that directly relates to the feed.
|
86 |
* - image: An image URL used to display an image of the feed.
|
87 |
* - etag: An entity tag from the HTTP header used for cache validation to
|
88 |
* determine if the content has been changed.
|
89 |
* - modified: The UNIX timestamp when the feed was last modified.
|
90 |
* - items: An array of feed items. The common format for a single feed item
|
91 |
* is an associative array containing:
|
92 |
* - title: The human-readable title of the feed item.
|
93 |
* - description: The full body text of the item or a summary.
|
94 |
* - timestamp: The UNIX timestamp when the feed item was last published.
|
95 |
* - author: The author of the feed item.
|
96 |
* - guid: The global unique identifier (GUID) string that uniquely
|
97 |
* identifies the item. If not available, the link is used to identify
|
98 |
* the item.
|
99 |
* - link: A full URL to the individual feed item.
|
100 |
*
|
101 |
* @return
|
102 |
* TRUE if parsing was successful, FALSE otherwise.
|
103 |
*
|
104 |
* @see hook_aggregator_parse_info()
|
105 |
* @see hook_aggregator_fetch()
|
106 |
* @see hook_aggregator_process()
|
107 |
*
|
108 |
* @ingroup aggregator
|
109 |
*/
|
110 |
function hook_aggregator_parse($feed) { |
111 |
if ($items = mymodule_parse($feed->source_string)) { |
112 |
$feed->items = $items; |
113 |
return TRUE; |
114 |
} |
115 |
return FALSE; |
116 |
} |
117 |
|
118 |
/**
|
119 |
* Specify the title and short description of your parser.
|
120 |
*
|
121 |
* The title and the description provided are shown within the configuration
|
122 |
* page. Use as title the human readable name of the parser and as description
|
123 |
* a brief (40 to 80 characters) explanation of the parser's functionality.
|
124 |
*
|
125 |
* This hook is only called if your module implements hook_aggregator_parse().
|
126 |
* If this hook is not implemented aggregator will use your module's file name
|
127 |
* as title and there will be no description.
|
128 |
*
|
129 |
* @return
|
130 |
* An associative array defining a title and a description string.
|
131 |
*
|
132 |
* @see hook_aggregator_parse()
|
133 |
*
|
134 |
* @ingroup aggregator
|
135 |
*/
|
136 |
function hook_aggregator_parse_info() { |
137 |
return array( |
138 |
'title' => t('Default parser'), |
139 |
'description' => t('Default parser for RSS, Atom and RDF feeds.'), |
140 |
); |
141 |
} |
142 |
|
143 |
/**
|
144 |
* Create a processor for aggregator.module.
|
145 |
*
|
146 |
* A processor acts on parsed feed data. Active processors are called at the
|
147 |
* third and last of the aggregation stages: first, data is downloaded by the
|
148 |
* active fetcher; second, it is converted to a common format by the active
|
149 |
* parser; and finally, it is passed to all active processors that manipulate or
|
150 |
* store the data.
|
151 |
*
|
152 |
* Modules that define this hook can be activated as a processor within the
|
153 |
* configuration page.
|
154 |
*
|
155 |
* @param $feed
|
156 |
* A feed object representing the resource to be processed. $feed->items
|
157 |
* contains an array of feed items downloaded and parsed at the parsing stage.
|
158 |
* See hook_aggregator_parse() for the basic format of a single item in the
|
159 |
* $feed->items array. For the exact format refer to the particular parser in
|
160 |
* use.
|
161 |
*
|
162 |
* @see hook_aggregator_process_info()
|
163 |
* @see hook_aggregator_fetch()
|
164 |
* @see hook_aggregator_parse()
|
165 |
*
|
166 |
* @ingroup aggregator
|
167 |
*/
|
168 |
function hook_aggregator_process($feed) { |
169 |
foreach ($feed->items as $item) { |
170 |
mymodule_save($item);
|
171 |
} |
172 |
} |
173 |
|
174 |
/**
|
175 |
* Specify the title and short description of your processor.
|
176 |
*
|
177 |
* The title and the description provided are shown within the configuration
|
178 |
* page. Use as title the natural name of the processor and as description a
|
179 |
* brief (40 to 80 characters) explanation of the functionality.
|
180 |
*
|
181 |
* This hook is only called if your module implements hook_aggregator_process().
|
182 |
* If this hook is not implemented aggregator will use your module's file name
|
183 |
* as title and there will be no description.
|
184 |
*
|
185 |
* @return
|
186 |
* An associative array defining a title and a description string.
|
187 |
*
|
188 |
* @see hook_aggregator_process()
|
189 |
*
|
190 |
* @ingroup aggregator
|
191 |
*/
|
192 |
function hook_aggregator_process_info() { |
193 |
return array( |
194 |
'title' => t('Default processor'), |
195 |
'description' => t('Creates lightweight records of feed items.'), |
196 |
); |
197 |
} |
198 |
|
199 |
/**
|
200 |
* Remove stored feed data.
|
201 |
*
|
202 |
* Aggregator calls this hook if either a feed is deleted or a user clicks on
|
203 |
* "remove items".
|
204 |
*
|
205 |
* If your module stores feed items for example on hook_aggregator_process() it
|
206 |
* is recommended to implement this hook and to remove data related to $feed
|
207 |
* when called.
|
208 |
*
|
209 |
* @param $feed
|
210 |
* The $feed object whose items are being removed.
|
211 |
*
|
212 |
* @ingroup aggregator
|
213 |
*/
|
214 |
function hook_aggregator_remove($feed) { |
215 |
mymodule_remove_items($feed->fid);
|
216 |
} |
217 |
|
218 |
/**
|
219 |
* @} End of "addtogroup hooks".
|
220 |
*/
|