JetSmartFilters integration map
Use this as the router for JetSmartFilters work. Keep a single identity pair,
provider/queryId, from the filter controls through the request and the
rendered listing.
Mental model
filter control -> filter group (provider/queryId) -> parsed query args
-> provider renders content -> frontend replaces/inserts DOM
| Layer |
Owns |
Use |
| Filter |
User input and query-variable mapping |
Existing JSF filter types and their settings |
| Filter group |
All controls targeting one provider/query ID |
Frontend state, AJAX, pagination, active filters |
| Provider |
Locating and re-rendering the target HTML/data |
Built-in provider or a registered custom provider |
| Query |
Turning filter values into query arguments |
Listing-specific filters or JSF query hooks |
| Listing |
Initial query, item card, pagination statistics |
JSF Listing, JetEngine Listing Grid, Woo archive, or another supported renderer |
| Frontend events |
Loading state and post-render compatibility |
jsf-frontend-events |
Choose the narrowest extension point
- Configure a normal JSF Listing: use
jsf-listing-integration.
- Run JavaScript when AJAX starts or finishes: use
jsf-frontend-events.
- Modify which records a listing returns: use
jsf-query-hooks.
- Expose an unsupported renderer or data source: use
jsf-custom-provider-query.
- Do not create a custom provider merely to add one query condition. Providers
own DOM replacement; query hooks own record selection.
Identity rules
- A provider ID identifies a renderer, not a specific widget. The native JSF
Listing provider is
jsf-listing.
- The query ID identifies one instance of that provider. JSF defaults missing
IDs to
default.
- Every filter, pagination control, active-filter control, and listing intended
to work together must resolve to the same pair.
- Two listings using the same provider need distinct query IDs. Otherwise
requests, stored defaults, props, and frontend groups can collide.
- Scope PHP and JavaScript integrations by both values whenever both are
available.
Compatibility workflow
- Record the plugin version and the target renderer.
- Inspect the listing's provider and query ID in rendered attributes and
window.JetSmartFilterSettings.
- Verify the filter's content provider, query ID, apply type, and query
variable.
- Confirm the initial query works before testing AJAX.
- Inspect the
jet_smart_filters request and JSON response.
- Verify DOM replacement, pagination props, empty results, rapid changes, and
browser history.
- Re-test source-derived hooks after a JSF upgrade; the frontend event bus is
shipped in a minified bundle and is not a WordPress core API.
Source-verified boundaries
The public frontend script is enqueued only when a filter marks JSF as used.
JetSmartFilterSettings then contains provider selectors, default queries,
provider settings, and pagination props. A companion script must therefore
feature-detect window.JetSmartFilters and should load only on pages that use
filters.
References
Verified against JetSmartFilters 3.8.3.1 source:
jet-smart-filters.php:151-219,225-299includes/filters/manager.php:22-112includes/data.php:198-228includes/providers/manager.php:78-146includes/providers/jsf-listing.php:33-220assets/js/public.js
1---2name: jsf-overview3description: Map a JetSmartFilters integration to the correct filter, provider, query ID, listing, frontend event, or extension API. Use when planning or reviewing JSF compatibility, diagnosing a filter that targets the wrong listing, choosing between JSF Listing hooks and a custom provider, or encountering JetSmartFilters, JetSmartFilterSettings, jsf-listing, content_provider, or jet-smart-filters hooks without knowing which layer owns the behavior.4---56# JetSmartFilters integration map78Use this as the router for JetSmartFilters work. Keep a single identity pair,9`provider/queryId`, from the filter controls through the request and the10rendered listing.1112## Mental model1314```text15filter control -> filter group (provider/queryId) -> parsed query args16 -> provider renders content -> frontend replaces/inserts DOM17```1819| Layer | Owns | Use |20|---|---|---|21| Filter | User input and query-variable mapping | Existing JSF filter types and their settings |22| Filter group | All controls targeting one provider/query ID | Frontend state, AJAX, pagination, active filters |23| Provider | Locating and re-rendering the target HTML/data | Built-in provider or a registered custom provider |24| Query | Turning filter values into query arguments | Listing-specific filters or JSF query hooks |25| Listing | Initial query, item card, pagination statistics | JSF Listing, JetEngine Listing Grid, Woo archive, or another supported renderer |26| Frontend events | Loading state and post-render compatibility | `jsf-frontend-events` |2728## Choose the narrowest extension point2930- Configure a normal JSF Listing: use `jsf-listing-integration`.31- Run JavaScript when AJAX starts or finishes: use `jsf-frontend-events`.32- Modify which records a listing returns: use `jsf-query-hooks`.33- Expose an unsupported renderer or data source: use34 `jsf-custom-provider-query`.35- Do not create a custom provider merely to add one query condition. Providers36 own DOM replacement; query hooks own record selection.3738## Identity rules3940- A provider ID identifies a renderer, not a specific widget. The native JSF41 Listing provider is `jsf-listing`.42- The query ID identifies one instance of that provider. JSF defaults missing43 IDs to `default`.44- Every filter, pagination control, active-filter control, and listing intended45 to work together must resolve to the same pair.46- Two listings using the same provider need distinct query IDs. Otherwise47 requests, stored defaults, props, and frontend groups can collide.48- Scope PHP and JavaScript integrations by both values whenever both are49 available.5051## Compatibility workflow52531. Record the plugin version and the target renderer.542. Inspect the listing's provider and query ID in rendered attributes and55 `window.JetSmartFilterSettings`.563. Verify the filter's content provider, query ID, apply type, and query57 variable.584. Confirm the initial query works before testing AJAX.595. Inspect the `jet_smart_filters` request and JSON response.606. Verify DOM replacement, pagination props, empty results, rapid changes, and61 browser history.627. Re-test source-derived hooks after a JSF upgrade; the frontend event bus is63 shipped in a minified bundle and is not a WordPress core API.6465## Source-verified boundaries6667The public frontend script is enqueued only when a filter marks JSF as used.68`JetSmartFilterSettings` then contains provider selectors, default queries,69provider settings, and pagination props. A companion script must therefore70feature-detect `window.JetSmartFilters` and should load only on pages that use71filters.7273## References7475Verified against JetSmartFilters 3.8.3.1 source:7677- `jet-smart-filters.php:151-219,225-299`78- `includes/filters/manager.php:22-112`79- `includes/data.php:198-228`80- `includes/providers/manager.php:78-146`81- `includes/providers/jsf-listing.php:33-220`82- `assets/js/public.js`
Lonsdale201