aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--mod/search/README.txt120
-rw-r--r--mod/search/index.php46
-rw-r--r--mod/search/start.php13
-rw-r--r--mod/search/views/default/search/layout.php11
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