1 <?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  */