Connect filters to a listing

Treat the provider/query ID pair as a foreign key. Most apparent AJAX bugs are identity or query-variable mismatches.

Native JSF Listing recipe

1. Create the listing and its item card, then place the JSF Listing widget/block/element on the page.
2. Set every filter's content provider to JSF Listing (jsf-listing).
3. Give the listing instance a stable, unique query ID. JSF uses the rendered _element_id; if no ID is available it falls back to default.
4. Put the same query ID on every related filter, Apply button, Remove Filters, Active Filters/Tags, and Pagination control.
5. Map each filter to a query variable supported by the listing query: taxonomy, meta, search, sort, alphabet, or an intentionally handled plain query variable.
6. Start with AJAX apply type. Use reload only when the destination query must be reconstructed during a normal page request; test mixed mode in both paths.
7. Test the unfiltered page, one filter, combined filters, reset, no results, pagination, back/forward navigation, and two rapid changes.

Targeting matrix

Symptom	First check
Nothing happens	The JSF public script loaded and provider is valid
Wrong listing changes	Query ID collision or missing query ID
AJAX works but reload does not	Provider's request path / query hook is not wired
First page works, pagination does not	Provider props or pagination control targets another pair
Results change but UI is stale	Post-render code did not use the JSF lifecycle events
Additional listing is unchanged	Additional provider pair was not configured explicitly

Do not infer the query ID from a database listing ID. The native provider's listing ID selects the saved listing definition; its query ID selects the rendered instance.

Native provider contract

The built-in provider uses:

• provider ID jsf-listing;
• wrapper selector .jsf-listing;
• item selector .jsf-listing__item;
• wrapper action replace;
• in-depth selector lookup enabled.

It stores the initial query and pagination statistics before the frontend settings are localized. During AJAX it rebuilds the saved listing, merges the parsed JSF arguments into the listing query object, and renders it.

Source compatibility warning: the 3.8.3.1 stored-settings key is misspelled lisitng_id, and AJAX reads the same misspelling. Normal configuration code should not touch it. Code that filters jet-smart-filters/providers/jsf-listing/stored-settings must preserve that exact key until the installed version changes it.

Integration checklist

• Use unique IDs that are valid for the target builder and stable across page renders.
• Do not bind one pagination control to multiple query IDs.
• Prefer event delegation inside replaced content. Direct listeners disappear when the provider wrapper is replaced.
• Keep per-page limits bounded and return accurate found_posts, max_num_pages, and page for custom queries.
• If the renderer is not represented by a built-in provider, use jsf-custom-provider-query; changing CSS selectors alone is not a complete provider integration.

References

Verified against JetSmartFilters 3.8.3.1 source:

• includes/providers/jsf-listing.php:19-220
• includes/providers/base.php:15-101
• includes/providers/manager.php:24-146
• includes/filters/manager.php:64-111
• includes/listing/render/listing-base.php:31-183,335-366
• includes/listing/views/blocks/render.php
• includes/listing/views/widgets/listing.php
• includes/listing/views/bricks/listing.php