- Patch #303930 by Aron Novak, alex_b, et al: introduced pluggable architecture for aggregator

1 files changed, 214 insertions, 0 deletions

diff --git a/modules/aggregator/aggregator.api.php b/modules/aggregator/aggregator.api.php
new file mode 100644
index 000000000..e68fcb51c
--- /dev/null
+++ b/modules/aggregator/aggregator.api.php
@@ -0,0 +1,214 @@
+<?php
+// $Id$
+
+/**
+ * @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/content/aggregator/settings. 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/content/aggregator/settings 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/content/aggregator/settings. 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. 
+ *   
+ *   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
+ *
+ * @see hook_aggregator_parse_info()
+ * @see hook_aggregator_fetch()
+ * @see hook_aggregator_process()
+ * 
+ * @ingroup aggregator
+ */
+function hook_aggregator_parse($feed) {
+  $feed->items = mymodule_parse($feed->source_string);
+}
+
+/**
+ * Implement this hook to expose the title and a short description of your 
+ * parser.
+ * 
+ * The title and the description provided are shown on 
+ * admin/content/aggregator/settings 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/content/aggregator/settings.
+ * 
+ * @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/content/aggregator/settings . 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".
+ */