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

1. Record the plugin version and the target renderer.
2. Inspect the listing's provider and query ID in rendered attributes and window.JetSmartFilterSettings.
3. Verify the filter's content provider, query ID, apply type, and query variable.
4. Confirm the initial query works before testing AJAX.
5. Inspect the jet_smart_filters request and JSON response.
6. Verify DOM replacement, pagination props, empty results, rapid changes, and browser history.
7. 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-299
• includes/filters/manager.php:22-112
• includes/data.php:198-228
• includes/providers/manager.php:78-146
• includes/providers/jsf-listing.php:33-220
• assets/js/public.js