.. _routing-facet-in-path:

=======================
Facets in path segments
=======================

This chapter describe how you can use a facet as part of your url path.

Imagine you have an online shop and use Solr to display the products. It would be convenient for the customer if can call an url path like `/products/candy`.

The first step is to create a site `/products` and place the Solr plugin as content.

Configure the path segment
--------------------------

In our example we are using facet `productType` to filter the search result for a specific product type.

The first step is to define a route path. Because we have already a side called `/products` only need to define a path contain the facet.

The name itself needs no connection to the facet, so you can choose something different.

.. code-block:: yaml

  routeEnhancers:
    products:
      routePath: '/{productType}'


The next step is to map the variable to the facet itself.

Map the variable to the facet
-----------------------------

The mapping from variable to facet differs from the standard as you know from TYPO3 or symfony.

A facet inside of the query is a composition of facet and value.

Example:

	/products/?tx_solr[filter][0]=taste:matcha&tx_solr[filter][1]=productType:candy&tx_solr[filter][2]=color:yellow&tx_solr[filter][3]=color:green&tx_solr[filter][4]=taste:sweet

This example shows another issues:

* there is not specific order of facets
* a facet can contains multiple values

Define a query path would not work in this case.

The solution is to define a part of a query path and attach the facet you want to place inside of the url.

This is done by separating the query path and the facet by a dash.

.. code-block:: yaml

  routeEnhancers:
    products:
      # Note: All arguments inside of namespace tx_solr. See -> extensionKey
      # Example: Argument 'type' define as 'filter-type' will convert into 'tx_solr/filter-type'
      _arguments:
        productType: filter-productType
      requirements:
        productType: '.*'

The route enhancer now knows to place values of facet `productType` as path segment.

As result the URL now changed into

	/products/candy/?tx_solr[filter][0]=taste:matcha&tx_solr[filter][1]=color:yellow&tx_solr[filter][2]=color:green&tx_solr[filter][3]=taste:sweet

.. important::
   The name used as argument name have to match the name of the Solr filter.

.. important::
   We recommend to configured the requirements for a variable with `.*`. If a value is required it will lead to an exception if not type is omitted.


Handling of multiple values
---------------------------

As the customer can combine as many values of a facet to filter the result, the path segment can contain multiple value.

The route enhancer will collect all values of the configured facet and combine them to a single string.

The values will sort alphanumeric and concat with a colon.

You can change the value separator by configuring a multi value separator:

.. code-block:: yaml

  routeEnhancers:
    products:
      solr:
        multiValueSeparator: ';'

Additional you can replace specific characters inside of each value using a map to replace the characters:

.. code-block:: yaml

  routeEnhancers:
    products:
      solr:
        replaceCharacters:
          ' ': '-'

.. important::
  If you replace characters, please take care that the target character is not a character, which could be a part of the facet value.

Now lets have a look at the effect.

Before the configuration we had this URL:

	/products/?tx_solr[filter][0]=taste:matcha&tx_solr[filter][1]=productType:dark+chocolate&tx_solr[filter][2]=taste:sweet&tx_solr[filter][3]=productType:candy

After applying the configuration, the URL changed into:

	/products/candy;dark-chocolate?tx_solr[filter][0]=taste:matcha&tx_solr[filter][1]=taste:sweet

Full example
------------

This example shows the all configuration done above

.. code-block:: yaml

  routeEnhancers:
    products:
      type: SolrFacetMaskAndCombineEnhancer
      limitToPages:
        - 42
      extensionKey: tx_solr
      routePath: '/{productType}'
      # Note: All arguments inside of namespace tx_solr. See -> extensionKey
      # Example: Argument 'type' define as 'filter-type' will convert into 'tx_solr/filter-type'
      _arguments:
        productType: filter-productType
      # Important: Configure requirement for fields! If you wand to allow empty values, set .*
      requirements:
        productType: '.*'
      solr:
        multiValueSeparator: ';'
        replaceCharacters:
          ' ': '-'