danielebarchiesi@0: <?php
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * @file
danielebarchiesi@0:  * Documentation for aggregator API.
danielebarchiesi@0:  */
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * @addtogroup hooks
danielebarchiesi@0:  * @{
danielebarchiesi@0:  */
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Create an alternative fetcher for aggregator.module.
danielebarchiesi@0:  *
danielebarchiesi@0:  * A fetcher downloads feed data to a Drupal site. The fetcher is called at the
danielebarchiesi@0:  * first of the three aggregation stages: first, data is downloaded by the
danielebarchiesi@0:  * active fetcher; second, it is converted to a common format by the active
danielebarchiesi@0:  * parser; and finally, it is passed to all active processors, which manipulate
danielebarchiesi@0:  * or store the data.
danielebarchiesi@0:  *
danielebarchiesi@0:  * Modules that define this hook can be set as the active fetcher within the
danielebarchiesi@0:  * configuration page. Only one fetcher can be active at a time.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $feed
danielebarchiesi@0:  *   A feed object representing the resource to be downloaded. $feed->url
danielebarchiesi@0:  *   contains the link to the feed. Download the data at the URL and expose it
danielebarchiesi@0:  *   to other modules by attaching it to $feed->source_string.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @return
danielebarchiesi@0:  *   TRUE if fetching was successful, FALSE otherwise.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see hook_aggregator_fetch_info()
danielebarchiesi@0:  * @see hook_aggregator_parse()
danielebarchiesi@0:  * @see hook_aggregator_process()
danielebarchiesi@0:  *
danielebarchiesi@0:  * @ingroup aggregator
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_aggregator_fetch($feed) {
danielebarchiesi@0:   $feed->source_string = mymodule_fetch($feed->url);
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Specify the title and short description of your fetcher.
danielebarchiesi@0:  *
danielebarchiesi@0:  * The title and the description provided are shown within the configuration
danielebarchiesi@0:  * page. Use as title the human readable name of the fetcher and as description
danielebarchiesi@0:  * a brief (40 to 80 characters) explanation of the fetcher's functionality.
danielebarchiesi@0:  *
danielebarchiesi@0:  * This hook is only called if your module implements hook_aggregator_fetch().
danielebarchiesi@0:  * If this hook is not implemented aggregator will use your module's file name
danielebarchiesi@0:  * as title and there will be no description.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @return
danielebarchiesi@0:  *   An associative array defining a title and a description string.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see hook_aggregator_fetch()
danielebarchiesi@0:  *
danielebarchiesi@0:  * @ingroup aggregator
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_aggregator_fetch_info() {
danielebarchiesi@0:   return array(
danielebarchiesi@0:     'title' => t('Default fetcher'),
danielebarchiesi@0:     'description' => t('Default fetcher for resources available by URL.'),
danielebarchiesi@0:   );
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Create an alternative parser for aggregator module.
danielebarchiesi@0:  *
danielebarchiesi@0:  * A parser converts feed item data to a common format. The parser is called
danielebarchiesi@0:  * at the second of the three aggregation stages: first, data is downloaded
danielebarchiesi@0:  * by the active fetcher; second, it is converted to a common format by the
danielebarchiesi@0:  * active parser; and finally, it is passed to all active processors which
danielebarchiesi@0:  * manipulate or store the data.
danielebarchiesi@0:  *
danielebarchiesi@0:  * Modules that define this hook can be set as the active parser within the
danielebarchiesi@0:  * configuration page. Only one parser can be active at a time.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $feed
danielebarchiesi@0:  *   An object describing the resource to be parsed. $feed->source_string
danielebarchiesi@0:  *   contains the raw feed data. The hook implementation should parse this data
danielebarchiesi@0:  *   and add the following properties to the $feed object:
danielebarchiesi@0:  *   - description: The human-readable description of the feed.
danielebarchiesi@0:  *   - link: A full URL that directly relates to the feed.
danielebarchiesi@0:  *   - image: An image URL used to display an image of the feed.
danielebarchiesi@0:  *   - etag: An entity tag from the HTTP header used for cache validation to
danielebarchiesi@0:  *     determine if the content has been changed.
danielebarchiesi@0:  *   - modified: The UNIX timestamp when the feed was last modified.
danielebarchiesi@0:  *   - items: An array of feed items. The common format for a single feed item
danielebarchiesi@0:  *     is an associative array containing:
danielebarchiesi@0:  *     - title: The human-readable title of the feed item.
danielebarchiesi@0:  *     - description: The full body text of the item or a summary.
danielebarchiesi@0:  *     - timestamp: The UNIX timestamp when the feed item was last published.
danielebarchiesi@0:  *     - author: The author of the feed item.
danielebarchiesi@0:  *     - guid: The global unique identifier (GUID) string that uniquely
danielebarchiesi@0:  *       identifies the item. If not available, the link is used to identify
danielebarchiesi@0:  *       the item.
danielebarchiesi@0:  *     - link: A full URL to the individual feed item.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @return
danielebarchiesi@0:  *   TRUE if parsing was successful, FALSE otherwise.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see hook_aggregator_parse_info()
danielebarchiesi@0:  * @see hook_aggregator_fetch()
danielebarchiesi@0:  * @see hook_aggregator_process()
danielebarchiesi@0:  *
danielebarchiesi@0:  * @ingroup aggregator
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_aggregator_parse($feed) {
danielebarchiesi@0:   if ($items = mymodule_parse($feed->source_string)) {
danielebarchiesi@0:     $feed->items = $items;
danielebarchiesi@0:     return TRUE;
danielebarchiesi@0:   }
danielebarchiesi@0:   return FALSE;
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Specify the title and short description of your parser.
danielebarchiesi@0:  *
danielebarchiesi@0:  * The title and the description provided are shown within the configuration
danielebarchiesi@0:  * page. Use as title the human readable name of the parser and as description
danielebarchiesi@0:  * a brief (40 to 80 characters) explanation of the parser's functionality.
danielebarchiesi@0:  *
danielebarchiesi@0:  * This hook is only called if your module implements hook_aggregator_parse().
danielebarchiesi@0:  * If this hook is not implemented aggregator will use your module's file name
danielebarchiesi@0:  * as title and there will be no description.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @return
danielebarchiesi@0:  *   An associative array defining a title and a description string.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see hook_aggregator_parse()
danielebarchiesi@0:  *
danielebarchiesi@0:  * @ingroup aggregator
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_aggregator_parse_info() {
danielebarchiesi@0:   return array(
danielebarchiesi@0:     'title' => t('Default parser'),
danielebarchiesi@0:     'description' => t('Default parser for RSS, Atom and RDF feeds.'),
danielebarchiesi@0:   );
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Create a processor for aggregator.module.
danielebarchiesi@0:  *
danielebarchiesi@0:  * A processor acts on parsed feed data. Active processors are called at the
danielebarchiesi@0:  * third and last of the aggregation stages: first, data is downloaded by the
danielebarchiesi@0:  * active fetcher; second, it is converted to a common format by the active
danielebarchiesi@0:  * parser; and finally, it is passed to all active processors that manipulate or
danielebarchiesi@0:  * store the data.
danielebarchiesi@0:  *
danielebarchiesi@0:  * Modules that define this hook can be activated as a processor within the
danielebarchiesi@0:  * configuration page.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $feed
danielebarchiesi@0:  *   A feed object representing the resource to be processed. $feed->items
danielebarchiesi@0:  *   contains an array of feed items downloaded and parsed at the parsing stage.
danielebarchiesi@0:  *   See hook_aggregator_parse() for the basic format of a single item in the
danielebarchiesi@0:  *   $feed->items array. For the exact format refer to the particular parser in
danielebarchiesi@0:  *   use.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see hook_aggregator_process_info()
danielebarchiesi@0:  * @see hook_aggregator_fetch()
danielebarchiesi@0:  * @see hook_aggregator_parse()
danielebarchiesi@0:  *
danielebarchiesi@0:  * @ingroup aggregator
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_aggregator_process($feed) {
danielebarchiesi@0:   foreach ($feed->items as $item) {
danielebarchiesi@0:     mymodule_save($item);
danielebarchiesi@0:   }
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Specify the title and short description of your processor.
danielebarchiesi@0:  *
danielebarchiesi@0:  * The title and the description provided are shown within the configuration
danielebarchiesi@0:  * page. Use as title the natural name of the processor and as description a
danielebarchiesi@0:  * brief (40 to 80 characters) explanation of the functionality.
danielebarchiesi@0:  *
danielebarchiesi@0:  * This hook is only called if your module implements hook_aggregator_process().
danielebarchiesi@0:  * If this hook is not implemented aggregator will use your module's file name
danielebarchiesi@0:  * as title and there will be no description.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @return
danielebarchiesi@0:  *   An associative array defining a title and a description string.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @see hook_aggregator_process()
danielebarchiesi@0:  *
danielebarchiesi@0:  * @ingroup aggregator
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_aggregator_process_info() {
danielebarchiesi@0:   return array(
danielebarchiesi@0:     'title' => t('Default processor'),
danielebarchiesi@0:     'description' => t('Creates lightweight records of feed items.'),
danielebarchiesi@0:   );
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * Remove stored feed data.
danielebarchiesi@0:  *
danielebarchiesi@0:  * Aggregator calls this hook if either a feed is deleted or a user clicks on
danielebarchiesi@0:  * "remove items".
danielebarchiesi@0:  *
danielebarchiesi@0:  * If your module stores feed items for example on hook_aggregator_process() it
danielebarchiesi@0:  * is recommended to implement this hook and to remove data related to $feed
danielebarchiesi@0:  * when called.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @param $feed
danielebarchiesi@0:  *   The $feed object whose items are being removed.
danielebarchiesi@0:  *
danielebarchiesi@0:  * @ingroup aggregator
danielebarchiesi@0:  */
danielebarchiesi@0: function hook_aggregator_remove($feed) {
danielebarchiesi@0:   mymodule_remove_items($feed->fid);
danielebarchiesi@0: }
danielebarchiesi@0: 
danielebarchiesi@0: /**
danielebarchiesi@0:  * @} End of "addtogroup hooks".
danielebarchiesi@0:  */