From 14c98d183faaa3ec83f1242d66341d801029cfd8 Mon Sep 17 00:00:00 2001 From: Dries Buytaert Date: Sun, 21 Nov 2010 18:42:25 +0000 Subject: - Patch #827116 by jhodgdon, marvil07: search API is inconsistent in /, and generally needs doc cleanup. --- modules/search/search-result.tpl.php | 2 +- modules/search/search.api.php | 6 +-- modules/search/search.extender.inc | 58 ++++++++++---------- modules/search/search.module | 101 ++++++++++++++++++----------------- modules/search/search.pages.inc | 5 +- modules/search/search.test | 2 +- 6 files changed, 92 insertions(+), 82 deletions(-) (limited to 'modules/search') diff --git a/modules/search/search-result.tpl.php b/modules/search/search-result.tpl.php index 625133fb7..667540adb 100644 --- a/modules/search/search-result.tpl.php +++ b/modules/search/search-result.tpl.php @@ -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. diff --git a/modules/search/search.api.php b/modules/search/search.api.php index f6209987f..13b812aab 100644 --- a/modules/search/search.api.php +++ b/modules/search/search.api.php @@ -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', ); } diff --git a/modules/search/search.extender.inc b/modules/search/search.extender.inc index 6c0c7600b..5347bb52a 100644 --- a/modules/search/search.extender.inc +++ b/modules/search/search.extender.inc @@ -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() { diff --git a/modules/search/search.module b/modules/search/search.module index 82eb65d37..3489fd74f 100644 --- a/modules/search/search.module +++ b/modules/search/search.module @@ -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', diff --git a/modules/search/search.pages.inc b/modules/search/search.pages.inc index 607afa97f..c78c60aaf 100644 --- a/modules/search/search.pages.inc +++ b/modules/search/search.pages.inc @@ -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 */ diff --git a/modules/search/search.test b/modules/search/search.test index 040465103..c7a18ef46 100644 --- a/modules/search/search.test +++ b/modules/search/search.test @@ -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( -- cgit v1.2.3