Index: user_tags.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/user_tags/user_tags.module,v
retrieving revision 1.14.2.6
diff -u -p -r1.14.2.6 user_tags.module
--- user_tags.module	27 Aug 2007 11:12:57 -0000	1.14.2.6
+++ user_tags.module	5 Oct 2007 13:47:53 -0000
@@ -1,5 +1,5 @@
 <?php
-// $id:$
+// $Id:$
 
 /**
 * Implementation of hook_help().
@@ -12,6 +12,7 @@ function user_tags_help($section) {
   }
 }
 
+
 /**
  * Implementation of hook_perm().
  */
@@ -19,6 +20,7 @@ function user_tags_perm() {
   return array('administer user tags', 'tag users');
 }
 
+
 /**
 * Implementation of hook_menu().
  */
@@ -54,8 +56,9 @@ function user_tags_menu($may_cache) {
   return $items;
 }
 
+
 /**
-* Implementation of hook_settings().
+ * Implementation of hook_settings().
  */
 function user_tags_settings() {
   if ($_POST['user_tags_vocabulary_list']) {
@@ -69,9 +72,6 @@ function user_tags_settings() {
   if (db_affected_rows() > 0) {
     while($vocab_list = db_fetch_object($vocab)) {
       $options[$vocab_list->vid] = $vocab_list->name;
-      if ($vocab_list->description) {
-        $options[$vocab_list->vid] .=" - ". $vocab_list->description;
-      }
     }
     $enabled_vocab = db_query("SELECT vu.vid, v.name FROM {user_tags_vocabulary} vu INNER JOIN {vocabulary} v ON v.vid = vu.vid");
     while($enabled = db_fetch_object($enabled_vocab)) {
@@ -104,39 +104,42 @@ function user_tags_settings() {
   return system_settings_form($form);
 }
 
+
 /**
-* Implementation of hook_user().
+ * Implementation of hook_user().
  */
 function user_tags_user($op, &$edit, &$account, $category = NULL) {
   switch ($op) {
     case 'view':
       return user_tags_view_tags($account);
-    break;
 
     case 'load':
-      return user_tags_load_tags($account);
-    break;
+      user_tags_load_tags($account);
+      break;
 
     case 'form':
       return user_tags_form_tags($category, $account);
-    break;
 
     case 'submit':
-      return user_tags_submit_tags($category, $edit, $account);
-    break;
+      user_tags_submit_tags($category, $edit, $account);
+      break;
 
     case 'categories':
-      return array(array('name' => 'tags', 'title' => t('tags'), 'weight' => 10));
-    break;
+      return array(array('name' => 'tags', 'title' => t('Tags'), 'weight' => 10));
 
     case 'delete':
-      return user_tags_delete_tags($account);
-    break;
+      user_tags_delete_tags($account);
+      break;
   }
 }
 
+
 /**
  * Find all terms associated to the given user, ordered by vocabulary and term weight.
+ *
+ * @param int - $uid : User ID
+ * @param char - $key : Key used for query rewriting - default to 'tid'
+ * @return array - of terms assigned to a user
  */
 function user_tags_get_terms($uid, $key = 'tid') {
   static $terms;
@@ -151,11 +154,12 @@ function user_tags_get_terms($uid, $key 
   return $terms[$uid];
 }
 
+
 /**
  * prints all the vocab in use atm
  *
  * @param char $tid : term id
- * @return page listing off all the users with corresponding term
+ * @return char - page listing off all the users with corresponding term
  */
 function user_tags_page_list() {
   $term = taxonomy_get_term($tid);
@@ -167,7 +171,7 @@ function user_tags_page_list() {
   $vocab_query = (db_query('SELECT DISTINCT(tu.vid) as vid, v.name FROM {term_user} tu INNER JOIN {vocabulary} v  ON tu.vid = v.vid GROUP BY vid'));
   $count_vocab = db_num_rows($vocab_query);
 
-while ($term = db_fetch_object($query)) {
+  while ($term = db_fetch_object($query)) {
     $vocab[$term->vid][$term->tid] = $term->termname;
   }
 
@@ -175,13 +179,18 @@ while ($term = db_fetch_object($query)) 
     foreach ($tid as $term_tid=>$term_name) {
       $rows[] = array(l($term_name, "tag/user/$term_tid"));
     }
-  }return theme('table', array(t('Tags')), $rows);
-
-
-
+  }
+  
+  return theme('table', array(t('Tags')), $rows);
 }
 
 
+/**
+ * Generate a table of users and their tags
+ *
+ * @param int $tid : Term ID
+ * @return char : page listing all users and their tags
+ */
 function user_tags_page_users($tid) {
   $row = array();
   $rows = array();
@@ -209,13 +218,15 @@ function user_tags_page_users($tid) {
     return theme('table', array(t('Name'), t('Tags')), $rows);
   }
 }
+
+
 /**
- * Enter description here...
+ * Get all the terms associated with a user but limited to a specified Vocabulary ID
  *
  * @param int  $uid : user ID
  * @param int  $vid : vocabulary ID
  * @param char $key : term ID
- * @return all the tags belonging to the user with the specified uid
+ * @return array : all the tags belonging to the user with the specified uid
  */
 function user_tags_get_terms_by_vocabulary($uid, $vid, $key = 'tid') {
   $result = db_query('SELECT t.* FROM {term_data} t INNER JOIN {term_user} tu WHERE tu.tid = t.tid AND tu.vid = %d AND tu.uid =%d', $vid, $uid);
@@ -226,6 +237,7 @@ function user_tags_get_terms_by_vocabula
   return $terms;
 }
 
+
 /**
  * generate the categories selected for this module
  * in admin setting, if user has already selected any tags
@@ -233,13 +245,13 @@ function user_tags_get_terms_by_vocabula
  *
  * @param  char  $category : current page name
  * @param  array $account  : user details
- * @return taxonomy form
+ * @return array : taxonomy form
  */
 function user_tags_form_tags($category, $account){
   if ($category != 'tags') {
     return;
   }
-
+  
   if (!isset($account->taxonomy)) {
     if ($account->uid) {
       $terms = user_tags_get_terms($account->uid);
@@ -294,6 +306,7 @@ function user_tags_form_tags($category, 
           $default_terms[$term->tid] = $term;
         }
       }
+      
       $form['taxonomy']['tags'][$vocabulary->vid] = taxonomy_form($vocabulary->vid, array_keys($default_terms), $vocabulary->help);
       $form['taxonomy']['tags'][$vocabulary->vid]['#weight'] = $vocabulary->weight;
       $form['taxonomy']['tags'][$vocabulary->vid]['#required'] = $vocabulary->required;
@@ -305,19 +318,38 @@ function user_tags_form_tags($category, 
   return $form;
 }
 
-function user_tags_load_tags($account){
+
+/**
+ * Load tags onto a User Object
+ *
+ * @param object $account : User Object for modifying (passed ByRef)
+ */
+function user_tags_load_tags(&$account){
   $result = db_query('SELECT t.* FROM {term_data} t INNER JOIN {term_user} tu WHERE tu.tid = t.tid AND tu.uid = %d ORDER BY weight, name', $account->uid);
   $account->taxonomy = array();
   while ($term = db_fetch_object($result)) {
     $account->taxonomy[$term->tid] = $term;
   }
-  return $account->taxonomy;
 }
 
+
+/**
+ * Function for deleting tags from a user account
+ *
+ * @param object $account : User Object
+ */
 function user_tags_delete_tags($account){
   db_query('DELETE FROM {term_user} WHERE uid = %d', $account->uid);
 }
 
+
+/**
+ * User submit handling function.
+ *
+ * @param char $category : The selected tab on the user profile page.
+ * @param array $edit : the values returned from the submitted form
+ * @param object $account : The User Object
+ */
 function user_tags_submit_tags($category, $edit, $account){
   if ($category != 'tags') {
     return;
@@ -370,6 +402,13 @@ function user_tags_submit_tags($category
   unset($edit['taxonomy']);
 }
 
+
+/**
+ * Return an array of links to user tags.
+ *
+ * @param object $account : User account object (from user_load() function)
+ * @return array : nested array
+ */
 function user_tags_view_tags($account){
   $list = array();
   foreach ($account->taxonomy as $tid => $term) {
@@ -380,3 +419,41 @@ function user_tags_view_tags($account){
     return array('Tags' => $list);
   }
 }
+
+/**
+ * Find users with similar tags. Results are ordered so the closest matching user
+ *   is decided on number of matching terms, falling back to alphabetical on
+ *   username if matching terms are equal.
+ *
+ * @param array $terms : array of term objects with the array keys as term ID's (ie, the result of user_tags_get_terms($uid)
+ * @param int $limit : optional, limit the number of results returned. Default: 5
+ * @return array : Array of output from theme_username.
+ */
+function user_tags_get_similar_users($terms, $limit = 5) {
+  if (empty($terms)) {
+    return array();
+  }
+  
+  $args = implode(',', array_keys($terms));
+  $result = db_query('SELECT
+                        u.uid AS uid,
+                        COUNT(*) AS cnt
+                      FROM {users} u
+                      LEFT JOIN {term_user} tu ON tu.uid = u.uid AND tu.tid IN (%s)
+                      WHERE u.status = 1 AND tu.tid IS NOT NULL
+                      GROUP BY u.uid
+                      ORDER BY cnt DESC, u.name ASC
+                      LIMIT %d', $args, $limit);
+  if (db_num_rows($result)) {
+    $items = array();
+    
+    while ($item = db_fetch_object($result)) {
+      $items[] = theme('username', user_load(array('uid' => $item->uid)));
+    }
+    
+    return $items;
+  }
+  else {
+    return array();
+  }
+}