diff options
author | Dries Buytaert <dries@buytaert.net> | 2010-02-27 10:54:12 +0000 |
---|---|---|
committer | Dries Buytaert <dries@buytaert.net> | 2010-02-27 10:54:12 +0000 |
commit | 4717f28975c26ce3c1efa208c1ed4e3e69f1a7ad (patch) | |
tree | 1f7688302f9f8e33368d83f27d3380b7c0cac9c6 /modules/search | |
parent | 3cd6a773a1a1d0a269368c5cb14a812a56d15847 (diff) | |
download | brdo-4717f28975c26ce3c1efa208c1ed4e3e69f1a7ad.tar.gz brdo-4717f28975c26ce3c1efa208c1ed4e3e69f1a7ad.tar.bz2 |
- Patch #704866 by jhodgdon: search API doc has some problems.
Diffstat (limited to 'modules/search')
-rw-r--r-- | modules/search/search.api.php | 126 |
1 files changed, 68 insertions, 58 deletions
diff --git a/modules/search/search.api.php b/modules/search/search.api.php index a9327ac2c..408cff34f 100644 --- a/modules/search/search.api.php +++ b/modules/search/search.api.php @@ -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 */ |