From c3081764c3eabeed2318b7302339d52a21eb92f0 Mon Sep 17 00:00:00 2001
From: Angie Byron <webchick@24967.no-reply.drupal.org>
Date: Wed, 5 Aug 2009 14:58:40 +0000
Subject: [PATCH] #364564 by cwgordon7: Document hook_ranking().
---
modules/node/node.api.php | 61 +++++++++++++++++++++++++++++++++++++++
1 file changed, 61 insertions(+)
diff --git a/modules/node/node.api.php b/modules/node/node.api.php
index 2a490e57ad6b..81852808216c 100644
--- a/modules/node/node.api.php
+++ b/modules/node/node.api.php
@@ -564,6 +564,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.
*
--
GitLab