# JPKCom Post Filter — Guide & Tips

> Faceted taxonomy filtering for posts, pages and custom post types with JPKCom Post Filter — SEO-friendly URLs, AJAX, shortcodes, blocks and page builder support.

Source: https://www.jpkc.com/db/en/guides/jpkcom-post-filter/

JPKCom Post Filter adds faceted taxonomy filtering to any WordPress archive page — for posts, pages and any custom post type. Every filter state is encoded in an SEO-friendly URL like `/blog/filter/web-design+marketing/wordpress/`, so it is shareable and bookmarkable; filtering runs via AJAX with a full no-JavaScript fallback.

## Guide

### Requirements

- WordPress **6.9** or newer (tested up to 7.0)
- PHP **8.3** or newer
- **No** dependencies: no ACF, no Bootstrap, no jQuery required

Page builder support is optional — the Gutenberg blocks, Elementor widgets and Oxygen elements load only when the respective builder is active.

### Installation

1. Upload the `jpkcom-post-filter` directory to `/wp-content/plugins/` (or install the ZIP via **Plugins → Add New → Upload Plugin**).
2. Activate the plugin under **Plugins → Installed Plugins**.
3. Under **Post Filter → General**, select the post types to filter.
4. Under **Post Filter → Filter Groups**, add the taxonomies you want as filter dimensions.
5. Go to **Settings → Permalinks** and click **Save Changes** to flush the rewrite rules.

### Configuring filter groups

Each filter group maps a taxonomy to a URL position; the group order determines the order of the URL segments. Per group you set the taxonomy, label, target post types, a numeric sort position (`Order`) and an on/off toggle (`Enabled`).

You can **register new taxonomies** right from the Filter Groups page (the "Register as new WordPress taxonomy" option): slug, rewrite slug, hierarchical/flat, public, admin column and REST API visibility (required for Gutenberg) are all configurable.

> **Warning:** Deleting a filter group that registered a custom taxonomy unregisters that taxonomy — all term assignments on posts are permanently lost.

### Output: auto-inject, shortcodes, blocks

There are three ways to render the filter and list:

- **Auto-inject** (**General → Auto-Inject Filter**): the plugin automatically wraps the theme's archive loop with the filter UI — no shortcode or template edit needed. It hooks into `loop_start`/`loop_end` on archive/blog pages (not on singular posts, search or pages).
- **Shortcodes:** `[jpkcom_postfilter_filter]`, `[jpkcom_postfilter_list]` and `[jpkcom_postfilter_pagination]`. The interactive shortcode builder under **Post Filter → Shortcodes** generates ready-made snippets.
- **Builders:** three Gutenberg blocks, three Elementor widgets and three Oxygen elements each (Post Filter, Post List, Post Pagination).

```text
[jpkcom_postfilter_filter post_type="portfolio" layout="dropdown"]
[jpkcom_postfilter_list post_type="portfolio" layout="cards" limit="12"]
[jpkcom_postfilter_pagination post_type="portfolio"]
```

> **Important:** Shortcodes (and blocks/widgets/elements) always attach to the archive of the configured post type. They only work on an archive template page or on the page set as the "Posts Page" under **Settings → Reading**. On an arbitrary page (e.g. `/test/`) filter clicks and AJAX jump back to the archive URL — use auto-inject there instead.

### Layout & design

**Post Filter → Layout & Design** offers six tabs (Global, Filter, Posts, Pagination, Color Schemes, Advanced). You choose from four filter layouts (bar, columns, sidebar, dropdown), three list layouts (cards, rows, minimal) and four color schemes (Default, Dark, Contrast, Monochrome). The **Advanced** tab controls the stylesheet mode (Full / Variables only / Disabled), the Plus/Minus mode, reset button visibility and your own custom CSS, among others.

## Tips & Tricks

- **Change the URL endpoint:** By default the filter sits under `/filter/`. Change the path segment under **General → URL Endpoint** and then click **Flush Rewrite Rules** (or re-save your permalinks).
- **Behaviour without filter terms:** Use **Bare Endpoint Behaviour** to set what happens when `/filter/` is accessed without terms — 404, redirect to the blog homepage, or a custom URL.
- **Multiple filter instances per page:** Each filter/list/pagination set is paired via the `post_type` attribute (`data-jpkpf-post-type`), so different post types can be filtered independently on one page.
- **Four cache layers:** Object cache, transients, APCu and a PHP settings file cache keep output fast. Caches are invalidated automatically on `save_post`/`deleted_post` or term changes; clear them manually under **Post Filter → Cache**.
- **Override CSS cleanly:** All styles use CSS custom properties prefixed `--jpkpf-`. Set them in your theme stylesheet, in the variable fields under **Layout & Design**, or via the custom CSS field. For full control, set the stylesheet mode to "Disabled".
- **Override templates per theme:** The loader checks child theme → parent theme → `mu-plugins/jpkcom-post-filter-overrides/templates/` → plugin `templates/`. For example, copy `templates/partials/list/list-cards.php` to `themes/your-theme/jpkcom-post-filter/partials/list/list-cards.php`.
- **Migrate settings:** Under **Post Filter → Import / Export** you can export all settings (general, layout, cache, filter\_groups) as JSON and re-import them on another environment.
- **Constants in `wp-config.php`:** among others, `JPKCOM_POSTFILTER_URL_ENDPOINT`, `JPKCOM_POSTFILTER_CACHE_ENABLED`, `JPKCOM_POSTFILTER_DEBUG` and `JPKCOM_POSTFILTER_MAX_FILTER_COMBOS` are overridable.
- **Build Gutenberg blocks from source:** The block editor scripts need a build step (`npm install && npm run build`, output to `blocks/build/`). If the build directory is missing, the plugin skips block registration.
- **Accessible & SEO-ready:** Filter terms are real `<a>` links (page reload without JS), the results zone uses `aria-live`, toggle buttons use `aria-pressed`. Each filter combination has a crawlable URL with a canonical set against duplicate content.

## Further reading

- Source code on GitHub: <https://github.com/JPKCom/jpkcom-post-filter>
- [This project's changelog](https://www.jpkc.com/db/en/changelog/jpkcom-post-filter/)