root / drupal7 / modules / aggregator / aggregator.api.php @ 134c7813
1 | 85ad3d82 | Assos Assos | <?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 | */ |