modules/faceted_search/README.txt

$Id: README.txt,v 1.48 2009/05/05 01:29:28 davidlesieur Exp $

README file for the Faceted Search Drupal module.


Description
***********

The Faceted Search module provides a search API and a search interface for
allowing users to browse content in such a way that they can rapidly get
acquainted with the scope and nature of the content, and never feel lost in the
data. More than a search interface, this is an information navigation and
discovery tool.

The interface exposes metadata in such a way that users can build their queries
as they go, refining or expanding the current query, with results automatically
reflecting the current query. This interface also combines free-text search,
fully leveraging Drupal's search engine. It avoids complex search forms, and
never offers facets that would lead to empty result sets.

The most obvious metadata for faceted searches is provided by Drupal's taxonomy
module. However, Faceted Search's API allows developers to expose other
metadata, therefore providing more more facets to users for browsing content.

Any of the following cases might prompt you to use Faceted Search:

- Users need to filter content using multiple taxonomy terms at the same time.

- Users want to combine text searches, taxonomy term filtering, and other search
  criteria.

- Users don't know precisely what they can find on your site, or what to search
  for.

- You want to hint users at related content they might not have thought of
  looking for, but that could be of interest to them.

- You want to clearly show users what subject areas are the most comprehensive
  on your site.

- You are trying to discover relationships or trends between contents.

- Your site has too much content for it to be displayed through fixed
  navigational structures, but you still want it to be navigable.

- You want to use a faceted classification
  [http://en.wikipedia.org/wiki/Faceted_classification] because a single
  taxonomic order or a single folksonomy is not suitable or sufficient for your
  content.

- Users often get empty result sets when searching your site.

- You think that "advanced" search forms are not fun to use.


The package
***********

Faceted Search is in fact a bundle of modules.

- Faceted Search: Provides the search framework and API.

- Faceted Search UI: Provides the search user interface.

- Faceted Search Views: Allows to use Views to display the search results.

- Author Facet: Allows users to refine the current search based on content
  author.

- Content Type Facet: Allows users to refine the current search based on content
  type.

- Date Authored Facet: Allows users to refine the current search based on
  content creation date.

- Taxonomy Facets: Allows users to search content through taxonomy. Any
  vocabulary can become a facet that can be used to refine the current search.

- Field Keyword Filter: Allows to perform keyword searches restricted by field
  (requires the Field Indexer module).

- Publishing Options Facets: Allows users to refine the current search based on
  content publishing options (sticky, published, promoted to front page,
  moderated). This is mostly useful in search environments built specifically
  for site editors.

- Date Facets Format: Provides formatting options for date-based facets.

Hopefully, many more facets will be developed. The API is meant to make it easy
to implement new facets.


Caution
*******

Faceted Search is database-intensive. If your server can barely keep up with
your traffic, this package will make things worst. Make sure to benchmark
performance before deploying this system on a busy site or on a site with many
thousand nodes (more info: http://drupal.org/node/347952).


Requirements
************

- Drupal 6.x (http://drupal.org/project/drupal).

- MySQL 4.1 (or later version). 

- PHP 5.1 (or later version).


Recommended modules
*******************

- CCK Facets (http://drupal.org/project/cck_facets)
  Exposes Content Construction Kit (CCK) (http://drupal.org/project/cck) fields
  as facets.

- Organic Group Facets (http://drupal.org/project/og_facets)
  Exposes organic groups (http://drupal.org/project/og) as facets.

- Views (http://drupal.org/project/views): In combination with the Faceted
  Search Views module, the Views module can give you tremendous flexibility for
  displaying Faceted Search's results, and even for performing additional
  filtering of the search results. See the "Views integration" topic below for
  more details.

- Field Indexer (http://drupal.org/project/field_indexer): The Field Indexer
  module indexes field data into Drupal's search index. Faceted Search's Field
  Keyword Filter module relies on this data to let users perform keyword
  searches restricted by field.

- jQuery Update (http://drupal.org/project/jquery_update): If you wish to use
  Faceted Search UI's tooltips feature (for showing subcategories when hovering
  over a category in the guided search), it is strongly recommended to install
  the jQuery Update module. Make sure to read that module's installation
  instructions. If you don't use the tooltips feature, Faceted Search UI won't
  use jQuery at all, so in that case you would not need jQuery Update.

- Taxonomy hide (http://drupal.org/project/taxonomy_hide): If you use Faceted
  Search UI's Related Categories block, you might want to remove Drupal's
  default terms listing when viewing a node. You could do that from your site's
  theme, but another way could be to use the Taxonomy hide module.


Known incompatibilities
***********************

- PostgreSQL: PostgreSQL has not actually been tested at this point. Also, the
  Date Authored Facet module uses some MySQL-specific functions.  Feel free to
  share patches to support PostgreSQL (or any other database). :-)
  See http://drupal.org/node/230471 for updates, and remember that you can help
  make PostgreSQL support happen!


Installation
************

1. When using MySQL, in addition to the database permissions already required by
   Drupal, you will also need to grant your database user the LOCK TABLES and
   the CREATE TEMPORARY TABLES permissions. To grant those permissions, you need
   to login to your database:

     mysql -u username -p

   You will be asked for the 'username' database password. Then, at the MySQL
   prompt, enter the following command:

    GRANT LOCK TABLES, CREATE TEMPORARY TABLES
    ON databasename.*
    TO 'username'@'localhost';

   where

     'databasename' is the name of your database
     'username@localhost' is the username of your MySQL account

   Note: Unless your database user has the privileges listed above, you will not
   be able to have Faceted Search work properly.

   If successful, MySQL will reply with:

     Query OK, 0 rows affected

   Then enter the following command:

     quit;

2. Extract the 'faceted_search' module directory, including all its
   subdirectories, into your Drupal modules directory.

3. Go to the Administer > Site building > Modules page, and enable the following
   modules:

   - Faceted Search
   - Faceted Search UI
   - At least one of the following modules (which are provided with Faceted
     Search). Technically, you could use Faceted Search without any of these,
     but there would not be much benefit over Drupal's standard search:
     - Author Facet
     - Content Type Facet
     - Date Authored Facet
     - Taxonomy Facets
     - Field Keyword Filter
   - Search (Drupal core module)
   - Taxonomy (Drupal core module -- only needed if you intend to use Taxonomy Facets)

4. Go to the Administer > Site configuration > Faceted Search page, and click
   the Add Environment tab.

5. Define a faceted search environment by filling the "Add a faceted search
   environment" form. Hopefully it is self-explanatory enough, but don't be
   afraid to experiment. You can always change any of the settings later.

   Click Save to save the new environment. This takes you back to the 
   Administer > Site configuration > Faceted Search page.

6. Go to the Administer > Site building > Blocks page, and enable the following
   blocks (where my_search is the name of the faceted search environment you
   have just created):

   - my_search / Current search
   - my_search / Keyword search
   - my_search / Guided search
   - my_search / Related categories
   - my_search / Sort options

   Use Weight to order the blocks. Having the Current search block located above
   the Keyword search and Guided search blocks is generally most intuitive for
   users.

   When using multiple faceted search environments, you'll want to configure the
   block visibility to avoid showing multiple Keyword search or Guided search
   blocks at the same time. The most common setting is to have those blocks
   visible only on your search environment's base path.

   To do so, in Administer > Site building > Blocks, click Configure next to the
   Keyword search or Guided search block whose visibility is to be adjusted.
   Select "Show on every page except the listed pages", then enter the following
   paths in the Pages field:

   base_path
   base_path/*

   ... where "base_path" should be replaced with your search environment's
   actual base path.

7. Go to the Administer > User management > Access control page, and grant the
   "use faceted search" permission to the roles you intend to give access to
   faceted search.


Views integration
*****************

With the Faceted Search Views module, you may use the Views module to display
and further filter search results.

This system replaces the results page with an embedded view that gets passed the
current search environment as an argument. That argument gets processed by
Faceted Search Views itself through Views' hook_views_query_alter(). You don't
need to configure any particular arguments in your view.

The main requirements for a view to be eligible for use with Faceted Search are:

- Must be a Node view.
- Must use a pager.
- Must be enabled.

To use a view to display search results, go to Administer > Site configuration >
Faceted search, edit your faceted search environment, then select the desired
view in the "Display style" field of the "Results page" section.


Known limitations:

- Only a view's default display can be used (other displays are ignored).
- The view cannot use exposed filters or arguments.
- The view's "Title" and "Empty text" settings are ignored.
- If the view is set to have an unlimited number of items per page, instead of
  having no limit the system's default limit will be used (per Administer >
  Content management > Post settings > Number of posts on main page).


Known issues:

- If your site is using table prefixing, you will need to tell Drupal not to
  prefix temporary tables needed by Faceted Search Views. In settings.php, you
  need something like the following:

    $db_prefix = array(
      'default' => '[your_default_prefix]_',
      'temp_faceted_search_results_[env_id]' => '',
    );

  You will need as many 'temp_faceted_search_results_[env_id]' entries as there
  are faceted search environments (env_id is the numeric identifier for the
  faceted search environment, to be specified without the brackets). You can
  find out the env_id by editing an environment and looking at its administration
  URL, which has a path in the form 'admin/settings/faceted_search/[env_id]'.

  Reference: http://drupal.org/node/227634#comment-864171.


Multilanguage support
*********************

Multilanguage support in Faceted Search relies on the Internationalization
module (http://drupal.org/project/i18n).

With Taxonomy Facets, if a vocabulary uses the 'Localize terms' translation
mode, then the system will display the localized version of the vocabulary's
name and its term names for the current language.


Upgrading from Drupal 5.x
*************************

Before upgrading your site and Faceted Search from Drupal 5 to Drupal 6, make
sure that your site is using the latest version of Faceted Search for Drupal
5.x. If this is not the case, then you will have to perform this update as a
separate step *before* updating to Drupal 6.

Note that Faceted Search Views for Drupal 6 no longer needs an argument (which
was called "Faceted Search: Environment ID") to be added to your views. After
the upgrade to Drupal 6, you will have to remove any remnants of that argument
from your views.


Support
*******

For support requests, bug reports, and feature requests, please use Faceted
Search's issue queue on http://drupal.org/project/issues/faceted_search.

Please DO NOT send bug reports through e-mail or personal contact forms, use the
aforementioned issue queue instead.

For general discussions about Faceted Search (or other Drupal search solutions),
you are invited to join the Search group on http://groups.drupal.org/node/4102.


Credits
*******

- Project initiated by David Lesieur (http://davidlesieur.com,
  http://drupal.org/user/17157).

- Sponsored in part by Laboratoire NT2 (http://www.labo-nt2.uqam.ca), Eyos BV
  (http://www.eyos.nl), and CAIS Institute (http://caisinstitute.org).

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