From 9c0a913909e0b560ce5e2723098e233601e86903 Mon Sep 17 00:00:00 2001 From: brettp Date: Thu, 14 Jan 2010 02:42:27 +0000 Subject: Removed unnecessary view directories. Added option of overriding the default layout for search queries. Updated documentation reflecting those changes. Clarified some points in the documentation. git-svn-id: http://code.elgg.org/elgg/trunk@3807 36083f99-b078-4883-b0ff-0f9b5a30f544 --- mod/search/README.txt | 120 +++++++++++++++++++++-------- mod/search/index.php | 46 ++++++----- mod/search/start.php | 13 +++- mod/search/views/default/search/layout.php | 11 +++ 4 files changed, 137 insertions(+), 53 deletions(-) create mode 100644 mod/search/views/default/search/layout.php (limited to 'mod') diff --git a/mod/search/README.txt b/mod/search/README.txt index 301fe3d09..72172e073 100644 --- a/mod/search/README.txt +++ b/mod/search/README.txt @@ -1,4 +1,4 @@ -Full text search dev reference. +Full text search developer's reference. 1. OVERVIEW @@ -20,7 +20,7 @@ Full text search dev reference. annotations, or private data it must register a search hook itself. -2. SEARCH AND YOUR PLUGIN +2. SEARCH AND CUSTOM PLUGINS * To appear in search you must register your entity type and subtype by saying in your plugin's init function: @@ -36,9 +36,15 @@ Full text search dev reference. and you don't need a custom display, there is nothing else you need to do for your results to appear in search. If you would like more granular control of search, continue below. + +3.0 CONTROLLING SEARCH RESULTS + + * Search results can be controlled at a object:subtype level. + * You can specify your own search types by responding to a hook. + -3.1 CONTROLLING SEARCH -- ENTITIES +3.1 CONTROLLING SEARCH RESULTS - ENTITIES RETURNED * You can override the default search by responding to the search/type or search/type:subtype hook. Generally, you will be replying to @@ -48,14 +54,16 @@ Full text search dev reference. results are returned (but not FALSE, see below) a hook for search/type will be triggered. - * FALSE returned for any search hook will halt results for that type/subtype. + * FALSE returned for any search hook will halt results for that + type/subtype. * Register plugin hooks like this: - register_plugin_hook('search', 'object:my_subtype', 'my_subtype_search_hook'); + register_plugin_hook('search', 'object:my_subtype', + 'my_subtype_search_hook'); - * The hooked function is provided with details about the search query in $param. - These include: + * The hooked function is provided with details about the search query + in $param. These include: query offset limit @@ -88,7 +96,49 @@ Full text search dev reference. you need. -3.2 CONTROLLING SEARCH - ENTITY VIEWS +3.2 CONTROLLING SEARCH RESULTS - CUSTOM SEARCH + + * Non-entities, including information from 3rd party applications, + can easily be included in search by registering a custom search hook + that responds to the search_types/get_types trigger: + + register_plugin_hook('search_types', 'get_types', + 'my_custom_search_hook_function'); + + In this function, append to the array sent in $value with the name of + your custom search: + + function my_custom_search_hook_function($hook, $type, + $value, $params) { + $value[] = 'my_custom_search'; + return $value; + } + + Search will trigger a hook for search/my_custom_search, which your + plugin should respond to as detailed in section 3.1 above. + + +4.0 CONTROLLING SEARCH VIEWS + * Three types views are used for displaying search: entity, listing, + and layout. + + * Each view has a default that standardizes the display of entities + regardless of type, subtype, or search type. + + * The entity and listing views can be customized based upon a type, + subtype, or custom search type of the results. + + * The layout view can be customized based upon the original search + type. NB: This can be different to the types for the results. + + * The entity view controls how each individual result is formatted. + + * The listing view control how each group of listings is formatted. + + * The listing layout controls how each full result set is formatted. + + +4.1 CONTROLLING SEARCH VIEWS - ENTITIES * The default view for entities is search/entity. @@ -99,8 +149,8 @@ Full text search dev reference. found and passes to the entity view. See 3.3 for more information about listing views. - * Views are discovered in the following order. The first search view - found is used. + * Entity views are discovered in the following order. The first search + view found is used. search/type/subtype/entity (For entity-based searches only) search/type/entity search/entity @@ -120,15 +170,15 @@ Full text search dev reference. views/default/search/mysearch/entity.php -3.3 CONTROLLING SEARCH - LISTING VIEWS +4.2 CONTROLLING SEARCH VIEWS - LISTING * The default search view is search/listing. * For each entity in the returned array, search expects two pieces of volatile data: search_matched_title and search_matched_description. - * Views are discovered in the following order. The first search view - found is used. + * Listing views are discovered in the following order. The first + search view found is used. search/type/subtype/listing (For entity-based searches only) search/type/listing search/listing @@ -144,26 +194,32 @@ Full text search dev reference. To create a listing view for the custom search mysearch, create a file called: views/default/search/mysearch/listing.php + - -3.4 CONTROLLING SEARCH - CUSTOM SEARCH +4.3 CONTROLLING SEARCH VIEWS - LAYOUT - * Non-entities, including information from 3rd party applications, - can easily be included in search by registering a custom search hook - that responds to the search_types/get_types trigger: + * The default layout view for search is search/layout, which calls + to elgg_view_layout(two_column_left_sidebar', '', $entity_results); - register_plugin_hook('search_types', 'get_types', 'my_custom_search_hook_function'); - - In this function, append to the array sent in $value with the name of - your custom search: + * Layouts can be overridden only when not searching all entities. - function my_custom_search_hook_function($hook, $type, $value, $params) { - $value[] = 'my_custom_search'; - return $value; - } - - Search will trigger a hook for search/my_custom_search, which your - plugin should respond to as detailed in section 3.1 above. + * Layout views are discovered in the following order. The first search + view found is used. + search/type/subtype/layout (For entity-based searches only) + search/type/layout + search/layout + + * The following parameters are passed in $vars to the layout view: + body => The HTML formatted list of results. + params => The original params for the search. + + * Example: To create a layout view for ElggObjects with the subtype + of blog, create a file called: + views/default/search/object/blog/layout.php + + To create a layout view for the custom search mysearch, create a file + called: + views/default/search/mysearch/layout.php 4. HINTS @@ -176,8 +232,10 @@ Full text search dev reference. uses volatile data. $entity = new ElggObject(); $entity->owner_guid = use_magic_to_match_to_a_real_user(); - $entity->setVolatileData('search_matched_title', '3rd Party Integration'); - $entity->setVolatileData('search_matched_description', 'Searching is fun!'); + $entity->setVolatileData('search_matched_title', + '3rd Party Integration'); + $entity->setVolatileData('search_matched_description', + 'Searching is fun!'); return array( 'count' => $count, diff --git a/mod/search/index.php b/mod/search/index.php index 4f1aa3dbf..e92eee312 100644 --- a/mod/search/index.php +++ b/mod/search/index.php @@ -124,8 +124,9 @@ if (!$query) { $results_html = ''; if ($search_type == 'all' || $search_type == 'entities') { - // to pass the correct search type to the views - $params['search_type'] = 'entities'; + // to pass the correct current search type to the views + $current_params = $params; + $current_params['search_type'] = 'entities'; // foreach through types. // if a plugin returns FALSE for subtype ignore it. @@ -143,10 +144,10 @@ if ($search_type == 'all' || $search_type == 'entities') { if ($search_type != 'all' && $entity_subtype != $subtype) { continue; } - $params['subtype'] = $subtype; - $params['type'] = $type; + $current_params['subtype'] = $subtype; + $current_params['type'] = $type; - $entities = trigger_plugin_hook('search', "$type:$subtype", $params, NULL); + $entities = trigger_plugin_hook('search', "$type:$subtype", $current_params, NULL); if ($entities === FALSE) { // someone is saying not to display these types in searches. continue; @@ -156,12 +157,12 @@ if ($search_type == 'all' || $search_type == 'entities') { // no results and not hooked. use default type search. // don't change the params here, since it's really a different subtype. // Will be passed to elgg_get_entities(). - $results = trigger_plugin_hook('search', $type, $params, array()); + $results = trigger_plugin_hook('search', $type, $current_params, array()); } if (is_array($results['entities']) && $results['count']) { - if ($view = search_get_search_view($params, 'listing')) { - $results_html .= elgg_view($view, array('results' => $results, 'params' => $params)); + if ($view = search_get_search_view($current_params, 'listing')) { + $results_html .= elgg_view($view, array('results' => $results, 'params' => $current_params)); } } } @@ -169,18 +170,18 @@ if ($search_type == 'all' || $search_type == 'entities') { // pull in default type entities with no subtypes // @todo this might currently means "all entities regardless of subtype" - $params['type'] = $type; - $params['subtype'] = 0; + $current_params['type'] = $type; + $current_params['subtype'] = 0; - $results = trigger_plugin_hook('search', $type, $params, array()); + $results = trigger_plugin_hook('search', $type, $current_params, array()); if ($results === FALSE) { // someone is saying not to display these types in searches. continue; } if (is_array($results['entities']) && $results['count']) { - if ($view = search_get_search_view($params, 'listing')) { - $results_html .= elgg_view($view, array('results' => $results, 'params' => $params)); + if ($view = search_get_search_view($current_params, 'listing')) { + $results_html .= elgg_view($view, array('results' => $results, 'params' => $current_params)); } } } @@ -194,11 +195,12 @@ if ($search_type != 'entities' || $search_type == 'all') { continue; } - $params['search_type'] = $type; + $current_params = $params; + $current_params['search_type'] = $type; // custom search types have no subtype. - unset($params['subtype']); + unset($current_params['subtype']); - $results = trigger_plugin_hook('search', $type, $params, array()); + $results = trigger_plugin_hook('search', $type, $current_params, array()); if ($results === FALSE) { // someone is saying not to display these types in searches. @@ -206,8 +208,8 @@ if ($search_type != 'entities' || $search_type == 'all') { } if (is_array($results['entities']) && $results['count']) { - if ($view = search_get_search_view($params, 'listing')) { - $results_html .= elgg_view($view, array('results' => $results, 'params' => $params)); + if ($view = search_get_search_view($current_params, 'listing')) { + $results_html .= elgg_view($view, array('results' => $results, 'params' => $current_params)); } } } @@ -226,6 +228,12 @@ if (!$results_html) { $body .= $results_html; } -$layout = elgg_view_layout('two_column_left_sidebar', '', $body); +// this is passed the original params because we don't care what actually +// matched (which is out of date now anyway). +// we want to know what search type it is. +$layout_view = search_get_search_view($params, 'layout'); +$layout = elgg_view($layout_view, array('params' => $params, 'body' => $body)); + +$title = sprintf(elgg_echo('search:results'), "\"{$params['query']}\""); page_draw($title, $layout); diff --git a/mod/search/start.php b/mod/search/start.php index c54072b91..8e84a4144 100644 --- a/mod/search/start.php +++ b/mod/search/start.php @@ -321,13 +321,20 @@ function search_remove_ignored_words($query, $format = 'array') { * * @param array $results * @param array $params - * @param string $view_type = listing || entity + * @param string $view_type = listing, entity or listing * @return string */ function search_get_search_view($params, $view_type) { - if ($view_type != 'listing' && $view_type != 'entity') { - return FALSE; + switch ($view_type) { + case 'listing': + case 'entity': + case 'layout': + break; + + default: + return FALSE; } + $view_order = array(); // check if there's a special search listing view for this type:subtype diff --git a/mod/search/views/default/search/layout.php b/mod/search/views/default/search/layout.php new file mode 100644 index 000000000..f79cfee12 --- /dev/null +++ b/mod/search/views/default/search/layout.php @@ -0,0 +1,11 @@ +, The MITRE Corporation + * @link http://elgg.org/ + */ + +echo elgg_view_layout('two_column_left_sidebar', '', $vars['body']); \ No newline at end of file -- cgit v1.2.3