- Patch #827116 by jhodgdon, marvil07: search API is inconsistent in /, and generally needs doc cleanup.

merge-requests/26/head
Dries Buytaert 2010-11-21 18:42:25 +00:00
parent 8ae92e78ef
commit 14c98d183f
6 changed files with 92 additions and 82 deletions

View File

@ -20,7 +20,7 @@
* as "node" or "user".
*
* Default keys within $info_split:
* - $info_split['type']: Node type.
* - $info_split['type']: Node type (or item type string supplied by module).
* - $info_split['user']: Author of the node linked to users profile. Depends
* on permission.
* - $info_split['date']: Last update of the node. Short formatted.

View File

@ -181,7 +181,7 @@ function hook_search_admin() {
* An array of search results. To use the default search result
* display, each item should have the following keys':
* - 'link': Required. The URL of the found item.
* - 'type': The type of item.
* - 'type': The type of item (such as the content type).
* - 'title': Required. The name of the item.
* - 'user': The author of the item.
* - 'date': A timestamp when the item was last modified.
@ -272,8 +272,8 @@ function hook_search_page($results) {
foreach ($results as $entry) {
$output[] = array(
'#theme' => 'search_result',
'#result' => $entry,
'#theme' => 'search_result',
'#result' => $entry,
'#module' => 'my_module_name',
);
}

View File

@ -22,8 +22,8 @@
* The second portion of the query further refines this set by verifying
* advanced text conditions (such as negative or phrase matches).
*
* The used query object has the tag 'search_$type' and can be further extended
* with hook_query_alter().
* The used query object has the tag 'search_$module' and can be further
* extended with hook_query_alter().
*/
class SearchQuery extends SelectQueryExtender {
/**
@ -34,9 +34,11 @@ class SearchQuery extends SelectQueryExtender {
protected $searchExpression;
/**
* Type of search.
* Type of search (search module).
*
* This maps to the value of the type column in search_index.
* This maps to the value of the type column in search_index, and is equal
* to the machine-readable name of the module that implements
* hook_search_info().
*
* @var string
*/
@ -50,7 +52,7 @@ class SearchQuery extends SelectQueryExtender {
protected $keys = array('positive' => array(), 'negative' => array());
/**
* Indicates if the first pass query requires complex conditions (LIKE).
* Indicates whether the first pass query requires complex conditions (LIKE).
*
* @var boolean.
*/
@ -94,7 +96,7 @@ class SearchQuery extends SelectQueryExtender {
protected $normalize;
/**
* Indicates if the first pass query has been executed.
* Indicates whether the first pass query has been executed.
*
* @var boolean
*/
@ -122,33 +124,35 @@ class SearchQuery extends SelectQueryExtender {
protected $multiply = array();
/**
* Search items for the given search query string and type.
* Sets up the search query expression.
*
* @param $query
* A search query string, that can contain options.
* @param $type
* The type of search, this maps to {search_index}.type.
* A search query string, which can contain options.
* @param $module
* The search module. This maps to {search_index}.type in the database.
*
* @return
* The SearchQuery object.
*/
public function searchExpression($expression, $type) {
public function searchExpression($expression, $module) {
$this->searchExpression = $expression;
$this->type = $type;
$this->type = $module;
return $this;
}
/**
* Apply a search option and remove it from the search query string.
* Applies a search option and removes it from the search query string.
*
* These options are in the form option:value,value2,value3.
*
* @param $option
* Name of the option.
* @param $column
* Name of the db column to which the value should be applied.
* Name of the database column to which the value should be applied.
*
* @return
* TRUE if at least a value for that option has been found, FALSE if not.
* TRUE if a value for that option was found, FALSE if not.
*/
public function setOption($option, $column) {
if ($values = search_expression_extract($this->searchExpression, $option)) {
@ -164,9 +168,9 @@ class SearchQuery extends SelectQueryExtender {
}
/**
* Parse a search query into SQL conditions.
* Parses the search query into SQL conditions.
*
* We build two queries that matches the dataset bodies.
* We build two queries that match the dataset bodies.
*/
protected function parseSearchExpression() {
// Matchs words optionally prefixed by a dash. A word in this case is
@ -303,10 +307,10 @@ class SearchQuery extends SelectQueryExtender {
}
/**
* Execute the first pass query.
* Executes the first pass query.
*
* This can either be done explicitly, so that additional scores and
* conditions can be applied to the second pass query or implicitly by
* conditions can be applied to the second pass query, or implicitly by
* addScore() or execute().
*
* @return
@ -362,7 +366,7 @@ class SearchQuery extends SelectQueryExtender {
/**
* Adds a custom score expression to the search query.
*
* Each score expression can optionally use a multiplicator and multiple
* Each score expression can optionally use a multiplier, and multiple
* expressions are combined.
*
* @param $score
@ -388,15 +392,15 @@ class SearchQuery extends SelectQueryExtender {
}
/**
* Execute the search.
* Executes the search.
*
* If not already done, this executes the first pass query, then the complex
* If not already done, this executes the first pass query. Then the complex
* conditions are applied to the query including score expressions and
* ordering.
*
* @return
* FALSE if the first pass query returned no results and a database result
* set if not.
* FALSE if the first pass query returned no results, and a database result
* set if there were results.
*/
public function execute()
{
@ -447,10 +451,10 @@ class SearchQuery extends SelectQueryExtender {
}
/**
* Build the default count query for SearchQuery.
* Builds the default count query for SearchQuery.
*
* Since SearchQuery always uses GROUP BY, we can default to a subquery. Also
* adding the same conditions as execute() because countQuery() is called
* Since SearchQuery always uses GROUP BY, we can default to a subquery. We
* also add the same conditions as execute() because countQuery() is called
* first.
*/
public function countQuery() {

View File

@ -297,41 +297,44 @@ function _search_menu_access($name) {
}
/**
* Wipes a part of or the entire search index.
* Clears a part of or the entire search index.
*
* @param $sid
* (optional) The SID of the item to wipe. If specified, $type must be passed
* too.
* @param $type
* (optional) The type of item to wipe.
* (optional) The ID of the item to remove from the search index. If
* specified, $module must also be given. Omit both $sid and $module to clear
* the entire search index.
* @param $module
* (optional) The machine-readable name of the module for the item to remove
* from the search index.
*/
function search_reindex($sid = NULL, $type = NULL, $reindex = FALSE) {
if ($type == NULL && $sid == NULL) {
function search_reindex($sid = NULL, $module = NULL, $reindex = FALSE) {
if ($module == NULL && $sid == NULL) {
module_invoke_all('search_reset');
}
else {
db_delete('search_dataset')
->condition('sid', $sid)
->condition('type', $type)
->condition('type', $module)
->execute();
db_delete('search_index')
->condition('sid', $sid)
->condition('type', $type)
->condition('type', $module)
->execute();
// Don't remove links if re-indexing.
if (!$reindex) {
db_delete('search_node_links')
->condition('sid', $sid)
->condition('type', $type)
->condition('type', $module)
->execute();
}
}
}
/**
* Marks a word as dirty (or retrieves the list of dirty words). This is used
* during indexing (cron). Words which are dirty have outdated total counts in
* the search_total table, and need to be recounted.
* Marks a word as "dirty" (changed), or retrieves the list of dirty words.
*
* This is used during indexing (cron). Words that are dirty have outdated
* total counts in the search_total table, and need to be recounted.
*/
function search_dirty($word = NULL) {
$dirty = &drupal_static(__FUNCTION__, array());
@ -346,8 +349,9 @@ function search_dirty($word = NULL) {
/**
* Implements hook_cron().
*
* Fires hook_update_index() in all modules and cleans up dirty words (see
* search_dirty).
* Fires hook_update_index() in all modules and cleans up dirty words.
*
* @see search_dirty()
*/
function search_cron() {
// We register a shutdown function to ensure that search_total is always up
@ -361,7 +365,9 @@ function search_cron() {
}
/**
* This function is called on shutdown to ensure that search_total is always
* Updates the {search_total} database table.
*
* This function is called on shutdown to ensure that {search_total} is always
* up to date (even if cron times out or otherwise fails).
*/
function search_update_totals() {
@ -521,17 +527,16 @@ function search_invoke_preprocess(&$text) {
* Update the full-text search index for a particular item.
*
* @param $sid
* A number identifying this particular item (e.g. node id).
*
* @param $type
* A string defining this type of item (e.g. 'node')
*
* An ID number identifying this particular item (e.g., node ID).
* @param $module
* The machine-readable name of the module that this item comes from (a module
* that implements hook_search_info()).
* @param $text
* The content of this item. Must be a piece of HTML text.
* The content of this item. Must be a piece of HTML or plain text.
*
* @ingroup search
*/
function search_index($sid, $type, $text) {
function search_index($sid, $module, $text) {
$minimum_word_size = variable_get('minimum_word_size', 3);
// Link matching
@ -678,13 +683,13 @@ function search_index($sid, $type, $text) {
$tag = !$tag;
}
search_reindex($sid, $type, TRUE);
search_reindex($sid, $module, TRUE);
// Insert cleaned up data into dataset
db_insert('search_dataset')
->fields(array(
'sid' => $sid,
'type' => $type,
'type' => $module,
'data' => $accum,
'reindex' => 0,
))
@ -699,7 +704,7 @@ function search_index($sid, $type, $text) {
->key(array(
'word' => $word,
'sid' => $sid,
'type' => $type,
'type' => $module,
))
->fields(array('score' => $score))
->expression('score', 'score + :score', array(':score' => $score))
@ -711,7 +716,7 @@ function search_index($sid, $type, $text) {
// Get all previous links from this item.
$result = db_query("SELECT nid, caption FROM {search_node_links} WHERE sid = :sid AND type = :type", array(
':sid' => $sid,
':type' => $type
':type' => $module
), array('target' => 'slave'));
$links = array();
foreach ($result as $link) {
@ -727,7 +732,7 @@ function search_index($sid, $type, $text) {
db_update('search_node_links')
->fields(array('caption' => $caption))
->condition('sid', $sid)
->condition('type', $type)
->condition('type', $module)
->condition('nid', $nid)
->execute();
search_touch_node($nid);
@ -735,14 +740,14 @@ function search_index($sid, $type, $text) {
// Unset the link to mark it as processed.
unset($links[$nid]);
}
elseif ($sid != $nid || $type != 'node') {
elseif ($sid != $nid || $module != 'node') {
// Insert the existing link and mark the node for reindexing, but don't
// reindex if this is a link in a node pointing to itself.
db_insert('search_node_links')
->fields(array(
'caption' => $caption,
'sid' => $sid,
'type' => $type,
'type' => $module,
'nid' => $nid,
))
->execute();
@ -753,7 +758,7 @@ function search_index($sid, $type, $text) {
foreach ($links as $nid => $caption) {
db_delete('search_node_links')
->condition('sid', $sid)
->condition('type', $type)
->condition('type', $module)
->condition('nid', $nid)
->execute();
search_touch_node($nid);
@ -761,10 +766,10 @@ function search_index($sid, $type, $text) {
}
/**
* Change a node's changed timestamp to 'now' to force reindexing.
* Changes a node's changed timestamp to 'now' to force reindexing.
*
* @param $nid
* The nid of the node that needs reindexing.
* The node ID of the node that needs reindexing.
*/
function search_touch_node($nid) {
db_update('search_dataset')
@ -904,15 +909,15 @@ function search_expression_insert($expression, $option, $value = NULL) {
* for all of the search features to work.
*
* There are three ways to interact with the search system:
* - Specifically for searching nodes, you can implement hook_node_update_index()
* and hook_node_search_result(). However, note that the search system already
* indexes all visible output of a node, i.e. everything displayed normally
* by hook_view() and hook_node_view(). This is usually sufficient. You should
* only use this mechanism if you want additional, non-visible data to be
* indexed.
* - Implement hook_search_info(). This will create a search tab for your module on
* the /search page with a simple keyword search form. You will also need to
* implement hook_search_execute() to perform the search.
* - Specifically for searching nodes, you can implement
* hook_node_update_index() and hook_node_search_result(). However, note that
* the search system already indexes all visible output of a node; i.e.,
* everything displayed normally by hook_view() and hook_node_view(). This is
* usually sufficient. You should only use this mechanism if you want
* additional, non-visible data to be indexed.
* - Implement hook_search_info(). This will create a search tab for your module
* on the /search page with a simple keyword search form. You will also need
* to implement hook_search_execute() to perform the search.
* - Implement hook_update_index(). This allows your module to use Drupal's
* HTML indexing mechanism for searching full text efficiently.
*
@ -927,11 +932,11 @@ function search_expression_insert($expression, $option, $value = NULL) {
*
* @param $action
* Form action. Defaults to "search/$path", where $path is the search path
* associated with the $type module in its hook_search_info(). This will be
* associated with the module in its hook_search_info(). This will be
* run through url().
* @param $keys
* The search string entered by the user, containing keywords for the search.
* @param $type
* @param $module
* The search module to render the form for: a module that implements
* hook_search_info(). If not supplied, the default search module is used.
* @param $prompt
@ -941,14 +946,14 @@ function search_expression_insert($expression, $option, $value = NULL) {
* @return
* A Form API array for the search form.
*/
function search_form($form, &$form_state, $action = '', $keys = '', $type = NULL, $prompt = NULL) {
function search_form($form, &$form_state, $action = '', $keys = '', $module = NULL, $prompt = NULL) {
$module_info = FALSE;
if (!$type) {
if (!$module) {
$module_info = search_get_default_module_info();
}
else {
$info = search_get_info();
$module_info = isset($info[$type]) ? $info[$type] : FALSE;
$module_info = isset($info[$module]) ? $info[$module] : FALSE;
}
// Sanity check.
@ -968,7 +973,7 @@ function search_form($form, &$form_state, $action = '', $keys = '', $type = NULL
// Record the $action for later use in redirecting.
$form_state['action'] = $action;
$form['#attributes']['class'][] = 'search-form';
$form['module'] = array('#type' => 'value', '#value' => $type);
$form['module'] = array('#type' => 'value', '#value' => $module);
$form['basic'] = array('#type' => 'container', '#attributes' => array('class' => array('container-inline')));
$form['basic']['keys'] = array(
'#type' => 'textfield',

View File

@ -77,8 +77,9 @@ function search_view($module = NULL, $keys = '') {
* Process variables for search-results.tpl.php.
*
* The $variables array contains the following arguments:
* - $results
* - $module
* - $results: Search results array.
* - $module: Module the search results came from (module implementing
* hook_search_info()).
*
* @see search-results.tpl.php
*/

View File

@ -1184,7 +1184,7 @@ class SearchConfigSettingsForm extends DrupalWebTestCase {
* Verify that you can disable individual search modules.
*/
function testSearchModuleDisabling() {
// Array of search types to test: 'path' is the search path, 'title' is
// Array of search modules to test: 'path' is the search path, 'title' is
// the tab title, 'keys' are the keywords to search for, and 'text' is
// the text to assert is on the results page.
$module_info = array(