README.txt 6.48 KB
Newer Older
1 2
CONTENTS OF THIS FILE
---------------------
3

4
 * Requirements
5
 * Recommended Modules
6 7
 * Installation
 * Configuration
8
 * Features
9
 * Extension modules
10
 * FAQ
11
 * Maintainers
12

13

14 15
INTRODUCTION
------------
16 17 18

The Facets module allows site builders to easily create and manage faceted search
interfaces.
19

20

21 22
REQUIREMENTS
------------
23 24 25 26 27 28 29 30 31

No other modules required; we're supporting Drupal Core's search as a source for
creating facets.


RECOMMENDED MODULES
-------------------

 * Search API - https://www.drupal.org/project/search_api
32

33

34 35
INSTALLATION
------------
36 37 38

 * Install as you would normally install a contributed Drupal module. Visit:
   https://www.drupal.org/node/1897420 for further information.
39

40

41 42
CONFIGURATION
-------------
43

44 45 46 47
Before adding a facet, there should be a facet source. Facet sources can be:
- Drupal core's search.
- A view based on a Search API index with a page display.
- A page from the search_api_page module.
48

49
After adding one of those, you can add a facet on the facets configuration page:
50 51 52
/admin/config/search/facets, there's an `add facet` link, that links to:
admin/config/search/facets/add-facet. Use that page to add the facet by
selecting the correct facet source and field from that source.
53

54 55 56
If you're using Search API views, make sure to disable views cache when using
facets for that view.

57

58 59
KNOWN ISSUES
------------
60

61
When choosing the "Hard limit" option on a search_api_db backend, be aware that
62
the limitation is done internally after sorting on the number of results ("num")
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
first and then sorting by the raw value of the facet (e.g. entity-id) in the
second dimension. This can lead to edge cases when there is an equal amount of
results on facets that are exactly on the threshold of the hard limit. In this
case the raw facet value with the lower value is preferred:

| num | value | label |
|-----|-------|-------|
|  3  |   4   | Bar   |
|  3  |   5   | Atom  |
|  2  |   2   | Zero  |
|  2  |   3   | Clown |

"Clown" will be cut off due to its higher internal value (entity-id). For
further details see: https://www.drupal.org/node/2834730

78 79 80 81

FEATURES
--------

82
If you are the developer of a search API backend implementation and want
83 84
to support facets with your service class, too, you'll have to support the
"search_api_facets" feature. In short, you'll just have to return facet terms
85 86 87
and counts according to the query's "search_api_facets" option, when executing
a query.
For the module to be able to tell that your server supports facets,
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
you will also have to change your service's supportsFeature() method to
something like the following:

```
  public function getSupportedFeatures() {
    return ['search_api_facets'];
  }
```

If you don't do that, there's no way for the facet source to pick up facets.

The "search_api_facets" option looks as follows:

```
$query->setOption('search_api_facets', [
  $facet_id => [
    // The Search API field ID of the field to facet on.
    'field' => (string),
    // The maximum number of filters to retrieve for the facet.
    'limit' => (int),
    // The facet operator: "and" or "or".
    'operator' => (string),
    // The minimum count a filter/value must have to be returned.
    'min_count' => (int),
    // Whether to retrieve a facet for "missing" values.
    'missing' => (bool),
  ],
  // …
]);
```

The structure of the returned facets array should look like this:

```
$results->setExtraData('search_api_facets', [
  $facet_id => [
    [
      'count' => (int),
      'filter' => (string),
    ],
    // …
  ],
  // …
]);
```

A filter is a string with one of the following forms:
- `"VALUE"`: Filter by the literal value VALUE (always include the quotes, not
  only for strings).
- `[VALUE1 VALUE2]`: Filter for a value between VALUE1 and VALUE2. Use
138
  parentheses for excluding the border values and square brackets for including
139 140 141 142
  them. An asterisk (*) can be used as a wildcard. E.g., (* 0) or [* 0) would be
  a filter for all negative values.
- `!`: Filter for items without a value for this field (i.e., the "missing"
  facet).
143

144

145 146 147 148
EXTENSION MODULES
-----------------

- https://www.drupal.org/project/entity_reference_facet_link
149
  Provides a link to a facet through an entity reference field.
150
- https://www.drupal.org/project/facets_prefix_suffix
151
  Provides a plugin to configure a prefix/suffix per result.
152
- https://www.drupal.org/project/facets_block
153
  Provide the facets as a Drupal block.
154
- https://www.drupal.org/project/facets_taxonomy_path_processor
155
  Sets taxonomy facet items active if present in route.
156
- https://www.drupal.org/project/facets_view_mode_processor
157
  Provides a processor to render facet entity reference items as view modes.
158 159
- https://www.drupal.org/project/facets_range_input
  Provides an input range form (min and max) as a processor and widget.
160

161 162 163 164

FAQ
---

165
Q: Why do the facets disappear after a refresh?
166 167
A: We don't support cached views, change the view to disable caching.

168 169 170
Q: Why doesn't chosen (or similar JavaScript dropdown replacement) not work
with the dropdown widget?
A: Because the dropdown we create for the widget is created through JavaScript,
171
the chosen module (and others, probably) doesn't find the select element.
172 173
Though the library can be attached to the block in custom code, we haven't
done this in facets because we don't want to support all possible frameworks.
174
See https://www.drupal.org/node/2853121 for more information.
175 176 177 178 179 180 181

Q: Why are facets results links from another language showing in the facet
results?
A: Facets use the same limitations as the query object passed, so when using
views, add a filter to the view to limit to one language.
Otherwise, this is solved by adding a `hook_search_api_query_alter()` that
limits the results to the current language.
182 183 184 185

Q: I would like a prefix/suffix for facet result items.
A: If you just need to show text, use
https://www.drupal.org/project/facets_prefix_suffix.
186
However, if you need to include HTML you can use
187
hook_preprocess_facets_result_item().
188 189 190 191 192 193 194 195

Q: Why are results shown for inaccessible content?
A: If the "Content access" Search API processor is enabled but results still
aren't properly access-checked, you might need to write a custom processor to do
the access checks for you.
This should only happen if you're not using the default node access framework
provided by Core, though. You need to use a combination of hook_node_grants and
hook_node_access_records instead of hook_node_access.
196 197 198 199 200 201 202

MAINTAINERS
-----------

 * Joris Vercammen (borisson_) - https://www.drupal.org/u/borisson_
 * Jimmy Henderickx (StryKaizer) - https://www.drupal.org/u/strykaizer
 * Nick Veenhof (Nick_vh) - https://www.drupal.org/u/nick_vh