Commit c3081764 authored by webchick's avatar webchick

#364564 by cwgordon7: Document hook_ranking().

parent 24057c3d
......@@ -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.
*
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment