Announcements Module API

In order to make it easier to display announcements in Drupal components, such as blocks, we offer a few shortcuts for users with PHP experience.

The functions below were designed to streamline common tasks like fetching the most announcements and/or ones from a specific category. They also support more advanced customization that can control options like sorting.

Examples

Available functions:

• announcement_get ($interval = '', $order = '', $limit = '');
• announcement_get_by_category ($cat, $interval = '', $order = '', $limit = '');

Common behaviors among all functions:

• If $interval is left empty, no interval will be assumed.
• If $order is left empty, the following MySQL ORDER BY option is used: "`revision_id` DESC, `publish_date` DESC". This will place the most recent announcements at the top.
  • Columns which can be used in your $order option:
    • `revision_id`
    • `node_id`
    • `publish_date`
    • `expire_date`
    • `sticky` (Whether the node is "promoted to the front".)
• If $limit is left empty, all announcements will be returned. Therefore we suggest always choosing a limit.
• Fields available in the results:
  • `revision_id`
  • `node_id`
  • `title`
  • `body`
  • `teaser`
  • `changed` (UNIX timestamp)
  • `created` (UNIX timestamp)
  • `uid` (user ID)

announcement_get ($interval, $order = '', $limit = '');

General Purpose

• Parameters:
  • string $interval: How far back should we search? You can use natural intervals like '1 month', '2 weeks', '16 hours', etc. See PHP documentation for strtotime() for compatible intervals.
  • string $order: In what order should the announcements be collected? You will need to express this in MySQL, e.g. '`publish_date` DESC' or '`publish_date` DESC, `sticky` DESC'.
  • int $limit: How many announcements should we collect?
• Returns: Query result resource, e.g. the same as db_query().
• Examples

announcement_get_by_category ($cat, $interval = '', $order = '', $limit = '');

Filter By Category

• Parameters:
  • int $cat: The ID number of the category.
  • string $interval: How far back should we search? You can use natural intervals like '1 month', '2 weeks', '16 hours', etc. See PHP documentation for strtotime() for compatible intervals.
  • string $order: In what order should the announcements be collected? You will need to express this in MySQL, e.g. '`publish_date` DESC' or '`publish_date` DESC, `sticky` DESC'.
  • int $limit: How many announcements should we collect?
• Returns: Query result resource, e.g. the same as db_query().
• Examples

Examples

• announcement_get
  • 10 most recent announcements from the last month
    • announcement_get('1 month', '', 10);
  • 10 most recent announcements since the beginning of time
    • announcement_get('', '', 10);
  • All announcements, most recent first, since the beginning of time
    • announcement_get();
  • 10 most recent announcements from the last 6 weeks, and with promoted ones closer to the top
    • announcement_get('6 weeks', '`sticky` DESC, `revision_id` DESC, `publish_date` DESC', 10);
• announcement_get_by_category: All of the examples for announcement_get() are also valid for this function, except that you must choose a category ID for the first parameter.