modules/aggregator/aggregator.api.php

<?php
// $Id: aggregator.api.php,v 1.5 2009/08/24 17:11:41 webchick Exp $

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

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

/**
 * Implement this hook to 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: data is downloaded by the
 * active fetcher, 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 active fetcher on
 * admin/config/services/aggregator. Only one fetcher can be active at a time.
 *
 * @param $feed
 *   The $feed object that describes 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.
 *
 * @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);
}

/**
 * Implement this hook to expose the title and a short description of your
 * fetcher.
 *
 * The title and the description provided are shown on
 * admin/config/services/aggregator among other places. 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.'),
  );
}

/**
 * Implement this hook to 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: data is downloaded by the
 * active fetcher, 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 active parser on
 * admin/config/services/aggregator. Only one parser can be active at a time.
 *
 * @param $feed
 *   The $feed object that describes the resource to be parsed.
 *   $feed->source_string contains the raw feed data as a string. Parse data
 *   from $feed->source_string and expose it to other modules as an array of
 *   data items on $feed->items.
 * 
 *   Feed format:
 *   - $feed->description (string) - description of the feed
 *   - $feed->image (string) - image for the feed
 *   - $feed->etag (string) - value of feed's entity tag header field
 *   - $feed->modified (UNIX timestamp) - value of feed's last modified header 
 *     field
 *   - $feed->items (Array) - array of feed items.
 *
 *   By convention, the common format for a single feed item is:
 *   $item[key-name] = value;
 *
 *   Recognized keys:
 *   TITLE (string) - the title of a feed item
 *   DESCRIPTION (string) - the description (body text) of a feed item
 *   TIMESTAMP (UNIX timestamp) - the feed item's published time as UNIX timestamp
 *   AUTHOR (string) - the feed item's author
 *   GUID (string) - RSS/Atom global unique identifier
 *   LINK (string) - the feed item's URL
 * 
 * @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;  
}

/**
 * Implement this hook to expose the title and a short description of your
 * parser.
 *
 * The title and the description provided are shown on
 * admin/config/services/aggregator among other places. 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.'),
  );
}

/**
 * Implement this hook to 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: data is downloaded by the active
 * fetcher, 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 activated as processor on
 * admin/config/services/aggregator.
 *
 * @param $feed
 *   The $feed object that describes 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);
  }
}

/**
 * Implement this hook to expose the title and a short description of your
 * processor.
 *
 * The title and the description provided are shown most importantly on
 * admin/config/services/aggregator. 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($feed) {
  return array(
    'title' => t('Default processor'),
    'description' => t('Creates lightweight records of feed items.'),
  );
}

/**
 * Implement this hook to remove stored data if a feed is being deleted or a
 * feed's items are being removed.
 *
 * 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".
 */
1	<?php
2	// $Id: aggregator.api.php,v 1.5 2009/08/24 17:11:41 webchick Exp $
3
4	/**
5	* @file
6	* Documentation for aggregator API.
7	*/
8
9	/**
10	* @addtogroup hooks
11	* @{
12	*/
13
14	/**
15	* Implement this hook to create an alternative fetcher for aggregator module.
16	*
17	* A fetcher downloads feed data to a Drupal site. The fetcher is called
18	* at the first of the three aggregation stages: data is downloaded by the
19	* active fetcher, it is converted to a common format by the active parser and
20	* finally, it is passed to all active processors which manipulate or store the
21	* data.
22	*
23	* Modules that define this hook can be set as active fetcher on
24	* admin/config/services/aggregator. Only one fetcher can be active at a time.
25	*
26	* @param $feed
27	* The $feed object that describes the resource to be downloaded.
28	* $feed->url contains the link to the feed. Download the data at the URL
29	* and expose it to other modules by attaching it to $feed->source_string.
30	*
31	* @see hook_aggregator_fetch_info()
32	* @see hook_aggregator_parse()
33	* @see hook_aggregator_process()
34	*
35	* @ingroup aggregator
36	*/
37	function hook_aggregator_fetch($feed) {
38	$feed->source_string = mymodule_fetch($feed->url);
39	}
40
41	/**
42	* Implement this hook to expose the title and a short description of your
43	* fetcher.
44	*
45	* The title and the description provided are shown on
46	* admin/config/services/aggregator among other places. Use as title the human
47	* readable name of the fetcher and as description a brief (40 to 80 characters)
48	* 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	* Implement this hook to 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: data is downloaded by the
73	* active fetcher, it is converted to a common format by the active parser and
74	* finally, it is passed to all active processors which manipulate or store the
75	* data.
76	*
77	* Modules that define this hook can be set as active parser on
78	* admin/config/services/aggregator. Only one parser can be active at a time.
79	*
80	* @param $feed
81	* The $feed object that describes the resource to be parsed.
82	* $feed->source_string contains the raw feed data as a string. Parse data
83	* from $feed->source_string and expose it to other modules as an array of
84	* data items on $feed->items.
85	*
86	* Feed format:
87	* - $feed->description (string) - description of the feed
88	* - $feed->image (string) - image for the feed
89	* - $feed->etag (string) - value of feed's entity tag header field
90	* - $feed->modified (UNIX timestamp) - value of feed's last modified header
91	* field
92	* - $feed->items (Array) - array of feed items.
93	*
94	* By convention, the common format for a single feed item is:
95	* $item[key-name] = value;
96	*
97	* Recognized keys:
98	* TITLE (string) - the title of a feed item
99	* DESCRIPTION (string) - the description (body text) of a feed item
100	* TIMESTAMP (UNIX timestamp) - the feed item's published time as UNIX timestamp
101	* AUTHOR (string) - the feed item's author
102	* GUID (string) - RSS/Atom global unique identifier
103	* LINK (string) - the feed item's URL
104	*
105	* @return
106	* TRUE if parsing was successful, FALSE otherwise.
107	*
108	* @see hook_aggregator_parse_info()
109	* @see hook_aggregator_fetch()
110	* @see hook_aggregator_process()
111	*
112	* @ingroup aggregator
113	*/
114	function hook_aggregator_parse($feed) {
115	if ($items = mymodule_parse($feed->source_string)) {
116	$feed->items = $items;
117	return TRUE;
118	}
119	return FALSE;
120	}
121
122	/**
123	* Implement this hook to expose the title and a short description of your
124	* parser.
125	*
126	* The title and the description provided are shown on
127	* admin/config/services/aggregator among other places. Use as title the human
128	* readable name of the parser and as description a brief (40 to 80 characters)
129	* explanation of the parser's functionality.
130	*
131	* This hook is only called if your module implements hook_aggregator_parse().
132	* If this hook is not implemented aggregator will use your module's file name
133	* as title and there will be no description.
134	*
135	* @return
136	* An associative array defining a title and a description string.
137	*
138	* @see hook_aggregator_parse()
139	*
140	* @ingroup aggregator
141	*/
142	function hook_aggregator_parse_info() {
143	return array(
144	'title' => t('Default parser'),
145	'description' => t('Default parser for RSS, Atom and RDF feeds.'),
146	);
147	}
148
149	/**
150	* Implement this hook to create a processor for aggregator module.
151	*
152	* A processor acts on parsed feed data. Active processors are called at the
153	* third and last of the aggregation stages: data is downloaded by the active
154	* fetcher, it is converted to a common format by the active parser and
155	* finally, it is passed to all active processors which manipulate or store the
156	* data.
157	*
158	* Modules that define this hook can be activated as processor on
159	* admin/config/services/aggregator.
160	*
161	* @param $feed
162	* The $feed object that describes the resource to be processed. $feed->items
163	* contains an array of feed items downloaded and parsed at the parsing
164	* stage. See hook_aggregator_parse() for the basic format of a single item
165	* in the $feed->items array. For the exact format refer to the particular
166	* parser in use.
167	*
168	* @see hook_aggregator_process_info()
169	* @see hook_aggregator_fetch()
170	* @see hook_aggregator_parse()
171	*
172	* @ingroup aggregator
173	*/
174	function hook_aggregator_process($feed) {
175	foreach ($feed->items as $item) {
176	mymodule_save($item);
177	}
178	}
179
180	/**
181	* Implement this hook to expose the title and a short description of your
182	* processor.
183	*
184	* The title and the description provided are shown most importantly on
185	* admin/config/services/aggregator. Use as title the natural name of the
186	* processor and as description a brief (40 to 80 characters) explanation of
187	* the functionality.
188	*
189	* This hook is only called if your module implements
190	* hook_aggregator_process(). If this hook is not implemented aggregator
191	* will use your module's file name as title and there will be no description.
192	*
193	* @return
194	* An associative array defining a title and a description string.
195	*
196	* @see hook_aggregator_process()
197	*
198	* @ingroup aggregator
199	*/
200	function hook_aggregator_process_info($feed) {
201	return array(
202	'title' => t('Default processor'),
203	'description' => t('Creates lightweight records of feed items.'),
204	);
205	}
206
207	/**
208	* Implement this hook to remove stored data if a feed is being deleted or a
209	* feed's items are being removed.
210	*
211	* Aggregator calls this hook if either a feed is deleted or a user clicks on
212	* "remove items".
213	*
214	* If your module stores feed items for example on hook_aggregator_process() it
215	* is recommended to implement this hook and to remove data related to $feed
216	* when called.
217	*
218	* @param $feed
219	* The $feed object whose items are being removed.
220	*
221	* @ingroup aggregator
222	*/
223	function hook_aggregator_remove($feed) {
224	mymodule_remove_items($feed->fid);
225	}
226
227	/**
228	* @} End of "addtogroup hooks".
229	*/