Skip to content
GitLab
Menu
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in
Toggle navigation
Menu
Open sidebar
project
drupal
Commits
12973db0
Commit
12973db0
authored
Feb 04, 2013
by
Jennifer Hodgdon
Browse files
Issue
#1355670
by pwolanin, NROTC_Webmaster, xjm: API docs cleanup for Search module
parent
5106e36c
Changes
11
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
. A
nd in the case of most simple
*
queries
the second pass is not even used.
* joined together into a single query
, a
nd 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).
* T
he t
ype 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 bool
ean.
* @var bool
*/
protected
$simple
=
TRUE
;
...
...
@@ -107,7 +104,7 @@ class SearchQuery extends SelectExtender {
/**
* Indicates whether the first pass query has been executed.
*
* @var bool
ean
* @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 bool
ean
* @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:
c
onfirm wiping of the index.
* Menu callback:
C
onfirm
s
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
s
earch
.
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 S
earch
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
'
:
R
equired
.
The URL of the found item.
* -
'
type
'
: The type of item (such as the content type).
* -
'
title
'
:
R
equired
.
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:
(r
equired
)
The URL of the found item.
* - type: The type of item (such as the content type).
* - title:
(r
equired
)
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
s
earch
.
module is enabled, your
* This hook is called every cron run if
the S
earch
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
s
earch module.
* Install, update
,
and uninstall functions for the
S
earch 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.
* Update
s
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
s
earch
.
module, so this must be
enabled
* for all of the search features to work.
* data. Most of the system is handled by
the S
earch
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
for
m
s
ubmission
.
*
Form submission handler
for s
earch_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().
* Find
s
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
s
earch module.
* User page callbacks for the
S
earch module.
*/
/**
*
Menu
callback
; p
resents the search form and/or search results.
*
Page
callback
: P
resents 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.
* Pr
ep
ocess
es 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.
* Pr
epr
ocess
es 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
c
omment
.
module.
* being the count. Depends on
the C
omment
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
e
mbedded
f
orm
"
description
=
"
Support module for
s
earch module testing of embedded forms.
"
name
=
Search
E
mbedded
F
orm
description
=
Support
module
for
S
earch
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 site
s
where each
*
search
result may include
d
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
s
earch
t
ype
"
description
=
"
Support module for
s
earch module testing.
"
name
=
Test
S
earch
T
ype
description
=
Support
module
for
S
earch
module
testing
.
package
=
Testing
version
=
VERSION