> For the complete documentation index, see [llms.txt](https://whoisandywhite.gitbook.io/porterwp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whoisandywhite.gitbook.io/porterwp/documentation/premium-filters-block.md).

# Premium Filters Block

> Requires **PorterWP Premium**.\
> Adds faceted filtering to any **core/Query Loop**.

## Usage

1. Insert **“Filters”** block.
2. Configure filter groups via the ACF sidebar:
   * Post Types, Taxonomies, Meta, Search, Sort.
3. Add a **core/Query Loop** block *after* the Filters block and give it the CSS class **`use-filters`**.

The Filters block outputs a hidden `<form>` which serialises field choices and triggers an **AJAX refresh** handled by `Porter_Filters_Ajax_Handler`.

### File Map

| Path                                                        | Purpose                                    |
| ----------------------------------------------------------- | ------------------------------------------ |
| `includes/premium/filters/block/`                           | Block source (block.json, ACF, SCSS, JS)   |
| `core-query--use-filters.php`                               | Alters WP\_Query based on submitted params |
| `includes/premium/filters/traits/trait-FilterParser.php`    | Converts GET params ⇒ WP\_Query arguments  |
| `includes/premium/filters/traits/trait-FilterGenerator.php` | Builds HTML for facet groups               |
| `templates/`                                                | Legacy PHP templates fallback              |

***

### JavaScript lifecycle

* **assets/src/js/porter-filters.js** listens for `change` events, debounces, then calls `wp.ajax.send( 'porter_filters', … )`.
* The PHP handler returns rendered block markup which swaps the contents of the Query Loop container.

### Customising the search placeholder

If the search field is enabled, themes can override its placeholder text without replacing the filter template:

```php
add_filter( 'porter/filter/search_placeholder', function( $placeholder, $key, $post_type, $filter_settings ) {
    if ( 'resource' === $post_type ) {
        return 'Search resources';
    }

    return $placeholder;
}, 10, 4 );
```

See [porter/filter/search\_placeholder](/porterwp/filters/porter_filter_search_placeholder.md) for the full hook reference.