1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
Full text search dev reference.
1. OVERVIEW
* All entities are searched through title and description using
MySQL's native fulltext search when possible, and LIKE %...% when not.
This can be overridden on a type/subtype basis.
* Entities are displayed in a standard list view consisting of a
title, blurb, and icon of the owning entity. This can be overridden
on a type/subtype basis.
* Search is separated based upon types/subtypes pairs and any
registered custom search.
* METADATA, ANNOTATIONS, AND PRIVATE DATA ARE NOT SEARCHED.
These are used in a variety of ways by plugin authors and generally
should not be displayed. There are exceptions (profile fields and
comments) but if a plugin needs to match against metadata,
annotations, or private data it must register a search hook itself.
2. SEARCH AND YOUR PLUGIN
* To appear in search you must register your entity type and subtype
by saying in your plugin's init function:
register_entity_type($type, $subtype);
If you are extending ElggObject with your own class, it is also advised
to add a subtype in your plugin's run_once function by saying:
add_subtype($type, $subtype, $class);
* If your plugin uses ElggEntity's standard title and description,
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.1 CONTROLLING SEARCH -- ENTITIES
* You can override the default search by responding to the search/type
or search/type:subtype hook. Generally, you will be replying to
search/object:subtype.
* Search will first trigger a hook for search/type:subtype. If no
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.
* Register plugin hooks like this:
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:
query
offset
limit
search_type
type - Entity type. (Not applicable for custom searches)
subtype - Entity subtype. (Not applicable for custom searches)
owner_guid
friends - Should only entities by friends of the logged in
user be searched? (@todo)
pagination - Show pagination?
* The hooked function should respond to search triggers with the
following:
array(
'count' => A count of ALL entities found,
'entities' => An array of entities.
)
This information is passed directly to the search view, so if you are
registering your own custom hook, you can provide more
information to display in your custom view.
* For each entity in the returned array, search expects two pieces of
volatile data: search_matched_title and search_matched_description.
Set these by saying:
$entity->setVolatileData('data_name', 'data_value');
Again, if you are customizing your search views, you can add anything
you need.
3.2 CONTROLLING SEARCH - ENTITY VIEWS
* The default view for entities is search/entity.
* Search views are separate from the object/entity views because
view types might not match entity types.
* The default search listing view iterates through each entity
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.
search/type/subtype/entity (For entity-based searches only)
search/type/entity
search/entity
* The following parameters are passed in $vars to the entity view by
the default listing view:
entity => The current returned entity
results => The results from the search/type:subtype hook
params => The params passed to the search/type:subtype hook
* Example: To create an entity view for an ElggObject of subtype blog,
create a file called:
views/default/search/object/blog/entity.php
To create an entity view for a custom search mysearch, create a file
called:
views/default/search/mysearch/entity.php
3.3 CONTROLLING SEARCH - LISTING VIEWS
* 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.
search/type/subtype/listing (For entity-based searches only)
search/type/listing
search/listing
* The view is called with the following in $vars:
results => The results from the search/type:subtype hook
params => The params passed to the search/type:subtype hook
* Example: To create a listing view for ElggObjects with the subtype
of blog, create a file called:
views/default/search/object/blog/listing.php
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
* 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. HINTS
* Use search_get_relevant_substring() to extract and highlight
relevant substrings for the search_match_title and description.
* If searching in 3rd party applications, create a temporary
ElggObject to hold the results. No need to save it since search
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!');
return array(
'count' => $count,
'entities' => array($entity)
);
|
