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.md

GitHub

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