Index: bio.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/bio/bio.module,v
retrieving revision 1.2.2.18
diff -u -p -r1.2.2.18 bio.module
--- bio.module	18 Jan 2008 06:02:16 -0000	1.2.2.18
+++ bio.module	23 Jan 2008 08:52:55 -0000
@@ -1,28 +1,39 @@
 <?php
 // $Id: bio.module,v 1.2.2.18 2008/01/18 06:02:16 webchick Exp $
 
+/**
+ * @file
+ * Bio module optionally creates a "Biography" node per user.
+ * 
+ * Use cases for this module include:
+ * - Add a Biography for each of your employees.
+ * - Make user profiles into nodes, for extra functionality.
+ * - Add CCK fields to the user registration form.
+ */
+
 // Panels integration.
 if (module_exists('panels')) {
   include_once drupal_get_path('module', 'bio') .'/bio_panels.inc';
 }
 
-/** 
- * Implementation of hook_init()
+/**
+ * Implementation of hook_init().
  */
 function bio_init() {
-  if ($_GET['q'] == 'node/add/'.variable_get('bio_nodetype', 'bio')) {
+  if ($_GET['q'] == 'node/add/'. variable_get('bio_nodetype', 'bio')) {
     if (($nid = bio_for_user()) && !user_access('administer nodes')) {
-      drupal_goto('node/'.$nid.'/edit');
+      drupal_goto('node/'. $nid .'/edit');
     }
   }
 }
 
 /** 
- * Implementation of hook_menu() 
+ * Implementation of hook_menu().
  */
 function bio_menu($may_cache) {
   global $user;
   $items = array();
+
   if ($may_cache) {
     $items[] = array(
       'path'  => 'admin/user/bio',
@@ -34,9 +45,10 @@ function bio_menu($may_cache) {
   }
   else {
     if (variable_get('bio_profile', 0) && (arg(0) == 'user') && (is_numeric(arg(1)))) {
-      $type = variable_get('bio_nodetype','bio');
+      $type = variable_get('bio_nodetype', 'bio');
       $nid  = bio_for_user(arg(1));
-      // user has a bio
+
+      // Determine access based on whether user has a bio.
       if ($nid) {
         $node = node_load($nid);
         $access = node_access('update', $node);
@@ -46,7 +58,7 @@ function bio_menu($may_cache) {
         $access = (($user->uid == arg(1)) && node_access('create', $type)) || user_access('administer nodes');
       }
       $items[] = array(
-        'path'  => 'user/'.arg(1).'/bio',
+        'path'  => 'user/'. arg(1) .'/bio',
         'title' => node_get_types('name', $type),
         'callback' => 'node_page_edit',
         'callback arguments' => array($node),
@@ -55,10 +67,10 @@ function bio_menu($may_cache) {
       );
     }
     elseif (variable_get('bio_profile', 0) && (arg(0) == 'node') && is_numeric(arg(1)) && !arg(2)) {
-      // if we're about to visit a bio node page, but we've got "use bios for profiles" selected,
-      // redirect to the user page
+      // If we're about to visit a bio node page, but we've got "use bios for profiles" selected,
+      // redirect to the user page.
       $node = node_load(arg(1));
-      if (user_access('access user profiles') && $node->type == variable_get('bio_nodetype','bio')) {
+      if (user_access('access user profiles') && $node->type == variable_get('bio_nodetype', 'bio')) {
         drupal_goto('user/'. $node->uid);
       }
     }
@@ -67,12 +79,10 @@ function bio_menu($may_cache) {
 }
 
 /**
- * Implementation of hook_form_alter
- * 
- * Handle the 
+ * Implementation of hook_form_alter().
  */
 function bio_form_alter($form_id, &$form) {
-  if ($form_id == variable_get('bio_nodetype', 'bio') ."_node_form" && arg(0) == 'user') {
+  if ($form_id == variable_get('bio_nodetype', 'bio') .'_node_form' && arg(0) == 'user') {
     // we're editing the bio in the user area... be sure we end up here when we finish submission
     $account = user_load(array('uid' => arg(1)));
     $form['#redirect'] = 'user/'. $account->uid;
@@ -81,7 +91,7 @@ function bio_form_alter($form_id, &$form
       $form['author']['name']['#value'] = $account->name;
       $form['author']['name']['#disabled'] = 'disabled';
       unset($form['author']['name']['#autocomplete_path']);
-      $form['author']['name']['#description'] = t(' This field is disabled. You cannot alter the author of this entry from within the user area.');
+      $form['author']['name']['#description'] = t('This field is disabled. You cannot alter the author of this entry from within the user area.');
     }
   }
 
@@ -171,11 +181,15 @@ function bio_user_reg_submit($form_id, $
   }
 }
 
+/**
+ * Implementation of hook_profile_alter().
+ */
 function bio_profile_alter(&$account, &$fields) {
+  // Replace user profile with user bio.
   if (variable_get('bio_profile_takeover', 0) && $bio = bio_for_user($account->uid)) {
     $bio = node_load($bio);
     $typename = node_get_types('name', variable_get('bio_nodetype', 'bio'));
-    foreach($fields as $key => $val) {
+    foreach ($fields as $key => $val) {
       if ($key != $typename) {
         unset($fields[$key]);
       }
@@ -185,87 +199,90 @@ function bio_profile_alter(&$account, &$
 }
 
 /** 
- * Implementation of hook_node_info()
- * 
- * - create default "Biography" node type
+ * Implementation of hook_node_info().
  */
 function bio_node_info() {
-  // The default bio node type is simple so we'll just use node as the base.
   if (variable_get('bio_nodetype', 'bio') == 'bio') {
-    return array('bio' => array(
-      'name' => t('Biography'),
-      'module' => 'node',
-      'has_title' => TRUE,
-      'has_body' => TRUE,
-      'custom' => TRUE,
-      'modified' => TRUE,
-      'locked' => FALSE,
-    ));
+    // Create a default bio type that's as simple as possible.
+    return array(
+      'bio' => array(
+        'name' => t('Biography'),
+        'module' => 'node',
+        'has_title' => TRUE,
+        'has_body' => TRUE,
+        'custom' => TRUE,
+        'modified' => TRUE,
+        'locked' => FALSE,
+      ),
+    );
   }
 }
 
 /** 
- * Implementation of hook_nodeapi()
- * 
- * - validate biography node form to make sure that the user doesn't already
- * have one
+ * Implementation of hook_nodeapi().
  */
 function bio_nodeapi(&$node, $op, $a3 = NULL, $a4 = NULL) { 
   if ($node->type != variable_get('bio_nodetype', 'bio')) return;
 
   switch ($op) {
     case 'validate':
-      // This user already has a bio node and this isn't it
+      // Ensure this user doesn't already have a bio node.
       $account = user_load(array('name' => $node->name));
       $nid = bio_for_user($account->uid);
       if ($nid && ($nid != $node->nid)) {
-        form_set_error('name', t('This user already has a @bio. Edit it <a href="@link">here</a> or assign this entry to another user.', array('@bio' => node_get_types('name', $node), '@link' => url('node/'.$nid.'/edit'))));
+        form_set_error('name', t('This user already has a @bio. Edit it <a href="@link">here</a> or assign this entry to another user.', array('@bio' => node_get_types('name', $node), '@link' => url('node/'. $nid .'/edit'))));
       } 
       break;
   }
 }
 
 /** 
- * Implentation hook_user()
- * 
- * - add bio to main user profile page
+ * Implementation hook_user().
  */
-function bio_user($op, &$edit, &$user, $category = NULL) {
+function bio_user($op, &$edit, &$account, $category = NULL) {
   if (!variable_get('bio_profile', 0)) return;
 
   switch ($op) {
     case 'view':
-      if (!$nid = bio_for_user($user->uid)) return;
+      // Add bio to main user profile page.
+      if (!$nid = bio_for_user($account->uid)) return;
       if (!node_access('view', $node = node_load($nid))) return;
       return array(node_get_types('name', variable_get('bio_nodetype', 'bio')) => array('bio' => array('value' => node_view($node, FALSE, TRUE, FALSE))));
   }
 }
 
 /**
- * Implementation of hook_link()
- * 
- * Add "View *username*'s biography" link to node
+ * Implementation of hook_link().
  */
 function bio_link($type, $node = NULL, $teaser = FALSE) { 
   if ($type == 'node' && $node->type != variable_get('bio_nodetype', 'bio')) {
+    // Add "View *username*'s biography" link to nodes.
     $bio_link = variable_get('bio_link', array($node->type => 1));
     if ($bio_link[$node->type] && ($nid = bio_for_user($node->uid))) {
-      $user = user_load(array('uid' => $node->uid));
-      return array('bio' => array(
-        'title' => t('by @user', array('@user' => $user->name)),
-        'href'  => 'node/'.$nid, 
-        'attributes' => array('title' => t('View @user\'s @bio.', array('@user' => $user->name, '@bio' => node_get_types('name', variable_get('bio_nodetype', 'bio')))))));
+      $account = user_load(array('uid' => $node->uid));
+      return array(
+        'bio' => array(
+          'title' => t('by @user', array('@user' => $account->name)),
+          'href'  => 'node/'. $nid,
+          'attributes' => array(
+            'title' => t('View @user\'s @bio.', array('@user' => $account->name, '@bio' => node_get_types('name', variable_get('bio_nodetype', 'bio')))),
+          ),
+        ),
+      );
     }
   } 
 }
 
 /**
- * Return node id of the bio for a given user
+ * Find bio for given user.
  * 
- * FALSE if user has no bio node
+ * @param $uid
+ *   User ID.
+ * @return
+ *   Node ID of bio, or FALSE if no bio node was found.
  */
-function bio_for_user($uid = NULL){
-  if (is_null($uid)){
+function bio_for_user($uid = NULL) {
+  if (is_null($uid)) {
     global $user;
     $uid = $user->uid;
   }
@@ -273,33 +290,32 @@ function bio_for_user($uid = NULL){
 }
 
 /**
- * Callback function for settings page
- * 
- * Settings for
- * - bio node type
- * - node types on which to display links
- * - use bio for profile
+ * Menu callback; administration settings page.
  */
 function bio_settings() {
+  // Bio node type.
   $types = array();
-  foreach(node_get_types() as $key => $type) {
+  foreach (node_get_types() as $key => $type) {
     $types[$key] = $type->name;
   }
-  $form = array();
   $form['bio_nodetype'] = array(
     '#type' => 'select',
     '#title' => t('Content type for user biographies'),
-    '#description' => t('The content type for user biographies.  Each user may create only one node of this type'),
+    '#description' => t('The content type for user biographies. Each user may create only one node of this type'),
     '#options' => $types,
     '#default_value' => variable_get('bio_nodetype', 'bio'),
   );
+
+  // Link to author's bio.
   $form['bio_link'] = array(
     '#type' => 'checkboxes',
     '#title' => t('Display bio link'),
-    '#description' => t('Display a link to author\'s bio if it is available.'),
+    '#description' => t("Display a link to author's bio if it is available."),
     '#options' => $types,
     '#default_value' => variable_get('bio_link', $types),
   );
+
+  // Bio profile options.
   $form['bio_profile'] = array(
     '#type' => 'checkbox',
     '#title' => t('Use bio for user profiles'),
@@ -313,7 +329,7 @@ function bio_settings() {
     '#default_value' => variable_get('bio_profile_takeover', 0),
   );
 
-  // Add option to show fields on the registration form.
+  // Show fields on the registration form.
   if (module_exists('content')) {
     $form['bio_regstration_form'] = array(
       '#type' => 'radios',
@@ -347,14 +363,15 @@ function bio_settings() {
     );
   }
 
+  // Strange hack for invalidating Views cache.
   $add_a_submit = system_settings_form($form);
   $add_a_submit['#validate']['bio_settings_validate_xxx'] = array();
   return $add_a_submit;
 }
 
 /**
- * Theme function for bio registration form options that adds a disabled flag to
- * required fields.
+ * Theme function for bio registration form options that adds a disabled flag
+ * to required fields.
  * 
  * @ingroup themeable
  */
@@ -371,11 +388,15 @@ function theme_bio_registration_fields($
   return drupal_render($form);
 }
 
-/*
- * A submit handler for the bio settings page so that we can invalidate the views
- * cache in case the bio node type changed. We need the _xxx suffix to keep it
- * from interfering with the #base in system_settings_form. Also, we do it in the
- * validate phase because submits were interfering with the #base attribute. Yuck.
+/**
+ * Invalidate Views cache when bio settings form is submitted.
+ * 
+ * This is required in case the bio node type has changed. We need the _xxx
+ * suffix to keep it from interfering with the #base in system_settings_form().
+ * Also, we do it in the validate phase because submits were interfering with
+ * the #base attribute. Yuck.
+ * 
+ * @todo Less hackish way to do this?
  */
 function bio_settings_validate_xxx($form_id, $form_values) {
   if (module_exists('views')) {
@@ -384,7 +405,7 @@ function bio_settings_validate_xxx($form
 }
 
 /**
- * Retrieve field info for bio CCK type.
+ * Retrieve field info for Bio CCK type.
  */
 function _bio_get_fields() {
   $bio_nodetype = variable_get('bio_nodetype', 'bio');
@@ -392,38 +413,51 @@ function _bio_get_fields() {
   return $type['fields'];
 }
 
+/*
+ * Views integration for Bio module.
+ * 
+ * Bio module's Views integration works by cloning many features of Views
+ * module's existing node integration. To avoid a large amount of code being
+ * loaded on every page, these functions therefore merely call private
+ * functions in bio_views.inc.
+ */
+
 /**
- * implementation of hook_views_table_alter()
- *
- * bio uses hook_views_table_alter to clone all the existing fields and handlers
- * and repurpose them as bio related searching. Since this doesn't need to occur on
- * every page load, we call into the bio_views.inc file for the heavy lifting.
+ * Implementation of hook_views_table_alter().
+ * 
+ * @see _bio_views_tables_alter()
  */
 function bio_views_tables_alter(&$tables) {
-  require_once drupal_get_path('module', 'bio') . '/bio_views.inc';
+  require_once drupal_get_path('module', 'bio') .'/bio_views.inc';
   return _bio_views_tables_alter($tables);
 }
 
-/*
+/**
  * Copy of views_handler_filter_isnew($op, $filter, $filterinfo, &$query)
- * As written this function has some very specific needs w.r.t. tables that
- * join against node. I couldn't make the views version generic, so I copied it
- * here. It lives in the .inc to avoid unecessary script bloat.
+ * 
+ * @see _bio_handler_filter_isnew()
  */
 function bio_handler_filter_isnew($op, $filter, $filterinfo, &$query) {
-  require_once drupal_get_path('module', 'bio') . '/bio_views.inc';
+  require_once drupal_get_path('module', 'bio') .'/bio_views.inc';
   return _bio_handler_filter_isnew($op, $filter, $filterinfo, $query);
 }
 
 /**
- * Implementation of hook_views_query_alter()
+ * Implementation of hook_views_query_alter().
+ * 
+ * @see _bio_views_query_alter()
  */
 function bio_views_query_alter(&$query, $view, $summary, $level) {
-  require_once drupal_get_path('module', 'bio') . '/bio_views.inc';
+  require_once drupal_get_path('module', 'bio') .'/bio_views.inc';
   return _bio_views_query_alter($query, $view, $summary, $level);
 }
 
+/**
+ * Implementation of hook_views_default_views().
+ * 
+ * @see _bio_views_default_views()
+ */
 function bio_views_default_views() {
-  require_once drupal_get_path('module', 'bio') . '/bio_views.inc';
+  require_once drupal_get_path('module', 'bio') .'/bio_views.inc';
   return _bio_views_default_views();
 }