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 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 89 insertions(+), 31 deletions(-) (limited to 'mod/search/README.txt') 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, -- cgit v1.2.3