123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125 |
- 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")
|