Skip to content
GitLab
Commit 12973db0 authored by Jennifer Hodgdon's avatar Jennifer Hodgdon
Browse files

Issue #1355670 by pwolanin, NROTC_Webmaster, xjm: API docs cleanup for Search module

parent 5106e36c
Hide whitespace changes
Inline Side-by-side
core/modules/search/lib/Drupal/search/SearchQuery.php
View file @ 12973db0
......@@ -3,6 +3,8 @@
/**
* @file
* Definition of Drupal\search\SearchQuery.
*
* Search query extender and helper functions.
*/
namespace Drupal\search;
......@@ -11,19 +13,14 @@
use Drupal\Core\Database\StatementEmpty;
/**
* @file
* Search query extender and helper functions.
*/
/**
* Do a query on the full-text search index for a word or words.
* Performs a query on the full-text search index for a word or words.
*
* This function is normally only called by each module that supports the
* indexed search (and thus, implements hook_update_index()).
*
* Results are retrieved in two logical passes. However, the two passes are
* joined together into a single query. And in the case of most simple
* queries the second pass is not even used.
* joined together into a single query, and in the case of most simple queries
* the second pass is not even used.
*
* The first pass selects a set of all possible matches, which has the benefit
* of also providing the exact result set for simple "AND" or "OR" searches.
......@@ -43,7 +40,7 @@ class SearchQuery extends SelectExtender {
protected $searchExpression;
/**
* Type of search (search module).
* The type of search (search module).
*
* 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
......@@ -63,7 +60,7 @@ class SearchQuery extends SelectExtender {
/**
* Indicates whether the first pass query requires complex conditions (LIKE).
*
* @var boolean.
* @var bool
*/
protected $simple = TRUE;
......@@ -107,7 +104,7 @@ class SearchQuery extends SelectExtender {
/**
* Indicates whether the first pass query has been executed.
*
* @var boolean
* @var bool
*/
protected $executedFirstPass = FALSE;
......@@ -138,7 +135,7 @@ class SearchQuery extends SelectExtender {
* The maximum number of AND/OR combinations exceeded can be configured to
* avoid Denial-of-Service attacks. Expressions beyond the limit are ignored.
*
* @var boolean
* @var bool
*/
protected $expressionsIgnored = FALSE;
......@@ -411,6 +408,9 @@ public function executeFirstPass() {
* @param $multiply
* If set, the score is multiplied with that value. Search query ensures
* that the search scores are still normalized.
*
* @return object
* The updated query object.
*/
public function addScore($score, $arguments = array(), $multiply = FALSE) {
if ($multiply) {
......
core/modules/search/search.admin.inc
View file @ 12973db0
......@@ -8,7 +8,7 @@
use Drupal\Component\Utility\NestedArray;
/**
* Menu callback: confirm wiping of the index.
* Menu callback: Confirms wiping of the index.
*/
function search_reindex_confirm() {
return confirm_form(array(), t('Are you sure you want to re-index the site?'),
......@@ -16,7 +16,10 @@ function search_reindex_confirm() {
}
/**
* Handler for wipe confirmation
* Form submission handler for search_reindex_confirm().
*
* @see search_reindex()
* @see search_reindex_confirm()
*/
function search_reindex_confirm_submit(&$form, &$form_state) {
if ($form['confirm']) {
......@@ -39,13 +42,13 @@ function _search_get_module_names() {
}
/**
* Menu callback: displays the search module settings page.
*
* @ingroup forms
* Form constructor for the Search module's settings page.
*
* @see search_admin_settings_validate()
* @see search_admin_settings_submit()
* @see search_admin_reindex_submit()
*
* @ingroup forms
*/
function search_admin_settings($form, &$form_state) {
$config = config('search.settings');
......@@ -183,7 +186,7 @@ function search_admin_settings_submit($form, &$form_state) {
}
/**
* Form submission handler for reindex button on search_admin_settings_form().
* Form submission handler for the reindex button on search_admin_settings().
*/
function search_admin_reindex_submit($form, &$form_state) {
// send the user to the confirmation page
......
core/modules/search/search.api.php
View file @ 12973db0
......@@ -13,28 +13,28 @@
/**
* Define a custom search type.
*
* This hook allows a module to tell search.module that it wishes to perform
* searches on content it defines (custom node types, users, or comments for
* example) when a site search is performed.
* This hook allows a module to tell the Search module that it wishes to
* perform searches on content it defines (custom node types, users, or
* comments for example) when a site search is performed.
*
* In order for the search to do anything, your module must also implement
* hook_search_execute(), which is called when someone requests a search
* on your module's type of content. If you want to have your content
* indexed in the standard search index, your module should also implement
* hook_search_execute(), which is called when someone requests a search on
* your module's type of content. If you want to have your content indexed
* in the standard search index, your module should also implement
* hook_update_index(). If your search type has settings, you can implement
* hook_search_admin() to add them to the search settings page. You can use
* hook_form_FORM_ID_alter(), with FORM_ID set to 'search_form', to add fields
* to the search form (see node_form_search_form_alter() for an example).
* You can use hook_search_access() to limit access to searching,
* and hook_search_page() to override how search results are displayed.
* You can use hook_search_access() to limit access to searching, and
* hook_search_page() to override how search results are displayed.
*
* @return
* Array with optional keys:
* - 'title': Title for the tab on the search page for this module. Defaults
* to the module name if not given.
* - 'path': Path component after 'search/' for searching with this module.
* - title: Title for the tab on the search page for this module. Defaults to
* the module name if not given.
* - path: Path component after 'search/' for searching with this module.
* Defaults to the module name if not given.
* - 'conditions_callback': Name of a callback function that is invoked by
* - conditions_callback: Name of a callback function that is invoked by
* search_view() to get an array of additional search conditions to pass to
* search_data(). For example, a search module may get additional keywords,
* filters, or modifiers for the search from the query string. Sample
......@@ -58,6 +58,7 @@ function hook_search_info() {
* generated internally - for example based on a module's settings.
*
* @see hook_search_info()
*
* @ingroup search
*/
function sample_search_conditions_callback($keys) {
......@@ -90,8 +91,8 @@ function hook_search_access() {
* Take action when the search index is going to be rebuilt.
*
* Modules that use hook_update_index() should update their indexing
* bookkeeping so that it starts from scratch the next time
* hook_update_index() is called.
* bookkeeping so that it starts from scratch the next time hook_update_index()
* is called.
*
* @ingroup search
*/
......@@ -111,8 +112,8 @@ function hook_search_reset() {
*
* @return
* An associative array with the key-value pairs:
* - 'remaining': The number of items left to index.
* - 'total': The total number of items to index.
* - remaining: The number of items left to index.
* - total: The total number of items to index.
*
* @ingroup search
*/
......@@ -179,22 +180,23 @@ function hook_search_admin() {
* index.
*
* @param $keys
* The search keywords as entered by the user.
* The search keywords as entered by the user. Defaults to NULL.
* @param $conditions
* An optional array of additional conditions, such as filters.
* (optional) An array of additional conditions, such as filters. Defaults to
* NULL.
*
* @return
* 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 (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.
* - 'extra': An array of optional extra information items.
* - 'snippet': An excerpt or preview to show with the result (can be
* generated with search_excerpt()).
* - 'language': Language code for the item (usually two characters).
* 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 (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.
* - extra: An array of optional extra information items.
* - snippet: An excerpt or preview to show with the result (can be generated
* with search_excerpt()).
* - language: Language code for the item (usually two characters).
*
* @ingroup search
*/
......@@ -261,22 +263,23 @@ function hook_search_execute($keys = NULL, $conditions = NULL) {
/**
* Override the rendering of search results.
*
* A module that implements hook_search_info() to define a type of search
* may implement this hook in order to override the default theming of
* its search results, which is otherwise themed using theme('search_results').
* A module that implements hook_search_info() to define a type of search may
* implement this hook in order to override the default theming of its search
* results, which is otherwise themed using theme('search_results').
*
* Note that by default, theme('search_results') and theme('search_result')
* work together to create an ordered list (OL). So your hook_search_page()
* implementation should probably do this as well.
*
* @see search-result.tpl.php, search-results.tpl.php
*
* @param $results
* An array of search results.
*
* @return
* A renderable array, which will render the formatted search results with
* a pager included.
* A renderable array, which will render the formatted search results with a
* pager included.
*
* @see search-result.tpl.php
* @see search-results.tpl.php
*/
function hook_search_page($results) {
$output['prefix']['#markup'] = '<ol class="search-results">';
......@@ -296,8 +299,8 @@ function hook_search_page($results) {
/**
* Preprocess text for search.
*
* This hook is called to preprocess both the text added to the search index and
* the keywords users have submitted for searching.
* This hook is called to preprocess both the text added to the search index
* and the keywords users have submitted for searching.
*
* Possible uses:
* - Adding spaces between words of Chinese or Japanese text.
......@@ -314,9 +317,9 @@ function hook_search_page($results) {
* The language code of the entity that has been found.
*
* @return
* The text after preprocessing. Note that if your module decides not to alter
* the text, it should return the original text. Also, after preprocessing,
* words in the text should be separated by a space.
* The text after preprocessing. Note that if your module decides not to
* alter the text, it should return the original text. Also, after
* preprocessing, words in the text should be separated by a space.
*
* @ingroup search
*/
......@@ -336,7 +339,7 @@ function hook_search_preprocess($text, $langcode = NULL) {
/**
* Update the search index for this module.
*
* This hook is called every cron run if search.module is enabled, your
* This hook is called every cron run if the Search module is enabled, your
* module has implemented hook_search_info(), and your module has been set as
* an active search module on the Search settings page
* (admin/config/search/settings). It allows your module to add items to the
......@@ -382,6 +385,7 @@ function hook_update_index() {
search_index($node->nid, 'node', $text);
}
}
/**
* @} End of "addtogroup hooks".
*/
core/modules/search/search.install
View file @ 12973db0
......@@ -2,7 +2,7 @@
/**
* @file
* Install, update and uninstall functions for the search module.
* Install, update, and uninstall functions for the Search module.
*/
/**
......
core/modules/search/search.module
View file @ 12973db0
......@@ -263,7 +263,7 @@ function search_get_info($all = FALSE) {
* Returns information about the default search module.
*
* @return
* The search_get_info() array element for the default search module, if any.
* The search_get_info() array element for the default search module, if any.
*/
function search_get_default_module_info() {
$info = search_get_info();
......@@ -277,14 +277,22 @@ function search_get_default_module_info() {
}
/**
* Access callback for search tabs.
* Access callback: Determines access for a search page.
*
* @param int $name
* The name of a search module (e.g., 'node')
*
* @return bool
* TRUE if a user has access to the search page; FALSE otherwise.
*
* @see search_menu()
*/
function _search_menu_access($name) {
return user_access('search content') && (!function_exists($name . '_search_access') || module_invoke($name, 'search_access'));
}
/**
* Clears a part of or the entire search index.
* Clears either a part of, or the entire search index.
*
* @param $sid
* (optional) The ID of the item to remove from the search index. If
......@@ -460,14 +468,14 @@ function search_simplify($text, $langcode = NULL) {
* written in long strings of characters, though, not split up into words. So
* in order to allow search matching, we split up CJK text into tokens
* consisting of consecutive, overlapping sequences of characters whose length
* is equal to the 'minimum_word_size' variable. This tokenizing is only done if
* the 'overlap_cjk' variable is TRUE.
* is equal to the 'minimum_word_size' variable. This tokenizing is only done
* if the 'overlap_cjk' variable is TRUE.
*
* @param $matches
* This function is a callback for preg_replace_callback(), which is called
* from search_simplify(). So, $matches is an array of regular expression
* matches, which means that $matches[0] contains the matched text -- a string
* of CJK characters to tokenize.
* matches, which means that $matches[0] contains the matched text -- a
* string of CJK characters to tokenize.
*
* @return
* Tokenized text, starting and ending with a space character.
......@@ -539,13 +547,13 @@ function search_invoke_preprocess(&$text, $langcode = NULL) {
}
/**
* Update the full-text search index for a particular item.
* Updates the full-text search index for a particular item.
*
* @param $sid
* 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()).
* 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 or plain text.
* @param $langcode
......@@ -882,13 +890,13 @@ function search_expression_extract($expression, $option) {
* The value to add for the option. If present, it will replace any previous
* value added for the option. Cannot contain any spaces or | characters, as
* these are used as delimiters. If you want to add a blank value $option: to
* the search expression, pass in an empty string or a string that is composed
* of only spaces. To clear a previously-stored option without adding a
* replacement, pass in NULL for $value or omit.
* the search expression, pass in an empty string or a string that is
* composed of only spaces. To clear a previously-stored option without
* adding a replacement, pass in NULL for $value or omit.
*
* @return
* $expression, with any previous value for this option removed, and a new
* $option:$value pair added if $value was provided.
* The search expression, with any previous value for this option removed, and
* a new $option:$value pair added if $value was provided.
*/
function search_expression_insert($expression, $option, $value = NULL) {
// Remove any previous values stored with $option.
......@@ -907,8 +915,8 @@ function search_expression_insert($expression, $option, $value = NULL) {
* The Drupal search interface manages a global search mechanism.
*
* Modules may plug into this system to provide searches of different types of
* data. Most of the system is handled by search.module, so this must be enabled
* for all of the search features to work.
* data. Most of the system is handled by the Search module, so this must be
* enabled 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
......@@ -917,20 +925,20 @@ function search_expression_insert($expression, $option, $value = NULL) {
* 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_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.
*
* If your module needs to provide a more complicated search form, then you need
* to implement it yourself without hook_search_info(). In that case, you should
* define it as a local task (tab) under the /search page (e.g. /search/mymodule)
* so that users can easily find it.
* If your module needs to provide a more complicated search form, then you
* need to implement it yourself without hook_search_info(). In that case, you
* should define it as a local task (tab) under the /search page (e.g.
* /search/mymodule) so that users can easily find it.
*/
/**
* Builds a search form.
* Form constructor for the search form.
*
* @param $action
* Form action. Defaults to "search/$path", where $path is the search path
......@@ -942,11 +950,14 @@ function search_expression_insert($expression, $option, $value = NULL) {
* 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
* Label for the keywords field. Defaults to t('Enter your keywords') if NULL.
* Supply '' to omit.
* Label for the keywords field. Defaults to t('Enter your keywords') if
* NULL. Supply '' to omit.
*
* @return
* A Form API array for the search form.
*
* @see search_form_validate()
* @see search_form_submit()
*/
function search_form($form, &$form_state, $action = '', $keys = '', $module = NULL, $prompt = NULL) {
$module_info = FALSE;
......@@ -992,10 +1003,14 @@ function search_form($form, &$form_state, $action = '', $keys = '', $module = NU
}
/**
* Form builder; Output a search form for the search block's search box.
* Form constructor for the search block's search box.
*
* @param $form_id
* The unique string identifying the desired form.
*
* @ingroup forms
* @see search_box_form_submit()
*
* @ingroup forms
*/
function search_box($form, &$form_state, $form_id) {
$form[$form_id] = array(
......@@ -1014,7 +1029,7 @@ function search_box($form, &$form_state, $form_id) {
}
/**
* Process a block search form submission.
* Form submission handler for search_box().
*/
function search_box_form_submit($form, &$form_state) {
// The search form relies on control of the redirect destination for its
......@@ -1076,6 +1091,7 @@ function search_data($keys, $module, $conditions = NULL) {
/**
* Returns snippets from a piece of text, with certain keywords highlighted.
*
* Used for formatting search results.
*
* @param $keys
......@@ -1232,7 +1248,7 @@ function _search_excerpt_replace(&$text) {
}
/**
* Find words in the original text that matched via search_simplify().
* Finds words in the original text that matched via search_simplify().
*
* This is called in search_excerpt() if an exact match is not found in the
* text, so that we can find the derived form that matches.
......
core/modules/search/search.pages.inc
View file @ 12973db0
......@@ -2,11 +2,11 @@
/**
* @file
* User page callbacks for the search module.
* User page callbacks for the Search module.
*/
/**
* Menu callback; presents the search form and/or search results.
* Page callback: Presents the search form and/or search results.
*
* @param $module
* Search module to use for the search.
......@@ -72,12 +72,13 @@ function search_view($module = NULL, $keys = '') {
}
/**
* Process variables for search-results.tpl.php.
* Prepocesses the variables for search-results.tpl.php.
*
* The $variables array contains the following arguments:
* - $results: Search results array.
* - $module: Module the search results came from (module implementing
* hook_search_info()).
* @param $variables
* An array with the following elements:
* - results: Search results array.
* - module: Module the search results came from (module implementing
* hook_search_info()).
*
* @see search-results.tpl.php
*/
......@@ -94,11 +95,13 @@ function template_preprocess_search_results(&$variables) {
}
/**
* Process variables for search-result.tpl.php.
* Preprocesses the variables for search-result.tpl.php.
*
* The $variables array contains the following arguments:
* - $result
* - $module
* @param $variables
* An array with the following elements:
* - result: Search results array.
* - module: Module the search results came from (module implementing
* hook_search_info()).
*
* @see search-result.tpl.php
*/
......@@ -135,17 +138,23 @@ function template_preprocess_search_result(&$variables) {
}
/**
* Form validation handler for search_form().
*
* As the search form collates keys from other modules hooked in via
* hook_form_alter, the validation takes place in _submit.
* hook_form_alter, the validation takes place in search_form_submit().
* search_form_validate() is used solely to set the 'processed_keys' form
* value for the basic search form.
*
* @see search_form_submit()
*/
function search_form_validate($form, &$form_state) {
form_set_value($form['basic']['processed_keys'], trim($form_state['values']['keys']), $form_state);
}
/**
* Process a search form submission.
* Form submission handler for search_form().
*
* @see search_form_validate()
*/
function search_form_submit($form, &$form_state) {
$keys = $form_state['values']['processed_keys'];
......
core/modules/search/templates/search-result.tpl.php
View file @ 12973db0
......@@ -5,8 +5,8 @@
* Default theme implementation for displaying a single search result.
*
* This template renders a single search result and is collected into
* search-results.tpl.php. This and the parent template are
* dependent to one another sharing the markup for definition lists.
* search-results.tpl.php. This and the parent template are dependent on one
* another sharing the markup for definition lists.
*
* Available variables:
* - $url: URL of the result.
......@@ -15,8 +15,8 @@
* - $info: String of all the meta information ready for print. Does not apply
* to user searches.
* - $info_split: Contains same data as $info, split into a keyed array.
* - $module: The machine-readable name of the module (tab) being searched, such
* as "node" or "user".
* - $module: The machine-readable name of the module (tab) being searched,
* such as "node" or "user".
* - $title_prefix (array): An array containing additional output populated by
* modules, intended to be displayed in front of the main title tag that
* appears in the template.
......@@ -30,7 +30,7 @@
* on permission.
* - $info_split['date']: Last update of the node. Short formatted.
* - $info_split['comment']: Number of comments output as "% comments", %
* being the count. Depends on comment.module.
* being the count. Depends on the Comment module.
*
* Other variables:
* - $title_attributes: Array of HTML attributes for the title. It is
......
core/modules/search/tests/modules/search_embedded_form/search_embedded_form.info
View file @ 12973db0
name = "Search embedded form"
description = "Support module for search module testing of embedded forms."
name = Search Embedded Form
description = Support module for Search module testing of embedded forms.
package = Testing
version = VERSION
core = 8.x
......
core/modules/search/tests/modules/search_embedded_form/search_embedded_form.module
View file @ 12973db0
......@@ -4,9 +4,9 @@
* @file
* Test module implementing a form that can be embedded in search results.
*
* Embedded form are important, for example, for ecommerce sites where each
* search result may included an embedded form with buttons like "Add to cart"
* for each individual product (node) listed in the search results.
* A sample use of an embedded form is an e-commerce site where each search
* result may include an embedded form with buttons like "Add to cart" for each
* individual product (node) listed in the search results.
*/
/**
......@@ -25,7 +25,7 @@ function search_embedded_form_menu() {
}
/**
* Builds a form for embedding in search results for testing.
* Form constructor for embedding search results for testing.
*
* @see search_embedded_form_form_submit().
*/
......
core/modules/search/tests/modules/search_extra_type/search_extra_type.info
View file @ 12973db0
name = "Test search type"
description = "Support module for search module testing."
name = Test Search Type
description = Support module for Search module testing.
package = Testing
version = VERSION