Facets Pretty Paths
Provides clean, SEO-friendly URL paths for Facets module by converting query string parameters into human-readable path segments.
facets_pretty_paths
Install
composer require 'drupal/facets_pretty_paths:^2.0'
Overview
Facets Pretty Paths transforms the default facet URLs generated by the Facets module from query string-based parameters (e.g., /search?f[0]=color:blue) into clean, readable path segments (e.g., /search/color/blue). This approach improves both SEO performance and user experience by creating more intuitive, shareable URLs.
The module provides a pluggable "Coder" system that determines how facet values are encoded into URLs and decoded back to their original values. This allows for different encoding strategies depending on the type of data being filtered (taxonomy terms, list items, node references, etc.). Multiple built-in coders are provided, and custom coders can be created by implementing the Coder plugin interface.
When enabled for a facet source, the module dynamically alters the source's route to accept facet filters as path segments. It also provides automatic breadcrumb generation for filtered search results pages.
Features
- URL Processor plugin that generates clean path segments instead of query string parameters (e.g., /brand/drupal/color/blue)
- Pluggable Coder system for encoding and decoding facet values in URLs - allows custom transformation logic per facet
- Built-in Default Coder that uses raw values without transformation (e.g., /color/2)
- Built-in Taxonomy Term Coder that uses term name with ID for uniqueness (e.g., /color/blue-2)
- Built-in Taxonomy Term Name Coder that uses only the term name for cleaner URLs (e.g., /color/blue)
- Built-in List Item Coder for option list fields with label and ID (e.g., /status/published-1)
- Built-in Node Title Coder for entity reference fields using node title with ID (e.g., /author/john-smith-42)
- Automatic route modification to accept facets_query parameter on facet source routes
- Active filters service that parses URL path segments to determine currently active facet selections
- Custom breadcrumb builder for faceted search pages with proper navigation links
- Support for hierarchical facets with parent/child relationship handling
- AJAX support for Views with proper URL context preservation
- Batch processing support for Views Data Export with facet context
Use Cases
SEO-Optimized E-commerce Filtering
An online store uses Facets Pretty Paths to create clean, indexable URLs for product filters. Instead of /products?f[0]=category:shoes&f[1]=color:blue, customers see /products/category/shoes/color/blue. This improves search engine indexing and allows users to bookmark and share specific filtered views.
Multilingual Taxonomy Filtering
A multilingual site uses the Taxonomy Term Name Coder to display facet values in the user's language. When filtering by category 'Electronics' in English, the URL shows /search/category/electronics, while the same filter in German shows /search/kategorie/elektronik, improving local SEO.
Content Type Filtering
A news portal allows filtering articles by type using a list field. With the List Item Coder, the URL /news/type/opinion-3 clearly indicates the filter while maintaining the internal value reference for reliable decoding.
Author-Based Content Filtering
A blog uses entity reference fields to link content to author profiles. The Node Title Coder creates URLs like /articles/author/jane-doe-15 that are both human-readable and uniquely identifiable.
Custom Coder Implementation
A site with complex facet value requirements implements a custom coder plugin. By implementing CoderInterface with encode() and decode() methods, developers can create site-specific URL encoding logic, such as using SKUs for product variants or custom slugs for categories.
Tips
- Set the facet 'URL alias' to a short, descriptive name as this becomes part of the URL path (e.g., 'brand' instead of 'field_product_brand')
- Use the Taxonomy Term Name Coder only when term names are guaranteed unique within the vocabulary to avoid ambiguous decoding
- Consider facet weight settings as they affect the order of path segments in URLs - consistent ordering helps with caching and SEO
- Custom coders can be created by implementing CoderInterface - define encode() for URL generation and decode() for parsing
- The breadcrumb builder has priority 1500, which can be adjusted if conflicts occur with other breadcrumb modules
- When debugging, check the 'facets_query' route parameter to see the raw filter string being parsed
Technical Details
Admin Pages 2
/admin/config/search/facets/facet-sources/{facet_source_id}/edit
Configure the URL handler for a facet source. Select 'Pretty paths' to enable clean URL paths for all facets using this source instead of query string parameters.
/admin/config/search/facets/{facets_facet}/edit
When Pretty Paths is enabled for the facet source, an additional 'Pretty paths coder' setting appears in the Facet settings section allowing you to select how this specific facet's values are encoded in URLs.
Hooks 1
hook_form_facets_facet_edit_form_alter
Alters the facet edit form to add the Pretty Paths coder selection when Pretty Paths is enabled for the facet source.
Troubleshooting 6
Ensure you have selected 'Pretty paths' as the URL handler in the facet source configuration, not just the individual facet. After changing the setting, clear all caches to rebuild routes.
The route may not have been rebuilt. Clear caches with 'drush cr' or via /admin/config/development/performance. Also verify that the base path exists and the facet source is correctly configured.
Change the Pretty Paths coder setting on the facet from 'Default' to 'Taxonomy term name + id' or 'Taxonomy term name' depending on your preference.
This was addressed in issue #3129632. Update to the latest version of the module. The fix ensures facet context is extracted from AJAX request parameters and referer headers.
Due to database limitations, the router table has a 255 character path limit. The module adds placeholder parameters to work around core routing issues, but extremely long filter combinations may still exceed limits. Consider reducing the number of simultaneously active facets.
The name-only coder searches all terms in configured vocabularies. If multiple terms have the same name, it returns the first match. Use 'Taxonomy term name + id' coder for guaranteed uniqueness.
Security Notes 3
- Facet values in URLs are sanitized using Pathauto's alias cleaner, which applies transliteration and removes unsafe characters
- The module uses access checking when loading entities during encoding/decoding operations
- Input from URL path segments is properly validated against existing facet configurations before processing