aggregator.api.php 7.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220
  1. <?php
  2. /**
  3. * @file
  4. * Documentation for aggregator API.
  5. */
  6. /**
  7. * @addtogroup hooks
  8. * @{
  9. */
  10. /**
  11. * Create an alternative fetcher for aggregator.module.
  12. *
  13. * A fetcher downloads feed data to a Drupal site. The fetcher is called at the
  14. * first of the three aggregation stages: first, data is downloaded by the
  15. * active fetcher; second, it is converted to a common format by the active
  16. * parser; and finally, it is passed to all active processors, which manipulate
  17. * or store the data.
  18. *
  19. * Modules that define this hook can be set as the active fetcher within the
  20. * configuration page. Only one fetcher can be active at a time.
  21. *
  22. * @param $feed
  23. * A feed object representing the resource to be downloaded. $feed->url
  24. * contains the link to the feed. Download the data at the URL and expose it
  25. * to other modules by attaching it to $feed->source_string.
  26. *
  27. * @return
  28. * TRUE if fetching was successful, FALSE otherwise.
  29. *
  30. * @see hook_aggregator_fetch_info()
  31. * @see hook_aggregator_parse()
  32. * @see hook_aggregator_process()
  33. *
  34. * @ingroup aggregator
  35. */
  36. function hook_aggregator_fetch($feed) {
  37. $feed->source_string = mymodule_fetch($feed->url);
  38. }
  39. /**
  40. * Specify the title and short description of your fetcher.
  41. *
  42. * The title and the description provided are shown within the configuration
  43. * page. Use as title the human readable name of the fetcher and as description
  44. * a brief (40 to 80 characters) explanation of the fetcher's functionality.
  45. *
  46. * This hook is only called if your module implements hook_aggregator_fetch().
  47. * If this hook is not implemented aggregator will use your module's file name
  48. * as title and there will be no description.
  49. *
  50. * @return
  51. * An associative array defining a title and a description string.
  52. *
  53. * @see hook_aggregator_fetch()
  54. *
  55. * @ingroup aggregator
  56. */
  57. function hook_aggregator_fetch_info() {
  58. return array(
  59. 'title' => t('Default fetcher'),
  60. 'description' => t('Default fetcher for resources available by URL.'),
  61. );
  62. }
  63. /**
  64. * Create an alternative parser for aggregator module.
  65. *
  66. * A parser converts feed item data to a common format. The parser is called
  67. * at the second of the three aggregation stages: first, data is downloaded
  68. * by the active fetcher; second, it is converted to a common format by the
  69. * active parser; and finally, it is passed to all active processors which
  70. * manipulate or store the data.
  71. *
  72. * Modules that define this hook can be set as the active parser within the
  73. * configuration page. Only one parser can be active at a time.
  74. *
  75. * @param $feed
  76. * An object describing the resource to be parsed. $feed->source_string
  77. * contains the raw feed data. The hook implementation should parse this data
  78. * and add the following properties to the $feed object:
  79. * - description: The human-readable description of the feed.
  80. * - link: A full URL that directly relates to the feed.
  81. * - image: An image URL used to display an image of the feed.
  82. * - etag: An entity tag from the HTTP header used for cache validation to
  83. * determine if the content has been changed.
  84. * - modified: The UNIX timestamp when the feed was last modified.
  85. * - items: An array of feed items. The common format for a single feed item
  86. * is an associative array containing:
  87. * - title: The human-readable title of the feed item.
  88. * - description: The full body text of the item or a summary.
  89. * - timestamp: The UNIX timestamp when the feed item was last published.
  90. * - author: The author of the feed item.
  91. * - guid: The global unique identifier (GUID) string that uniquely
  92. * identifies the item. If not available, the link is used to identify
  93. * the item.
  94. * - link: A full URL to the individual feed item.
  95. *
  96. * @return
  97. * TRUE if parsing was successful, FALSE otherwise.
  98. *
  99. * @see hook_aggregator_parse_info()
  100. * @see hook_aggregator_fetch()
  101. * @see hook_aggregator_process()
  102. *
  103. * @ingroup aggregator
  104. */
  105. function hook_aggregator_parse($feed) {
  106. if ($items = mymodule_parse($feed->source_string)) {
  107. $feed->items = $items;
  108. return TRUE;
  109. }
  110. return FALSE;
  111. }
  112. /**
  113. * Specify the title and short description of your parser.
  114. *
  115. * The title and the description provided are shown within the configuration
  116. * page. Use as title the human readable name of the parser and as description
  117. * a brief (40 to 80 characters) explanation of the parser's functionality.
  118. *
  119. * This hook is only called if your module implements hook_aggregator_parse().
  120. * If this hook is not implemented aggregator will use your module's file name
  121. * as title and there will be no description.
  122. *
  123. * @return
  124. * An associative array defining a title and a description string.
  125. *
  126. * @see hook_aggregator_parse()
  127. *
  128. * @ingroup aggregator
  129. */
  130. function hook_aggregator_parse_info() {
  131. return array(
  132. 'title' => t('Default parser'),
  133. 'description' => t('Default parser for RSS, Atom and RDF feeds.'),
  134. );
  135. }
  136. /**
  137. * Create a processor for aggregator.module.
  138. *
  139. * A processor acts on parsed feed data. Active processors are called at the
  140. * third and last of the aggregation stages: first, data is downloaded by the
  141. * active fetcher; second, it is converted to a common format by the active
  142. * parser; and finally, it is passed to all active processors that manipulate or
  143. * store the data.
  144. *
  145. * Modules that define this hook can be activated as a processor within the
  146. * configuration page.
  147. *
  148. * @param $feed
  149. * A feed object representing the resource to be processed. $feed->items
  150. * contains an array of feed items downloaded and parsed at the parsing stage.
  151. * See hook_aggregator_parse() for the basic format of a single item in the
  152. * $feed->items array. For the exact format refer to the particular parser in
  153. * use.
  154. *
  155. * @see hook_aggregator_process_info()
  156. * @see hook_aggregator_fetch()
  157. * @see hook_aggregator_parse()
  158. *
  159. * @ingroup aggregator
  160. */
  161. function hook_aggregator_process($feed) {
  162. foreach ($feed->items as $item) {
  163. mymodule_save($item);
  164. }
  165. }
  166. /**
  167. * Specify the title and short description of your processor.
  168. *
  169. * The title and the description provided are shown within the configuration
  170. * page. Use as title the natural name of the processor and as description a
  171. * brief (40 to 80 characters) explanation of the functionality.
  172. *
  173. * This hook is only called if your module implements hook_aggregator_process().
  174. * If this hook is not implemented aggregator will use your module's file name
  175. * as title and there will be no description.
  176. *
  177. * @return
  178. * An associative array defining a title and a description string.
  179. *
  180. * @see hook_aggregator_process()
  181. *
  182. * @ingroup aggregator
  183. */
  184. function hook_aggregator_process_info($feed) {
  185. return array(
  186. 'title' => t('Default processor'),
  187. 'description' => t('Creates lightweight records of feed items.'),
  188. );
  189. }
  190. /**
  191. * Remove stored feed data.
  192. *
  193. * Aggregator calls this hook if either a feed is deleted or a user clicks on
  194. * "remove items".
  195. *
  196. * If your module stores feed items for example on hook_aggregator_process() it
  197. * is recommended to implement this hook and to remove data related to $feed
  198. * when called.
  199. *
  200. * @param $feed
  201. * The $feed object whose items are being removed.
  202. *
  203. * @ingroup aggregator
  204. */
  205. function hook_aggregator_remove($feed) {
  206. mymodule_remove_items($feed->fid);
  207. }
  208. /**
  209. * @} End of "addtogroup hooks".
  210. */