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

4 files changed, 137 insertions, 53 deletions

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 @@
+<?php
+/**
+   * Elgg core search listing.
+   *
+   * @package Elgg
+   * @subpackage Core
+   * @author Curverider Ltd <info@elgg.com>, The MITRE Corporation <http://www.mitre.org>
+   * @link http://elgg.org/
+   */
+
+echo elgg_view_layout('two_column_left_sidebar', '', $vars['body']);
\ No newline at end of file