#364564 by cwgordon7: Document hook_ranking().

1 files changed, 61 insertions, 0 deletions

diff --git a/modules/node/node.api.php b/modules/node/node.api.php
index 2a490e57a..818528082 100644
--- a/modules/node/node.api.php
+++ b/modules/node/node.api.php
@@ -565,6 +565,67 @@ function hook_node_info() {
 }
 
 /**
+ * Provide additional methods of scoring for core search results for nodes.
+ *
+ * A node's search score is used to rank it among other nodes matched by the
+ * search, with the highest-ranked nodes appearing first in the search listing.
+ *
+ * For example, a module allowing users to vote on content could expose an
+ * option to allow search results' rankings to be influenced by the average
+ * voting score of a node.
+ *
+ * All scoring mechanisms are provided as options to site administrators, and
+ * may be tweaked based on individual sites or disabled altogether if they do
+ * not make sense. Individual scoring mechanisms, if enabled, are assigned a
+ * weight from 1 to 10. The weight represents the factor of magnification of
+ * the ranking mechanism, with higher-weighted ranking mechanisms having more
+ * influence. In order for the weight system to work, each scoring mechanism
+ * must return a value between 0 and 1 for every node. That value is then
+ * multiplied by the administrator-assigned weight for the ranking mechanism,
+ * and then the weighted scores from all ranking mechanisms are added, which
+ * brings about the same result as a weighted average.
+ *
+ * @return
+ *   An associative array of ranking data. The keys should be strings,
+ *   corresponding to the internal name of the ranking mechanism, such as
+ *   'recent', or 'comments'. The values should be arrays themselves, with the
+ *   following keys available:
+ *   - "title": the human readable name of the ranking mechanism. Required.
+ *   - "join": part of a query string to join to any additional necessary
+ *     table. This is not necessary if the table required is already joined to
+ *     by the base query, such as for the {node} table. Other tables should use
+ *     the full table name as an alias to avoid naming collisions. Optional.
+ *   - "score": part of a query string to calculate the score for the ranking
+ *     mechanism based on values in the database. This does not need to be
+ *     wrapped in parentheses, as it will be done automatically; it also does
+ *     not need to take the weighted system into account, as it will be done
+ *     automatically. It does, however, need to calculate a decimal between
+ *     0 and 1; be careful not to cast the entire score to an integer by
+ *     inadvertantly introducing a variable argument. Required.
+ *   - "arguments": if any arguments are required for the score, they can be
+ *     specified in an array here.
+ */
+function hook_ranking() {
+  // If voting is disabled, we can avoid returning the array, no hard feelings.
+  if (variable_get('vote_node_enabled', TRUE)) {
+    return array(
+      'vote_average' => array(
+        'title' => t('Average vote'),
+        // Note that we use i.sid, the search index's search item id, rather than
+        // n.nid.
+        'join' => 'LEFT JOIN {vote_node_data} vote_node_data ON vote_node_data.nid = i.sid',
+        // The highest possible score should be 1, and the lowest possible score,
+        // always 0, should be 0.
+        'score' => 'vote_node_data.average / CAST(%f AS DECIMAL)',
+        // Pass in the highest possible voting score as a decimal argument.
+        'arguments' => array(variable_get('vote_score_max', 5)),
+      ),
+    );
+  }
+}
+
+
+/**
  * Act on node type changes.
  *
  * This hook allows modules to take action when a node type is modified.