first import 7.x-1.4

contrib/search_api_facetapi/README.txt

@@ -0,0 +1,125 @@
+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")