# Solr Facet Field Formatter

Formats a field as links into a [Search API](https://www.drupal.org/project/search_api)
search page, pre-filtered by a [Facets](https://www.drupal.org/project/facets)
facet whose value is set to the field value.

For example, a "Genus" field rendered with this formatter becomes a link to your
search page with the *Genus* facet already filtered to that value.

## Supported field types

The formatter is available for every field type. The value used in the facet
query is resolved per field type:

- **Reference fields** (`entity_reference`, `typed_relation`, …): the referenced
  entity's **label** is used, so the facet is filtered by the readable value
  (e.g. the taxonomy term name) rather than the internal entity id.
- **All other fields** (text, string, list, numeric, boolean, datetime, …): the
  field's main property value is used.

This matches how such fields are normally indexed and faceted in Solr — make
sure the facet you select indexes the same readable value.

You can override this per field with the **Facet value** setting:

- **Automatic** (default): referenced entity label for reference fields, the
  field value otherwise.
- **Referenced entity label**: always use the referenced entity's label.
- **Raw stored value**: use the stored value — the entity id for reference
  fields. Choose this when your facet indexes entity ids rather than labels.

## Dependencies

- `search_api_solr`
- `facets`

## Configuration

The formatter is configured per field, under **Manage display** for the entity
(e.g. `/admin/structure/types/manage/<bundle>/display`). Choose the
*Solr Facet Field Formatter* format for a text/string field and set:

- **Search page (facet source):** the search results page the link points to.
  This determines both the URL path and the facet filter key, read from the
  selected facet source.
- **Facet:** the facet to filter on. Pick the facet configured for this field
  on the chosen search page. Its URL alias is used as the facet key in the
  generated query.
- **Facet value:** which value of the field to filter by. See
  *Supported field types* above.
- **Reset fulltext search** (optional): adds an empty fulltext query parameter
  so following the link starts a fresh, facet-only search. The parameter name
  (default `search_api_fulltext`) is configurable to match your view's exposed
  fulltext filter.

The generated link matches the query string that Facets itself produces, e.g.
`/<search-path>?f[0]=<facet-alias>:<field-value>`.

## Upgrading

Earlier versions hardcoded a specific view (`herbarium_search`). After
upgrading, each field using this formatter must be reconfigured on its
**Manage display** page to select a facet source and facet. Until configured,
the field renders as plain text.