Issue #1139282: Fixed undefined variable in admin UI.
[project/faceted_search.git] / README.txt
1
2 README file for the Faceted Search Drupal module.
3
4
5 Description
6 ***********
7
8 The Faceted Search module provides a search API and a search interface for
9 allowing users to browse content in such a way that they can rapidly get
10 acquainted with the scope and nature of the content, and never feel lost in the
11 data. More than a search interface, this is an information navigation and
12 discovery tool.
13
14 The interface exposes metadata in such a way that users can build their queries
15 as they go, refining or expanding the current query, with results automatically
16 reflecting the current query. This interface also combines free-text search,
17 fully leveraging Drupal's search engine. It avoids complex search forms, and
18 never offers facets that would lead to empty result sets.
19
20 The most obvious metadata for faceted searches is provided by Drupal's taxonomy
21 module. However, Faceted Search's API allows developers to expose other
22 metadata, therefore providing more more facets to users for browsing content.
23
24 Any of the following cases might prompt you to use Faceted Search:
25
26 - Users need to filter content using multiple taxonomy terms at the same time.
27
28 - Users want to combine text searches, taxonomy term filtering, and other search
29   criteria.
30
31 - Users don't know precisely what they can find on your site, or what to search
32   for.
33
34 - You want to hint users at related content they might not have thought of
35   looking for, but that could be of interest to them.
36
37 - You want to clearly show users what subject areas are the most comprehensive
38   on your site.
39
40 - You are trying to discover relationships or trends between contents.
41
42 - Your site has too much content for it to be displayed through fixed
43   navigational structures, but you still want it to be navigable.
44
45 - You want to use a faceted classification
46   [http://en.wikipedia.org/wiki/Faceted_classification] because a single
47   taxonomic order or a single folksonomy is not suitable or sufficient for your
48   content.
49
50 - Users often get empty result sets when searching your site.
51
52 - You think that "advanced" search forms are not fun to use.
53
54
55 The package
56 ***********
57
58 Faceted Search is in fact a bundle of modules.
59
60 - Faceted Search: Provides the search framework and API.
61
62 - Faceted Search UI: Provides the search user interface.
63
64 - Faceted Search Views: Allows to use Views to display the search results.
65
66 - Author Facet: Allows users to refine the current search based on content
67   author.
68
69 - Content Type Facet: Allows users to refine the current search based on content
70   type.
71
72 - Date Authored Facet: Allows users to refine the current search based on
73   content creation date.
74
75 - Taxonomy Facets: Allows users to search content through taxonomy. Any
76   vocabulary can become a facet that can be used to refine the current search.
77
78 - Field Keyword Filter: Allows to perform keyword searches restricted by field
79   (requires the Field Indexer module).
80
81 - Publishing Options Facets: Allows users to refine the current search based on
82   content publishing options (sticky, published, promoted to front page,
83   moderated). This is mostly useful in search environments built specifically
84   for site editors.
85
86 - Date Facets Format: Provides formatting options for date-based facets.
87
88 Hopefully, many more facets will be developed. The API is meant to make it easy
89 to implement new facets.
90
91
92 Caution
93 *******
94
95 Faceted Search is database-intensive. If your server can barely keep up with
96 your traffic, this package will make things worst. Make sure to benchmark
97 performance before deploying this system on a busy site or on a site with many
98 thousand nodes (more info: http://drupal.org/node/347952).
99
100
101 Requirements
102 ************
103
104 - Drupal 6.x (http://drupal.org/project/drupal).
105
106 - MySQL 4.1 (or later version). 
107
108 - PHP 5.1 (or later version).
109
110
111 Recommended modules
112 *******************
113
114 - CCK Facets (http://drupal.org/project/cck_facets)
115   Exposes Content Construction Kit (CCK) (http://drupal.org/project/cck) fields
116   as facets.
117
118 - Organic Group Facets (http://drupal.org/project/og_facets)
119   Exposes organic groups (http://drupal.org/project/og) as facets.
120
121 - Views (http://drupal.org/project/views): In combination with the Faceted
122   Search Views module, the Views module can give you tremendous flexibility for
123   displaying Faceted Search's results, and even for performing additional
124   filtering of the search results. See the "Views integration" topic below for
125   more details.
126
127 - Field Indexer (http://drupal.org/project/field_indexer): The Field Indexer
128   module indexes field data into Drupal's search index. Faceted Search's Field
129   Keyword Filter module relies on this data to let users perform keyword
130   searches restricted by field.
131
132 - jQuery Update (http://drupal.org/project/jquery_update): If you wish to use
133   Faceted Search UI's tooltips feature (for showing subcategories when hovering
134   over a category in the guided search), it is strongly recommended to install
135   the jQuery Update module. Make sure to read that module's installation
136   instructions. If you don't use the tooltips feature, Faceted Search UI won't
137   use jQuery at all, so in that case you would not need jQuery Update.
138
139 - Taxonomy hide (http://drupal.org/project/taxonomy_hide): If you use Faceted
140   Search UI's Related Categories block, you might want to remove Drupal's
141   default terms listing when viewing a node. You could do that from your site's
142   theme, but another way could be to use the Taxonomy hide module.
143
144
145 Known incompatibilities
146 ***********************
147
148 - PostgreSQL: PostgreSQL has not actually been tested at this point. Also, the
149   Date Authored Facet module uses some MySQL-specific functions.  Feel free to
150   share patches to support PostgreSQL (or any other database). :-)
151   See http://drupal.org/node/230471 for updates, and remember that you can help
152   make PostgreSQL support happen!
153
154
155 Installation
156 ************
157
158 1. When using MySQL, in addition to the database permissions already required by
159    Drupal, you will also need to grant your database user the LOCK TABLES and
160    the CREATE TEMPORARY TABLES permissions. To grant those permissions, you need
161    to login to your database:
162
163      mysql -u username -p
164
165    You will be asked for the 'username' database password. Then, at the MySQL
166    prompt, enter the following command:
167
168     GRANT LOCK TABLES, CREATE TEMPORARY TABLES
169     ON databasename.*
170     TO 'username'@'localhost';
171
172    where
173
174      'databasename' is the name of your database
175      'username@localhost' is the username of your MySQL account
176
177    Note: Unless your database user has the privileges listed above, you will not
178    be able to have Faceted Search work properly.
179
180    If successful, MySQL will reply with:
181
182      Query OK, 0 rows affected
183
184    Then enter the following command:
185
186      quit;
187
188 2. Extract the 'faceted_search' module directory, including all its
189    subdirectories, into your Drupal modules directory.
190
191 3. Go to the Administer > Site building > Modules page, and enable the following
192    modules:
193
194    - Faceted Search
195    - Faceted Search UI
196    - At least one of the following modules (which are provided with Faceted
197      Search). Technically, you could use Faceted Search without any of these,
198      but there would not be much benefit over Drupal's standard search:
199      - Author Facet
200      - Content Type Facet
201      - Date Authored Facet
202      - Taxonomy Facets
203      - Field Keyword Filter
204    - Search (Drupal core module)
205    - Taxonomy (Drupal core module -- only needed if you intend to use Taxonomy Facets)
206
207 4. Go to the Administer > Site configuration > Faceted Search page, and click
208    the Add Environment tab.
209
210 5. Define a faceted search environment by filling the "Add a faceted search
211    environment" form. Hopefully it is self-explanatory enough, but don't be
212    afraid to experiment. You can always change any of the settings later.
213
214    Click Save to save the new environment. This takes you back to the 
215    Administer > Site configuration > Faceted Search page.
216
217 6. Go to the Administer > Site building > Blocks page, and enable the following
218    blocks (where my_search is the name of the faceted search environment you
219    have just created):
220
221    - my_search / Current search
222    - my_search / Keyword search
223    - my_search / Guided search
224    - my_search / Related categories
225    - my_search / Sort options
226
227    Use Weight to order the blocks. Having the Current search block located above
228    the Keyword search and Guided search blocks is generally most intuitive for
229    users.
230
231    When using multiple faceted search environments, you'll want to configure the
232    block visibility to avoid showing multiple Keyword search or Guided search
233    blocks at the same time. The most common setting is to have those blocks
234    visible only on your search environment's base path.
235
236    To do so, in Administer > Site building > Blocks, click Configure next to the
237    Keyword search or Guided search block whose visibility is to be adjusted.
238    Select "Show on every page except the listed pages", then enter the following
239    paths in the Pages field:
240
241    base_path
242    base_path/*
243
244    ... where "base_path" should be replaced with your search environment's
245    actual base path.
246
247 7. Go to the Administer > User management > Access control page, and grant the
248    "use faceted search" permission to the roles you intend to give access to
249    faceted search.
250
251
252 Views integration
253 *****************
254
255 With the Faceted Search Views module, you may use the Views module to display
256 and further filter search results.
257
258 This system replaces the results page with an embedded view that gets passed the
259 current search environment as an argument. That argument gets processed by
260 Faceted Search Views itself through Views' hook_views_query_alter(). You don't
261 need to configure any particular arguments in your view.
262
263 The main requirements for a view to be eligible for use with Faceted Search are:
264
265 - Must be a Node view.
266 - Must use a pager.
267 - Must be enabled.
268
269 To use a view to display search results, go to Administer > Site configuration >
270 Faceted search, edit your faceted search environment, then select the desired
271 view in the "Display style" field of the "Results page" section.
272
273
274 Known limitations:
275
276 - Only a view's default display can be used (other displays are ignored).
277 - The view cannot use exposed filters or arguments.
278 - The view's "Title" and "Empty text" settings are ignored.
279 - If the view is set to have an unlimited number of items per page, instead of
280   having no limit the system's default limit will be used (per Administer >
281   Content management > Post settings > Number of posts on main page).
282
283
284 Known issues:
285
286 - If your site is using table prefixing, you will need to tell Drupal not to
287   prefix temporary tables needed by Faceted Search Views. In settings.php, you
288   need something like the following:
289
290     $db_prefix = array(
291       'default' => '[your_default_prefix]_',
292       'temp_faceted_search_results_[env_id]' => '',
293     );
294
295   You will need as many 'temp_faceted_search_results_[env_id]' entries as there
296   are faceted search environments (env_id is the numeric identifier for the
297   faceted search environment, to be specified without the brackets). You can
298   find out the env_id by editing an environment and looking at its administration
299   URL, which has a path in the form 'admin/settings/faceted_search/[env_id]'.
300
301   Reference: http://drupal.org/node/227634#comment-864171.
302
303
304 Multilanguage support
305 *********************
306
307 Multilanguage support in Faceted Search relies on the Internationalization
308 module (http://drupal.org/project/i18n).
309
310 With Taxonomy Facets, if a vocabulary uses the 'Localize terms' translation
311 mode, then the system will display the localized version of the vocabulary's
312 name and its term names for the current language.
313
314
315 Upgrading from Drupal 5.x
316 *************************
317
318 Before upgrading your site and Faceted Search from Drupal 5 to Drupal 6, make
319 sure that your site is using the latest version of Faceted Search for Drupal
320 5.x. If this is not the case, then you will have to perform this update as a
321 separate step *before* updating to Drupal 6.
322
323 Note that Faceted Search Views for Drupal 6 no longer needs an argument (which
324 was called "Faceted Search: Environment ID") to be added to your views. After
325 the upgrade to Drupal 6, you will have to remove any remnants of that argument
326 from your views.
327
328
329 Support
330 *******
331
332 For support requests, bug reports, and feature requests, please use Faceted
333 Search's issue queue on http://drupal.org/project/issues/faceted_search.
334
335 Please DO NOT send bug reports through e-mail or personal contact forms, use the
336 aforementioned issue queue instead.
337
338 For general discussions about Faceted Search (or other Drupal search solutions),
339 you are invited to join the Search group on http://groups.drupal.org/node/4102.
340
341
342 Credits
343 *******
344
345 - Project initiated by David Lesieur (http://davidlesieur.com,
346   http://drupal.org/user/17157).
347
348 - Sponsored in part by Laboratoire NT2 (http://www.labo-nt2.uqam.ca), Eyos BV
349   (http://www.eyos.nl), and CAIS Institute (http://caisinstitute.org).
350
351 - The superb Flamenco search interface (http://flamenco.berkeley.edu) has
352   provided much inspiration for this project.