Commit fc4e2487 authored by Steven Wittens's avatar Steven Wittens

Various additions, improvements and fixes to the search documentation.

parent 0b8ff5d1
......@@ -7,9 +7,10 @@
*/
/**
* Unicode character classes to include in the index.
* Matches Unicode character classes to exclude from the search index.
* See: http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values
*
* The index only contains the following character classes:
* Lu Letter, Uppercase
* Ll Letter, Lowercase
* Lt Letter, Titlecase
......@@ -25,7 +26,7 @@
* Sk Symbol, Modifier
* So Symbol, Other
*
* Matches all character classes not in the list above (enclosing marks, punctuation and control codes, spacers).
* All character classes not in the list above (enclosing marks, punctuation, control codes and spacers):
* 'Me', 'Pc', 'Pd', 'Ps', 'Pe', 'Pi', 'Pf', 'Po', 'Zs', 'Zl', 'Zp', 'Cc', 'Cf', 'Cs', 'Co'
*/
define('PREG_CLASS_SEARCH_EXCLUDE', '\x{0}-\x{23}\x{25}-\x{2a}\x{2c}-\x{2f}\x{3a}\x{3b}\x{3f}\x{40}\x{5b}-\x{5d}\x{5f}\x{7b}\x{7d}\x{7f}-\x{a1}\x{ab}\x{ad}\x{b7}\x{bb}\x{bf}\x{37e}\x{387}\x{488}\x{489}\x{55a}-\x{55f}\x{589}\x{58a}\x{5be}\x{5c0}\x{5c3}\x{5f3}\x{5f4}\x{600}-\x{603}\x{60c}\x{60d}\x{61b}\x{61f}\x{66a}-\x{66d}\x{6d4}\x{6dd}\x{6de}\x{700}-\x{70d}\x{70f}\x{964}\x{965}\x{970}\x{df4}\x{e4f}\x{e5a}\x{e5b}\x{f04}-\x{f12}\x{f3a}-\x{f3d}\x{f85}\x{104a}-\x{104f}\x{10fb}\x{1361}-\x{1368}\x{166d}\x{166e}\x{1680}\x{169b}\x{169c}\x{16eb}-\x{16ed}\x{1735}\x{1736}\x{17b4}\x{17b5}\x{17d4}-\x{17d6}\x{17d8}-\x{17da}\x{1800}-\x{180a}\x{180e}\x{1944}\x{1945}\x{2000}-\x{2043}\x{2045}-\x{2051}\x{2053}\x{2054}\x{2057}\x{205f}-\x{2063}\x{206a}-\x{206f}\x{207d}\x{207e}\x{208d}\x{208e}\x{20dd}-\x{20e0}\x{20e2}-\x{20e4}\x{2329}\x{232a}\x{23b4}-\x{23b6}\x{2768}-\x{2775}\x{27e6}-\x{27eb}\x{2983}-\x{2998}\x{29d8}-\x{29db}\x{29fc}\x{29fd}\x{3000}-\x{3003}\x{3008}-\x{3011}\x{3014}-\x{301f}\x{3030}\x{303d}\x{30a0}\x{30fb}\x{d800}\x{db7f}\x{db80}\x{dbff}\x{dc00}\x{dfff}\x{e000}\x{f8ff}\x{fd3e}\x{fd3f}\x{fe30}-\x{fe52}\x{fe54}-\x{fe61}\x{fe63}\x{fe68}\x{fe6a}\x{fe6b}\x{feff}\x{ff01}-\x{ff03}\x{ff05}-\x{ff0a}\x{ff0c}-\x{ff0f}\x{ff1a}\x{ff1b}\x{ff1f}\x{ff20}\x{ff3b}-\x{ff3d}\x{ff3f}\x{ff5b}\x{ff5d}\x{ff5f}-\x{ff65}\x{fff9}-\x{fffb}\x{10100}\x{10101}\x{1039f}\x{1d173}-\x{1d17a}\x{e0001}\x{e0020}-\x{e007f}\x{f0000}\x{ffffd}\x{100000}');
......@@ -136,7 +137,6 @@ function search_admin() {
* too.
* @param $type
* (optional) The type of item to wipe.
*
*/
function search_wipe($sid = NULL, $type = NULL) {
if ($type == NULL && $sid == NULL) {
......@@ -287,6 +287,8 @@ function search_preprocess(&$text) {
*
* @param $text
* The content of this item. Must be a piece of HTML text.
*
* @ingroup search
*/
function search_index($sid, $type, $text) {
$minimum_word_size = variable_get('minimum_word_size', 3);
......@@ -399,9 +401,10 @@ function search_index($sid, $type, $text) {
/**
* Perform a search on a word or words.
*
* This function is called by each module that supports the indexed search.
* This function is called by each module that supports the indexed search
* (and thus, implements hook_update_index()).
*
* The end result is an SQL select on the search_index table. As a guide for
* The final query is an SQL select on the search_index table. As a guide for
* writing the optional extra SQL fragments (see below), use this query:
*
* SELECT i.type, i.sid, i.word, SUM(i.score/t.count) AS score
......@@ -427,6 +430,8 @@ function search_index($sid, $type, $text) {
*
* @return
* An array of SIDs for the search results.
*
* @ingroup search
*/
function do_search($keys, $type, $join = '', $where = '1') {
// Note, we replace the wildcards with U+FFFD (Replacement character) to pass
......@@ -533,27 +538,40 @@ function search_view() {
* 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.
*
* There are three ways to interact with the search system:
* - Specifically for searching nodes, you can implement nodeapi('update index')
* and nodeapi('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_nodeapi('view'). This is usually sufficient.
* You should only use this mechanism if you want additional, non-visible data
* to be indexed.
* - Implement hook_search(). This will create a search tab for your module on
* the /search page with a simple keyword search form. You may optionally
* implement hook_search_item() to customize the display of your results.
* - 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(). 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.
*/
/**
* Render a search form.
*
* This form must be usable not only within "http://example.com/search", but also
* as a simple search box (without "Restrict search to", help text, etc.), in the
* theme's header, and so forth. This means we must provide options to
* conditionally render certain parts of this form.
*
* @param $action
* Form action. Defaults to "search".
* @param $keys
* The search string entered by the user, containing keywords for the search.
* @param $options
* Whether to render the optional form fields and text ("Restrict search
* to", help text, etc.).
* @param $type
* The type of search to render the node for. Must be the name of module
* which implements hook_search(). Defaults to 'node'.
* @return
* An HTML string containing the search form.
*/
function search_form($action = '', $keys = '', $type = null, $options = FALSE) {
function search_form($action = '', $keys = '', $type = null) {
$edit = $_POST['edit'];
if (!$action) {
......@@ -598,10 +616,6 @@ function search_data($keys = NULL, $type = 'node') {
return $output;
}
/**
* @} End of "defgroup search".
*/
/**
* Returns snippets from a piece of text, with certain keywords highlighted.
* Used for formatting search results.
......@@ -707,6 +721,10 @@ function search_excerpt($keys, $text) {
return $text;
}
/**
* @} End of "defgroup search".
*/
/**
* Helper function for array_walk in search_except.
*/
......@@ -726,7 +744,9 @@ function _search_excerpt_replace($text) {
* Optionally, "extra" can be an array of extra info to show along with the
* result.
* @param $type
* The type of item found, such as "user" or "comment".
* The type of item found, such as "user" or "node".
*
* @ingroup themeable
*/
function theme_search_item($item, $type) {
if (module_hook($type, 'search_item')) {
......
......@@ -7,9 +7,10 @@
*/
/**
* Unicode character classes to include in the index.
* Matches Unicode character classes to exclude from the search index.
* See: http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values
*
* The index only contains the following character classes:
* Lu Letter, Uppercase
* Ll Letter, Lowercase
* Lt Letter, Titlecase
......@@ -25,7 +26,7 @@
* Sk Symbol, Modifier
* So Symbol, Other
*
* Matches all character classes not in the list above (enclosing marks, punctuation and control codes, spacers).
* All character classes not in the list above (enclosing marks, punctuation, control codes and spacers):
* 'Me', 'Pc', 'Pd', 'Ps', 'Pe', 'Pi', 'Pf', 'Po', 'Zs', 'Zl', 'Zp', 'Cc', 'Cf', 'Cs', 'Co'
*/
define('PREG_CLASS_SEARCH_EXCLUDE', '\x{0}-\x{23}\x{25}-\x{2a}\x{2c}-\x{2f}\x{3a}\x{3b}\x{3f}\x{40}\x{5b}-\x{5d}\x{5f}\x{7b}\x{7d}\x{7f}-\x{a1}\x{ab}\x{ad}\x{b7}\x{bb}\x{bf}\x{37e}\x{387}\x{488}\x{489}\x{55a}-\x{55f}\x{589}\x{58a}\x{5be}\x{5c0}\x{5c3}\x{5f3}\x{5f4}\x{600}-\x{603}\x{60c}\x{60d}\x{61b}\x{61f}\x{66a}-\x{66d}\x{6d4}\x{6dd}\x{6de}\x{700}-\x{70d}\x{70f}\x{964}\x{965}\x{970}\x{df4}\x{e4f}\x{e5a}\x{e5b}\x{f04}-\x{f12}\x{f3a}-\x{f3d}\x{f85}\x{104a}-\x{104f}\x{10fb}\x{1361}-\x{1368}\x{166d}\x{166e}\x{1680}\x{169b}\x{169c}\x{16eb}-\x{16ed}\x{1735}\x{1736}\x{17b4}\x{17b5}\x{17d4}-\x{17d6}\x{17d8}-\x{17da}\x{1800}-\x{180a}\x{180e}\x{1944}\x{1945}\x{2000}-\x{2043}\x{2045}-\x{2051}\x{2053}\x{2054}\x{2057}\x{205f}-\x{2063}\x{206a}-\x{206f}\x{207d}\x{207e}\x{208d}\x{208e}\x{20dd}-\x{20e0}\x{20e2}-\x{20e4}\x{2329}\x{232a}\x{23b4}-\x{23b6}\x{2768}-\x{2775}\x{27e6}-\x{27eb}\x{2983}-\x{2998}\x{29d8}-\x{29db}\x{29fc}\x{29fd}\x{3000}-\x{3003}\x{3008}-\x{3011}\x{3014}-\x{301f}\x{3030}\x{303d}\x{30a0}\x{30fb}\x{d800}\x{db7f}\x{db80}\x{dbff}\x{dc00}\x{dfff}\x{e000}\x{f8ff}\x{fd3e}\x{fd3f}\x{fe30}-\x{fe52}\x{fe54}-\x{fe61}\x{fe63}\x{fe68}\x{fe6a}\x{fe6b}\x{feff}\x{ff01}-\x{ff03}\x{ff05}-\x{ff0a}\x{ff0c}-\x{ff0f}\x{ff1a}\x{ff1b}\x{ff1f}\x{ff20}\x{ff3b}-\x{ff3d}\x{ff3f}\x{ff5b}\x{ff5d}\x{ff5f}-\x{ff65}\x{fff9}-\x{fffb}\x{10100}\x{10101}\x{1039f}\x{1d173}-\x{1d17a}\x{e0001}\x{e0020}-\x{e007f}\x{f0000}\x{ffffd}\x{100000}');
......@@ -136,7 +137,6 @@ function search_admin() {
* too.
* @param $type
* (optional) The type of item to wipe.
*
*/
function search_wipe($sid = NULL, $type = NULL) {
if ($type == NULL && $sid == NULL) {
......@@ -287,6 +287,8 @@ function search_preprocess(&$text) {
*
* @param $text
* The content of this item. Must be a piece of HTML text.
*
* @ingroup search
*/
function search_index($sid, $type, $text) {
$minimum_word_size = variable_get('minimum_word_size', 3);
......@@ -399,9 +401,10 @@ function search_index($sid, $type, $text) {
/**
* Perform a search on a word or words.
*
* This function is called by each module that supports the indexed search.
* This function is called by each module that supports the indexed search
* (and thus, implements hook_update_index()).
*
* The end result is an SQL select on the search_index table. As a guide for
* The final query is an SQL select on the search_index table. As a guide for
* writing the optional extra SQL fragments (see below), use this query:
*
* SELECT i.type, i.sid, i.word, SUM(i.score/t.count) AS score
......@@ -427,6 +430,8 @@ function search_index($sid, $type, $text) {
*
* @return
* An array of SIDs for the search results.
*
* @ingroup search
*/
function do_search($keys, $type, $join = '', $where = '1') {
// Note, we replace the wildcards with U+FFFD (Replacement character) to pass
......@@ -533,27 +538,40 @@ function search_view() {
* 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.
*
* There are three ways to interact with the search system:
* - Specifically for searching nodes, you can implement nodeapi('update index')
* and nodeapi('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_nodeapi('view'). This is usually sufficient.
* You should only use this mechanism if you want additional, non-visible data
* to be indexed.
* - Implement hook_search(). This will create a search tab for your module on
* the /search page with a simple keyword search form. You may optionally
* implement hook_search_item() to customize the display of your results.
* - 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(). 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.
*/
/**
* Render a search form.
*
* This form must be usable not only within "http://example.com/search", but also
* as a simple search box (without "Restrict search to", help text, etc.), in the
* theme's header, and so forth. This means we must provide options to
* conditionally render certain parts of this form.
*
* @param $action
* Form action. Defaults to "search".
* @param $keys
* The search string entered by the user, containing keywords for the search.
* @param $options
* Whether to render the optional form fields and text ("Restrict search
* to", help text, etc.).
* @param $type
* The type of search to render the node for. Must be the name of module
* which implements hook_search(). Defaults to 'node'.
* @return
* An HTML string containing the search form.
*/
function search_form($action = '', $keys = '', $type = null, $options = FALSE) {
function search_form($action = '', $keys = '', $type = null) {
$edit = $_POST['edit'];
if (!$action) {
......@@ -598,10 +616,6 @@ function search_data($keys = NULL, $type = 'node') {
return $output;
}
/**
* @} End of "defgroup search".
*/
/**
* Returns snippets from a piece of text, with certain keywords highlighted.
* Used for formatting search results.
......@@ -707,6 +721,10 @@ function search_excerpt($keys, $text) {
return $text;
}
/**
* @} End of "defgroup search".
*/
/**
* Helper function for array_walk in search_except.
*/
......@@ -726,7 +744,9 @@ function _search_excerpt_replace($text) {
* Optionally, "extra" can be an array of extra info to show along with the
* result.
* @param $type
* The type of item found, such as "user" or "comment".
* The type of item found, such as "user" or "node".
*
* @ingroup themeable
*/
function theme_search_item($item, $type) {
if (module_hook($type, 'search_item')) {
......
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