jsf-overview
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 targe
SKILL.mdjetsmartfilter/jsf-overview/SKILL.md
GitHubJetSmartFilters 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_filtersrequest 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