modules/announcements/announcements.module

<?php
// $Id: announcements.module,v 1.9 2008/05/09 01:15:02 nancyw Exp $

/**
 * Module used to present Announcements
 * (C) Copyright IBM Corp. 2005-2006
 * 
 * @file
 * Enables the creation of announcement pages with a title, abstract, body, author and date.
 * @link http://www-128.ibm.com/developerworks/ibm/library/i-osource6/ Original module source @endlink
 */

/**
 * Implementation of hook_help().
 *
 * This function allows the announcement module to make documentation available 
 * to the Drupal interface.
 *
 * @param $section
 *   This determines which part of the interface is requesting help content.
 *   Here we return content for the module description under the administration
 *   interface, 'admin/modules#description', and at the top of the form to add a
 *   new announcement, node/add#announcements.
 * @return
 *   A string containing the help content.
 *
 * More detail at @link http://api.drupal.org/api/HEAD/function/hook_help API page @endlink .
 */
function announcements_help($section) {
  switch ($section) {
    case 'admin/modules#description':
      return t('Enables the creation of announcement pages that are presented on the home page.');

    case 'node/add#announcements':
      return t('An announcement is anything worthy of special note on the site. It may be displayed in a block or page, or both.');

    case 'announcements/view':
    case 'announcements':
      $links = array();
      if (user_access('create announcement')) {
        $links[] = l(t('Add a new announcement'), 'node/add/announcements');
      }
      if (user_access('administer site configuration')) {
        $links[] = l(t('Announcement settings'), 'admin/settings/announcements', array(), drupal_get_destination());
      }

      return '<div class="announcement-links">'.
        implode(' | ', $links)
        .'</div><div class="clear-block"></div>';
  }
}

/**
 * Implementation of hook_perm().
 *
 * This function supplies the permissions that the announcement module defines.
 * These can then be selected on the Drupal user permissions administration page
 * and used to restrict access to actions the announcement module performs.
 *
 * @return
 *   An array of strings used to identify permissible actions.
 *
 * More detail at @link http://api.drupal.org/api/HEAD/function/hook_perm API page @endlink .
 */
function announcements_perm() {
  return array('create announcement', 'edit announcement');
}

/**
 * Implementation of hook_node_info().
 *
 * This function is required for modules to define one or more node types. It 
 * allows Drupal to determine the names and the attributes of the announcement
 * module node type.
 *
 * @return
 *   An array of information on the module's node types. The minimum required
 *   information that needs to be returned is the modules human readable name, 
 *   the Drupal module name used to build hook function names and short description
 *   of the node type.
 *
 * More detail at @link http://api.drupal.org/api/HEAD/function/hook_node_info API page @endlink .
 */
function announcements_node_info() {
  return array('announcements' => array(
    'name' => 'Announcements', 
    'description' => t('An announcement is anything worthy of special note on the site. It may be displayed in a block or page, or both.'),
    'module' => 'announcements'));
}

/**
 * Implementation of hook_access().
 *
 * This function allows the announcement module to limit access to the node type 
 * it defines depending on the operation currently being performed and the 
 * permissions defined in the Drupal user permissions administration page.
 *
 * @param $op
 *   The Drupal operation currently being performed. Here we want to control access
 *   for the create, view, update and delete operations.
 * @param $node
 *   The node object on which this operation is being performed.
 * @return
 *   A boolean value depending on whether the operation can be performed or not.
 *
 * More detail at @link http://api.drupal.org/api/HEAD/function/hook_access API page @endlink .
 */
function announcements_access($op, $node) {
  global $user;
  
  switch ($op) {
    case 'create':
      return user_access('create announcement');

    case 'view':
      return user_access('access content');

    case 'update':
    case 'delete':
      // 'Edit own' is by default.
      if ($user->uid == $node->uid || user_access('edit announcement')) {
        return true;
      }
      else {
        return false;
      }

    default:
      return false;
  }
}

/**
 * Implementation of hook_menu().
 *
 * This function allows the announcement module to register URL paths and 
 * determine how these requests are to be handled. Depending on the 
 * registration a link may be placed in a menu or as a tab at the top of
 * the page.
 *
 * NOTE: For version 5.*, you need to register the URL path, 
 *  admin/settings/announcement, to map to a callback function to create
 * a form to manipulate its settings.
 *
 * @param $may_cache
 *   This is a boolean used to determine if a registered URL path should
 *   be cached or not. Usually, those URL path that include some dynamic
 *   value should not be cached.
 * @return
 *   An array of registered URL path objects. These contain at least the
 *   registered URL path, a string of text used as a title for these paths,
 *   an access flag built by testing the access list, a type to determine
 *   how this registration be used, and the name of the callback function
 *   that should be called when this URL path is requested.
 *
 * More detail at @link http://api.drupal.org/api/HEAD/function/hook_menu API page @endlink .
 */
function announcements_menu($may_cache) {
  $items = array();
  
  if ($may_cache) {
    $items[] = array(
      'path' => 'node/add/announcements',
      'title' => t('Announcement'),
      'access' => user_access('create announcement'),
      );

    $items[] = array(
      'path' => 'admin/settings/announcements',
      'title' => t('Announcement settings'), 
      'access' => user_access('administer site configuration'),
      'type' => MENU_NORMAL_ITEM,
      'callback arguments' => array('announcements_settings'),
      'callback' => 'drupal_get_form',
      );

    $items[] = array(
      'path' => 'announcements',
      'title' => t('Announcements'),
      'access' => user_access('access content'),
      'callback' => 'announcements_all',
      ); 
  }
  else {
    drupal_add_css(drupal_get_path('module', 'announcements') .'/announcements.css');
    
    $items[] = array(
      'path' => 'announcements/pager',
      'title' => t('Announcements Pager Example'),
      'access' => user_access('administer site'),
      'type' => MENU_CALLBACK,
      'callback' => 'announcements_pager',
      );
  }

  return $items;
}

/**
 *
 * This function builds a themed set of links, known as the pager, to each
 * page of a paginated list of announcements. This is usually placed at the 
 * bottom of each of these paginated pages.
 *
 * @return
 *   A string of XHTML used to render the pager.
 */
function announcements_pager() {
  $result = pager_query(db_rewrite_sql("SELECT n.nid, n.created FROM {node} n WHERE type = 'announcement' ORDER BY n.created DESC"), variable_get('default_nodes_main', 10));
  while ($announcement = db_fetch_object($result)) {
    $output .= node_view(node_load($announcement->nid), 1);
  }
    
  $output .= theme('pager', NULL, variable_get('default_nodes_main', 10));
    
  return $output;
}

/**
 * Implementation of hook_cron().
 *
 * This function allows the announcement module to insert its own actions when
 * the cron.php script is run  usually by the system cron system. This is useful
 * when performing periodic asynchronous tasks like, as in this case, checking to
 * see if any announcements have expired.
 *
 * @return
 *   Nothing.
 *
 * More detail at @link http://api.drupal.org/api/HEAD/function/hook_cron API page @endlink .
 */
function announcements_cron() {

  // Mark expired announcements as unpublished so that non-administrative 
  // users cannot see them on the site through standard node mechanisms.
  $query_result = db_query("UPDATE {node} AS n INNER JOIN {announcements} AS a ON n.nid = a.nid SET n.status = 0 WHERE n.type='announcements' AND n.status = 1 AND a.expiration_date < %d", time());
}

/**
 * Implementation of hook_link().
 *
 * This function allows the announcement module to insert its own links
 * into certain parts of Drupal generated content. In this case add, edit
 * and delete links are added to Drupal rendered announcements depending
 * on the access permissions of the current user.
 *
 * @param $type
 *   A string identifying the type of link being requested. In this case,
 *   the links placed below an announcement node.
 * @param $node
 *   The node object currently being requested.
 * @param $teaser
 *   A boolean indicating if the full announcement is being displayed or
 *   just its teaser.
 * @return
 *   An array of link objects as created by the l() function.
 *
 * More detail at @link http://api.drupal.org/api/HEAD/function/hook_link API page @endlink .
 */
/* function announcements_link($type, $node = NULL, $teaser = FALSE) {
  global $user;  
  $links = array();
  
  if ($type == 'node' && $node->type == 'announcement') {
    if (node_access('create', 'announcement')) {      
      $links[t('Add')] = array(
      'href' => 'node/add/announcement',
      'title' => t('Add a new announcement'),
      );
    }

    if (node_access('update', $node)) {
      $links[t('Edit')] = array(
        'href' => "announcements/$node->nid/edit",
        'title' => t('Edit Announcement ') . $node->title,
        );

      $links[t('Delete')] = array(
        'href' => "announcements/$node->nid/delete",
        'title' => t('Delete Announcement ') . $node->title,
        );
    }
  }

  return $links;
} */

/**
 * Implementation of hook_settings().
 *
 * This function provides an administrative interface for controlling 
 * various settings for the announcement module.
 *
 * NOTE: This hook is not used in Drupal v5 - converted to regular form.
 * (@link http://drupal.org/node/64279#hook-settings http://drupal.org/node/64279#hook-settings @endlink .)
 *
 * @return
 *   An array description, in the Drupal Forms API format, of the elements
 *   to render the settings interface.
 *
 * More detail at @link http://api.drupal.org/api/4.7/function/hook_settings API page @endlink .
 */
function announcements_settings() {
  $form = array();
  $form['announcements_block_max_list_count'] = array(
    '#type' => 'textfield',
    '#title' => t('Maximum number of block announcements'),
    '#default_value' => variable_get('announcements_block_max_list_count', 3),
    '#description' => t('The maximum number of items listed in the announcement block'),
    '#required' => FALSE, 
    '#size' => 6,
    );

  $form['announcements_display_classification'] = array(
    '#type' => 'checkbox',
    '#title' => t('Display additional announcement classification'),
    '#default_value' => variable_get('announcements_display_classification', true),
    '#description' => t('Insert the additional classification in the announcement modules'),
    '#required' => FALSE, 
    );

  $form['announcements_body_required'] = array(
    '#type' => 'checkbox',
    '#title' => t('Require a body'),
    '#default_value' => variable_get('announcements_body_required', false),
    '#description' => t('In addition to the abstract, do you require a body?'),
    '#required' => FALSE, 
    );

  $intervals = array(
    '+1 day' => '1 day', 
    '+1 week' => '1 week',
    '+2 week' => '2 weeks',
    '+1 month' => '1 month',
    '+2 month' => '2 months',
    '+3 month' => '3 months',
    '+6 month' => '6 months',
    '+1 year' => '1 year',
    );
  $form['announcements_interval'] = array(
    '#type' => 'radios',
    '#options' => $intervals,
    '#title' => t('Default duration of announcement'),
    '#default_value' => variable_get('announcements_interval', '+1 month'),
    '#description' => t('This will be added to the current date to set the default ending date.'),
    '#required' => FALSE, 
    '#prefix' => '<div class="announcements-radios">',
    '#suffix' => '</div><div class="clear-block"></div>',
    );

  return system_settings_form($form); 
}

/**
 * This function is called to retrieve the form that is displayed when one attempts 
 * to "create" an announcement.
 */
function announcements_form(&$node) {
  $type = node_get_types('type', $node);

  if ($node->expiration_date == NULL) {
    $node->expiration_date = strtotime(variable_get('announcements_interval', '+1 month'));
  }

  if ($node->publish_date == NULL) {
    $node->publish_date = time();
  }
  
  $form = node_content_form($node);
//  $form['title'] = array('#type' => 'textfield',
//    '#title' => t('Title'),
//    '#default_value' => $node->title,
//    '#description' => t('Title of the announcement'),
//    '#required' => TRUE, 
//    '#weight' => -5
//  );
  $form['body_filter']['body']['#description'] = t('The full text of the announcement.');
  $form['body_filter']['body']['#required'] = variable_get('announcements_body_required', false);

  $form['publication'] = array('#type' => 'fieldset',
    '#collapsible' => false,
    '#title' => t('Publication dates'),
    '#weight' => -4 
  );

  $form['publication']['publish_date'] = array(
    '#type' => 'date',
    '#title' => t('Publication date'),
    '#required' => true,
    '#default_value' => _announcements_unixtime2drupaldate($node->publish_date),
    '#prefix' => '<div class="date_widget">',
    '#suffix' => '</div>',
  );

  $form['publication']['expiration_date'] = array(
    '#type' => 'date',
    '#title' => t('Expiration date'),
    '#required' => true,
    '#default_value' => _announcements_unixtime2drupaldate($node->expiration_date),
    '#prefix' => '<div class="date_widget">',
    '#suffix' => '</div>',    
  );
  
  $form['abstract'] = array('#type' => 'textarea',
    '#title' => t('Abstract'),
    '#default_value' => $node->abstract,
    '#rows' => 3,
    '#description' => t('Short summary of the announcement'),
    '#required' => true,
    '#weight' => -3,
  );
  
//  $form['body_field'] = node_body_field($node, $type->body_label, $type->min_word_count);
  
  return $form;
}

/**
 * Implementation of hook_validate()
 * This just checks to ensure that the expiration date is after the publish date. 
 * No node attributes are set.
 */
function announcements_validate($node) {
    if ($node) {
      $publish_date = _announcements_drupaldate2unixtime($node->publish_date);
      $expiration_date = _announcements_drupaldate2unixtime($node->expiration_date);
      if ($publish_date >= $expiration_date) {
        form_set_error('publish_date', t('The publish date of an announcement must be before its expiration date.'));
      }
    }
} 

/**
 * Implementation of hook_submit()
 * Prepare the node for submission into the database. 
 * Update the date values to integer values
 */
function announcements_submit(&$node) {
  $node->publish_date = _announcements_drupaldate2unixtime($node->publish_date);
  $node->expiration_date = _announcements_drupaldate2unixtime($node->expiration_date);
  
  $now = time();
  if ($now > $node->publish_date && $now < $node->expiration_date) {
    $node->status = 1;
  }
  else {
    $node->status = 0;
  }
}

/**
 * Only show those announcements that have not expired for the average user.
 * If they have access to edit, show all announcements.
 */
function announcements_all($option = null) {
  $output = '<div class="announcements">';
  if (user_access('edit announcement')) {
    $query_result = db_query("SELECT n.nid FROM {node} n INNER JOIN {announcements} a ON n.nid = a.nid " .
      "WHERE n.type='announcements' ORDER BY n.sticky DESC, a.publish_date DESC");               
  }
  else {
    $query_result = db_query("SELECT n.nid FROM {node} n INNER JOIN {announcements} a ON n.nid = a.nid " .
      "WHERE n.type='announcements' AND a.expiration_date > %d ORDER BY n.sticky DESC, a.publish_date DESC", date("U"));
  }
  
  $page_content = array();
  while ($nid = db_fetch_object($query_result)) {
    $announcement = node_load($nid->nid);
    $announcement->url = url('announcements/'. $announcement->nid);
    if ($option == 'view') {
      $output .= theme('announcements', $announcement);
    }
    else {
      $output .= theme('announcements_compact', $announcement);
    }
  }

  $output .= '</div>';
  return $output;
}

/**
 * Database hooks when loading, inserting, updating or deleting an announcement
 */
 
/**
 * Implementation of hook_view()
 * This function is called to allow the module a chance to format extra information to display.
 */
function announcements_view($node, $teaser = false, $page = false) {
  $node = node_prepare($node, $teaser);
  $node->content['dates'] = array(
    '#value' => theme('announcements_dates', $node),
    '#weight' => -4,
    );
  $node->content['abstract'] = array(
    '#value' => theme('announcements_abstract', $node),
    '#weight' => -2,
    );
  return $node;
}
 
/**
 * Implementation of hook_load()
 * This function is called to allow the module a chance to load extra information that 
 * it stores about an announcement.
 */
function announcements_load($node) {
  $additions = db_fetch_object(db_query('SELECT * FROM {announcements} WHERE nid = %d', $node->nid));
  return $additions;
}

/**
 * Implementation of hook_insert()
 * This function is called to allow the module to take action when a new node is 
 * being inserted in the database.
 */
function announcements_insert($node) {
  db_query("INSERT INTO {announcements} (nid, abstract, publish_date, expiration_date) VALUES (%d, '%s', '%d', '%d')", $node->nid, $node->abstract, $node->publish_date, $node->expiration_date);
} 

/**
 * Implementation of hook_update()
 * As an existing node is being updated in the database, we need to do our own 
 * database updates, i.e., put info into announcement table.
 */
function announcements_update($node) {
  db_query("UPDATE {announcements} SET abstract='%s', publish_date = '%s', expiration_date = '%s' WHERE nid = %d", $node->abstract, $node->publish_date, $node->expiration_date, $node->nid);
} 

/**
 * Implementation of hook_delete()
 * This function is called to allow the module to take action when a node is 
 * being deleted from the database.
 */
function announcements_delete($node) {
  db_query('DELETE FROM {announcements} WHERE nid = %d', $node->nid);
}

/**
 * Implementation of hook_block().
 */
function announcements_block($op = 'list', $delta = 0, $edit = array()) {
  global $user;
  $vids = _announcements_get_vocabularies();
  if ($op == 'list') {
    $blocks[0]['info'] = t('Announcements: Recent');
    if ($vids) {
      foreach ($vids as $vid => $name) {
        $blocks[$vid]['info'] = t('Announcements: In !name vocabulary', array('!name' => $name));
      }
    }
    return $blocks;
  }
  else if ($op == 'view')  {
    $block  = array();
    //$output  = '';

    switch ($delta) {
      case 0:
        $announcement_items  = array();
        
        if (user_access('access content')) {
          $now = time();
          $qargs = array($now, $now);

          $q = 'SELECT n.nid FROM {node} n JOIN {announcements} a USING(nid) '.
            "WHERE n.type='announcements' AND n.status=1 ".
            'AND a.publish_date < %d AND a.expiration_date > %d ORDER BY a.publish_date ASC ';
 
          $result = db_query_range($q, $qargs, 0, variable_get('announcement_block_max_list_count', 3));
          while ($announcement = db_fetch_object($result)) {
            $announcement_items[] = node_load($announcement->nid);      
          }
        }
        if ($announcement_items) {
//          $block['subject'] = t('Announcements');
          $block['content'] = theme('announcements_block_list', $announcement_items);
        }
        break;

      case 1:
        if (user_access("access content")) {
          $vocabulary = taxonomy_get_vocabulary($delta);
          $block['subject']= $vocabulary->name;
          $block['content']= announcements_vocab_vert($vocabulary->vid);
        }
    }
    return $block;
  }
}

/** 
 * Adapated from the taxonomy_dhtml module.
 */
function announcements_vocab_vert($vocabulary_id, $op = NULL) {
  $tree = taxonomy_get_tree($vocabulary_id);
  // Build an array which holds all children of current term.
  // Necessary to build a proper 'or' value in the HREF
  foreach ($tree as $term) {
    //$url = "taxonomy/term/$term->tid/9";
    $url = "taxonomy/term/$term->tid";
    if ($op) {
      $url .= "/$op";
    }
    $link = l($term->name, $url, array("title" => $term->description));
    $out .= _taxonomy_depth($term->depth, "&nbsp;") ."- $link";
    $count = taxonomy_term_count_nodes($term->tid);
    if ($count) {
      $out .= " ($count)";
      $out .= _announcements_by_terms($term->tid);
    }
    else {
      $out .= " (0)";
    }
    $out .= "<br />";
  }
  return $out;
}

/**
 * Show all the announcements classified by this term.
 */
function _announcements_by_terms($tid) {
  $result = '';
  $tids   = array( $tid );
  $nodes  = taxonomy_select_nodes($tids, 'or', 0, FALSE);
  while ($r = db_fetch_object($nodes)) {
    $url = "announcements/". $r->nid;
    $result .= "<br/>&nbsp; - &nbsp;" . l($r->title, $url, array("title" => $r->title));
  }
  return $result;
}

/**
 * Implementation of hook_nodeapi().
 * If the operation is update index, we want to add the abstract 
 * of this announcement to the search index.
 */
function announcements_nodeapi(&$node, $op) {
  switch ($op) {
    // Add abstract field from announcement table to the search index
    case 'update index':
      if ($node->type == 'announcements') {
        $text = ''; 
        $q = db_query(
          'SELECT a.abstract FROM {node} n LEFT JOIN {announcements} a ON n.nid = a.nid '.
          'WHERE n.nid = %d', $node->nid);
        if ($r = db_fetch_object($q)) {
          $text = $r->abstract;
        }
        return $text;
      }
  }
}

/*
 * Theme functions
 * 
 * There are two theme functions:
 * 
 *  theme_announcement - Generic theme function that will work for all themes and theme engines
 * 
 *  phptemplate_annoucement - Theme function that will be used by the phptemplate engine 
 */
function theme_announcements($announcement) {
//  return '';
  return node_view($announcement, true, false, variable_get('announcement_display_classification', true));
}

function theme_announcements_dates($announcement) {
  $output = '<div class="announcement-dates">'. t('Starting') .' ';
  $output .= '<span class="announcement-start">'. format_date($announcement->publish_date, 'custom', 'F j, Y') .'</span>';
  $output .= ' - '. t('Ending') .' ';
  $output .= '<span class="announcement-end">'. format_date($announcement->expiration_date, 'custom', 'F j, Y') .'</span>';
  $output .= '</div>';
  return $output;
}

function theme_announcements_compact($announcement) {
//  return '';
  $path = drupal_get_path_alias('node/'. $announcement->nid);
  $output = '<h3>'. l($announcement->title, $path) .'</h3>';
  $output .= theme('announcements_dates', $announcement);
  $output .= theme('announcements_abstract', $announcement);
  return $output;
}

function theme_announcements_block_list($announcement_list) {
//  return '';
  $output = null;
  foreach ($announcement_list as $announcement) {
    $output .= '<h3>'. l($announcement->title, 'node/'. $announcement->nid) .'</h3>';
    $output .= theme('announcements_abstract', $announcement);
  }
  return $output;
}

function theme_announcements_abstract($announcement) {
  return '<div class="announcement-abstract">'. check_markup($announcement->abstract, $announcement->format) .'</div>';
}

//function phptemplate_announcement($announcement) {
//  return _theme_phptemplate_announcement($announcement, 'announcement');
//}

//function phptemplate_announcement_compact($announcement) {
//  return _theme_phptemplate_announcement($announcement, 'announcement_compact');
//}

//function phptemplate_announcement_block_list($announcement_list) {
//  global $user;
//  return _phptemplate_callback('announcement_block_list', array('announcements' => $announcement_list, 'user' => $user));  
//}

function _theme_phptemplate_announcements($announcement, $announcement_template) {
  $expired = FALSE;
  if ($announcement->expiration_date < time()) {
    $expired = TRUE;    
  }
  $variables = array(
    'title' => $announcement->title,
    'body' => $announcement->body,
    'links' => $announcement->links ? theme('links', $announcement->links) : '',
    'abstract' => $announcement->abstract,
    'published' => format_date($announcement->publish_date, 'custom', 'j M, Y'),
    'expires' => format_date($announcement->expiration_date, 'custom', 'j M, Y'),
    'expired' => $expired,
    'node' => $announcement
  );
  return _phptemplate_callback($announcement_template, $variables);  
}
 
function _announcements_drupaldate2unixtime($drupal_date) {
  $year  = $drupal_date["year"];
  $month = $drupal_date["month"];
  $day   = $drupal_date["day"];
  
  // Making the hour 12 helps prevent the date from adjusting due to GMT offset.
  return mktime(12, 0, 0, (int)$month, (int)$day, (int)$year);
}

function _announcements_unixtime2drupaldate($unixtime) {
  return array('day' => date('j', $unixtime),
    'month' => date('n', $unixtime),
    'year' => date('Y', $unixtime));
}

/**
 *  Function to get array of vocabularies that are sey up for the announcements type.
 */
function _announcements_get_vocabularies() {
  $vids = array();
  $result = db_query("SELECT t.vid, v.name FROM {vocabulary_node_types} t JOIN {vocabulary} v USING (vid) WHERE t.type='announcements'");
  while ($voc = db_fetch_object($result)) {
    $vids[$voc->vid] = $voc->name;
  }
  return $vids;
}