Commit 4717f289 authored by Dries's avatar Dries
Browse files

- Patch #704866 by jhodgdon: search API doc has some problems.

parent 3cd6a773
......@@ -12,25 +12,22 @@
*/
/**
* Define a custom search routine.
* Define a custom search type.
*
* This hook allows a module 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 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.
*
* Note that you can use form API to extend the search. You will need to use
* hook_form_alter() to add any additional required form elements. You can
* process their values on submission using a custom validation function.
* You will need to merge any custom search values into the search keys
* using a key:value syntax. This allows all search queries to have a clean
* and permanent URL. See node_form_search_form_alter() for an example.
*
* You can also alter the display of your module's search results
* by implementing hook_search_page().
*
* The example given here is for node.module, which uses the indexed search
* capabilities. To do this, node module also implements hook_update_index()
* which is used to create and maintain the index.
* 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_update_index(). If your search type has settings, you can implement
* hook_search_admin() to add them to the search settings page. You can also
* alter the display of your module's search results by implementing
* hook_search_page(). And you can use hook_form_FORM_ID_alter(), with
* FORM_ID set to 'search', to add fields to the search form. See
* node_form_search_form_alter() for an example.
*
* @return
* Array with the optional keys 'title' for the tab title and 'path' for
......@@ -49,7 +46,7 @@ function hook_search_info() {
/**
* Define access to a custom search routine.
*
* This hook allows a module to deny access to a user to a search tab.
* This hook allows a module to define permissions for a search tab.
*
* @ingroup search
*/
......@@ -58,9 +55,9 @@ function hook_search_access() {
}
/**
* The search index is going to be rebuilt.
* Take action when the search index is going to be rebuilt.
*
* Modules which use hook_update_index() should update their indexing
* 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.
*
......@@ -90,10 +87,10 @@ function hook_search_status() {
}
/**
* Add elements to the search administration form.
* Add elements to the search settings form.
*
* @return
* The form array for the Search settings page at admin/config/search/settings.
* Form array for the Search settings page at admin/config/search/settings.
*
* @ingroup search
*/
......@@ -124,8 +121,21 @@ function hook_search_admin() {
/**
* Execute a search for a set of key words.
*
* We call do_search() with the keys, the module name, and extra SQL fragments
* to use when searching. See hook_update_index() for more information.
* Use database API with the 'PagerDefault' query extension to perform your
* search.
*
* If your module uses hook_update_index() and search_index() to index its
* items, use table 'search_index' aliased to 'i' as the main table in your
* query, with the 'SearchQuery' extension. You can join to your module's table
* using the 'i.sid' field, which will contain the $sid values you provided to
* search_index(). Add the main keywords to the query by using method
* searchExpression(). The functions search_expression_extract() and
* search_expression_insert() may also be helpful for adding custom search
* parameters to the search expression.
*
* See node_execute_search() for an example of a module that uses the search
* index, and user_execute_search() for an example that doesn't ues the search
* index.
*
* @param $keys
* The search keywords as entered by the user.
......@@ -146,7 +156,7 @@ function hook_search_admin() {
*/
function hook_search_execute($keys = NULL) {
// Build matching conditions
$query = db_search()->extend('PagerDefault');
$query = db_select('search_index', 'i', array('target' => 'slave'))->extend('SearchQuery')->extend('PagerDefault');
$query->join('node', 'n', 'n.nid = i.sid');
$query
->condition('n.status', 1)
......@@ -211,18 +221,17 @@ function hook_search_execute($keys = NULL) {
*
* A module that implements hook_search() 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').
* 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 a definition
* list. So your hook_search_page() implementation should probably do
* this as well.
* Note that by default, theme('search_results') and theme('search_result')
* work together to create a definition list (DL). 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
* An HTML string containing the formatted search results, with
* a pager included.
......@@ -240,21 +249,26 @@ function hook_search_page($results) {
}
/**
* Preprocess text for the search index.
* Preprocess text for search.
*
* This hook is called both for text added to the search index, as well as
* This hook is called to preprocess both the text added to the search index and
* the keywords users have submitted for searching.
*
* This is required for example to allow Japanese or Chinese text to be
* searched. As these languages do not use spaces, it needs to be split into
* separate words before it can be indexed. There are various external
* libraries for this.
* Possible uses:
* - Adding spaces between words of Chinese or Japanese text.
* - Stemming words down to their root words to allow matches between, for
* instance, walk, walked, walking, and walks in searching.
* - Expanding abbreviations and acronymns that occur in text.
*
* @param $text
* The text to split. This is a single piece of plain-text that was
* extracted from between two HTML tags. Will not contain any HTML entities.
* The text to preprocess. This is a single piece of plain text extracted
* from between two HTML tags or from the search query. It will not contain
* any HTML entities or HTML tags.
*
* @return
* The text after processing.
* 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
*/
......@@ -264,26 +278,22 @@ function hook_search_preprocess($text) {
}
/**
* Update Drupal's full-text index for this module.
*
* Modules can implement this hook if they want to use the full-text indexing
* mechanism in Drupal.
*
* This hook is called every cron run if search.module is enabled. A module
* should check which of its items were modified or added since the last
* run. It is advised that you implement a throttling mechanism which indexes
* at most 'search_cron_limit' items per run (see example below).
* Update the search index for this module.
*
* You should also be aware that indexing may take too long and be aborted if
* there is a PHP time limit. That's why you should update your internal
* bookkeeping multiple times per run, preferably after every item that
* is indexed.
* This hook is called every cron run if 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
* built-in search index using search_index(), or to add them to your module's
* own indexing mechanism.
*
* Per item that needs to be indexed, you should call search_index() with
* its content as a single HTML string. The search indexer will analyse the
* HTML and use it to assign higher weights to important words (such as
* titles). It will also check for links that point to nodes, and use them to
* boost the ranking of the target nodes.
* When implementing this hook, your module should index content items that
* were modified or added since the last run. PHP has a time limit
* for cron, though, so it is advisable to limit how many items you index
* per run using variable_get('search_cron_limit') (see example below). Also,
* since the cron run could time out and abort in the middle of your run, you
* should update your module's internal bookkeeping on when items have last
* been indexed as you go rather than waiting to the end of indexing.
*
* @ingroup search
*/
......
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