126 lines
5.2 KiB
Plaintext
126 lines
5.2 KiB
Plaintext
Search facets
|
||
-------------
|
||
|
||
This module allows you to create facetted searches for any search executed via
|
||
the Search API, no matter if executed by a search page, a view or any other
|
||
module. The only thing you'll need is a search service class that supports the
|
||
"search_api_facets" feature. Currently, the "Database search" and "Solr search"
|
||
modules supports this.
|
||
|
||
This module is built on the Facet API [1], which is needed for this module to
|
||
work.
|
||
|
||
[1] http://drupal.org/project/facetapi
|
||
|
||
|
||
Information for site builders
|
||
-----------------------------
|
||
|
||
For creating a facetted search, you first need a search. Create or find some
|
||
page displaying Search API search results, either via a search page, a view or
|
||
by any other means. Now go to the configuration page for the index on which
|
||
this search is executed.
|
||
If the index lies on a server supporting facets (and if this module is enabled),
|
||
you'll notice a "Facets" tab. Click it and it will take you to the index' facet
|
||
configuration page. You'll see a table containing all indexed fields and options
|
||
for enabling and configuring facets for them.
|
||
For a detailed explanation of the available options, please refer to the Facet
|
||
API documentation.
|
||
|
||
- Creating facets via the URL
|
||
|
||
Facets can be added to a search (for which facets are activated) by passing
|
||
appropriate GET parameters in the URL. Assuming you have an indexed field with
|
||
the machine name "field_price", you can filter on it in the following ways:
|
||
|
||
- Filter for a specific value. For finding only results that have a price of
|
||
exactly 100, pass the following $options to url() or l():
|
||
|
||
$options['query']['f'][] = 'field_price:100';
|
||
|
||
Or manually append the following GET parameter to a URL:
|
||
|
||
?f[0]=field_price:100
|
||
|
||
- Search for values in a specified range. The following example will only return
|
||
items that have a price greater than or equal to 100 and lower than 500.
|
||
|
||
Code: $options['query']['f'][] = 'field_price:[100 TO 500]';
|
||
URL: ?f[0]=field_price%3A%5B100%20TO%20500%5D
|
||
|
||
- Search for values above a value. The next example will find results which have
|
||
a price greater than or equal to 100. The asterisk (*) stands for "unlimited",
|
||
meaning that there is no upper limit. Filtering for values lower than a
|
||
certain value works equivalently.
|
||
|
||
Code: $options['query']['f'][] = 'field_price:[100 TO *]';
|
||
URL: ?f[0]=field_price%3A%5B100%20TO%20%2A%5D
|
||
|
||
- Search for missing values. This example will filter out all items which have
|
||
any value at all in the price field, and will therefore only list items on
|
||
which this field was omitted. (This naturally only makes sense for fields
|
||
that aren't required.)
|
||
|
||
Code: $options['query']['f'][] = 'field_price:!';
|
||
URL: ?f[0]=field_price%3A%21
|
||
|
||
- Search for present values. The following example will only return items which
|
||
have the price field set (regardless of the actual value). You can see that it
|
||
is actually just a range filter with unlimited lower and upper bound.
|
||
|
||
Code: $options['query']['f'][] = 'field_price:[* TO *]';
|
||
URL: ?f[0]=field_price%3A%5B%2A%20TO%20%2A%5D
|
||
|
||
Note: When filtering a field whose machine name contains a colon (e.g.,
|
||
"author:roles"), you'll have to additionally URL-encode the field name in these
|
||
filter values:
|
||
Code: $options['query']['f'][] = rawurlencode('author:roles') . ':100';
|
||
URL: ?f[0]=author%253Aroles%3A100
|
||
|
||
- Issues
|
||
|
||
If you find any bugs or shortcomings while using this module, please file an
|
||
issue in the project's issue queue [1], using the "Facets" component.
|
||
|
||
[1] http://drupal.org/project/issues/search_api
|
||
|
||
|
||
Information for developers
|
||
--------------------------
|
||
|
||
- Features
|
||
|
||
If you are the developer of a SearchApiServiceInterface implementation and want
|
||
to support facets with your service class, too, you'll have to support the
|
||
"search_api_facets" feature. You can find details about the necessary additions
|
||
to your class in the example_servive.php file. In short, you'll just, when
|
||
executing a query, have to return facet terms and counts according to the
|
||
query's "search_api_facets" option, if present.
|
||
In order for the module to be able to tell that your server supports facets,
|
||
you will also have to change your service's supportsFeature() method to
|
||
something like the following:
|
||
public function supportsFeature($feature) {
|
||
return $feature == 'search_api_facets';
|
||
}
|
||
|
||
There is also a second feature defined by this module, namely
|
||
"search_api_facets_operator_or", for supporting "OR" facets. The requirements
|
||
for this feature are also explained in the example_servive.php file.
|
||
|
||
- Query option
|
||
|
||
The facets created follow the "search_api_base_path" option on the search query.
|
||
If set, this path will be used as the base path from which facet links will be
|
||
created. This can be used to show facets on pages without searches – e.g., as a
|
||
landing page.
|
||
|
||
- Hidden variable
|
||
|
||
The module uses one hidden variable, "search_api_facets_search_ids", to keep
|
||
track of the search IDs of searches executed for a given index. It is only
|
||
updated when a facet is displayed for the respective search, so isn't really a
|
||
reliable measure for this.
|
||
In any case, if you e.g. did some test searches and now don't want them to show
|
||
up in the block configuration forever after, just clear the variable:
|
||
variable_del("search_api_facets_search_ids")
|