summaryrefslogtreecommitdiff
path: root/kolab.org/www/drupal-7.26/modules/aggregator/aggregator.api.php
blob: d5cac4ec3dfbf25ef3e9d1f9666ee05259db1c4f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
<?php

/**
 * @file
 * Documentation for aggregator API.
 */

/**
 * @addtogroup hooks
 * @{
 */

/**
 * Create an alternative fetcher for aggregator.module.
 *
 * A fetcher downloads feed data to a Drupal site. The fetcher is called at the
 * first of the three aggregation stages: first, data is downloaded by the
 * active fetcher; second, it is converted to a common format by the active
 * parser; and finally, it is passed to all active processors, which manipulate
 * or store the data.
 *
 * Modules that define this hook can be set as the active fetcher within the
 * configuration page. Only one fetcher can be active at a time.
 *
 * @param $feed
 *   A feed object representing the resource to be downloaded. $feed->url
 *   contains the link to the feed. Download the data at the URL and expose it
 *   to other modules by attaching it to $feed->source_string.
 *
 * @return
 *   TRUE if fetching was successful, FALSE otherwise.
 *
 * @see hook_aggregator_fetch_info()
 * @see hook_aggregator_parse()
 * @see hook_aggregator_process()
 *
 * @ingroup aggregator
 */
function hook_aggregator_fetch($feed) {
  $feed->source_string = mymodule_fetch($feed->url);
}

/**
 * Specify the title and short description of your fetcher.
 *
 * The title and the description provided are shown within the configuration
 * page. Use as title the human readable name of the fetcher and as description
 * a brief (40 to 80 characters) explanation of the fetcher's functionality.
 *
 * This hook is only called if your module implements hook_aggregator_fetch().
 * If this hook is not implemented aggregator will use your module's file name
 * as title and there will be no description.
 *
 * @return
 *   An associative array defining a title and a description string.
 *
 * @see hook_aggregator_fetch()
 *
 * @ingroup aggregator
 */
function hook_aggregator_fetch_info() {
  return array(
    'title' => t('Default fetcher'),
    'description' => t('Default fetcher for resources available by URL.'),
  );
}

/**
 * Create an alternative parser for aggregator module.
 *
 * A parser converts feed item data to a common format. The parser is called
 * at the second of the three aggregation stages: first, data is downloaded
 * by the active fetcher; second, it is converted to a common format by the
 * active parser; and finally, it is passed to all active processors which
 * manipulate or store the data.
 *
 * Modules that define this hook can be set as the active parser within the
 * configuration page. Only one parser can be active at a time.
 *
 * @param $feed
 *   An object describing the resource to be parsed. $feed->source_string
 *   contains the raw feed data. The hook implementation should parse this data
 *   and add the following properties to the $feed object:
 *   - description: The human-readable description of the feed.
 *   - link: A full URL that directly relates to the feed.
 *   - image: An image URL used to display an image of the feed.
 *   - etag: An entity tag from the HTTP header used for cache validation to
 *     determine if the content has been changed.
 *   - modified: The UNIX timestamp when the feed was last modified.
 *   - items: An array of feed items. The common format for a single feed item
 *     is an associative array containing:
 *     - title: The human-readable title of the feed item.
 *     - description: The full body text of the item or a summary.
 *     - timestamp: The UNIX timestamp when the feed item was last published.
 *     - author: The author of the feed item.
 *     - guid: The global unique identifier (GUID) string that uniquely
 *       identifies the item. If not available, the link is used to identify
 *       the item.
 *     - link: A full URL to the individual feed item.
 *
 * @return
 *   TRUE if parsing was successful, FALSE otherwise.
 *
 * @see hook_aggregator_parse_info()
 * @see hook_aggregator_fetch()
 * @see hook_aggregator_process()
 *
 * @ingroup aggregator
 */
function hook_aggregator_parse($feed) {
  if ($items = mymodule_parse($feed->source_string)) {
    $feed->items = $items;
    return TRUE;
  }
  return FALSE;
}

/**
 * Specify the title and short description of your parser.
 *
 * The title and the description provided are shown within the configuration
 * page. Use as title the human readable name of the parser and as description
 * a brief (40 to 80 characters) explanation of the parser's functionality.
 *
 * This hook is only called if your module implements hook_aggregator_parse().
 * If this hook is not implemented aggregator will use your module's file name
 * as title and there will be no description.
 *
 * @return
 *   An associative array defining a title and a description string.
 *
 * @see hook_aggregator_parse()
 *
 * @ingroup aggregator
 */
function hook_aggregator_parse_info() {
  return array(
    'title' => t('Default parser'),
    'description' => t('Default parser for RSS, Atom and RDF feeds.'),
  );
}

/**
 * Create a processor for aggregator.module.
 *
 * A processor acts on parsed feed data. Active processors are called at the
 * third and last of the aggregation stages: first, data is downloaded by the
 * active fetcher; second, it is converted to a common format by the active
 * parser; and finally, it is passed to all active processors that manipulate or
 * store the data.
 *
 * Modules that define this hook can be activated as a processor within the
 * configuration page.
 *
 * @param $feed
 *   A feed object representing the resource to be processed. $feed->items
 *   contains an array of feed items downloaded and parsed at the parsing stage.
 *   See hook_aggregator_parse() for the basic format of a single item in the
 *   $feed->items array. For the exact format refer to the particular parser in
 *   use.
 *
 * @see hook_aggregator_process_info()
 * @see hook_aggregator_fetch()
 * @see hook_aggregator_parse()
 *
 * @ingroup aggregator
 */
function hook_aggregator_process($feed) {
  foreach ($feed->items as $item) {
    mymodule_save($item);
  }
}

/**
 * Specify the title and short description of your processor.
 *
 * The title and the description provided are shown within the configuration
 * page. Use as title the natural name of the processor and as description a
 * brief (40 to 80 characters) explanation of the functionality.
 *
 * This hook is only called if your module implements hook_aggregator_process().
 * If this hook is not implemented aggregator will use your module's file name
 * as title and there will be no description.
 *
 * @return
 *   An associative array defining a title and a description string.
 *
 * @see hook_aggregator_process()
 *
 * @ingroup aggregator
 */
function hook_aggregator_process_info() {
  return array(
    'title' => t('Default processor'),
    'description' => t('Creates lightweight records of feed items.'),
  );
}

/**
 * Remove stored feed data.
 *
 * Aggregator calls this hook if either a feed is deleted or a user clicks on
 * "remove items".
 *
 * If your module stores feed items for example on hook_aggregator_process() it
 * is recommended to implement this hook and to remove data related to $feed
 * when called.
 *
 * @param $feed
 *   The $feed object whose items are being removed.
 *
 * @ingroup aggregator
 */
function hook_aggregator_remove($feed) {
  mymodule_remove_items($feed->fid);
}

/**
 * @} End of "addtogroup hooks".
 */