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
- Create the listing and its item card, then place the JSF Listing
widget/block/element on the page.
- Set every filter's content provider to JSF Listing
(
jsf-listing).
- 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.
- Put the same query ID on every related filter, Apply button, Remove
Filters, Active Filters/Tags, and Pagination control.
- Map each filter to a query variable supported by the listing query:
taxonomy, meta, search, sort, alphabet, or an intentionally handled plain
query variable.
- 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.
- 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-220includes/providers/base.php:15-101includes/providers/manager.php:24-146includes/filters/manager.php:64-111includes/listing/render/listing-base.php:31-183,335-366includes/listing/views/blocks/render.phpincludes/listing/views/widgets/listing.phpincludes/listing/views/bricks/listing.php
1---2name: jsf-listing-integration3description: Connect JetSmartFilters controls to a native JSF Listing or another supported listing with the correct provider, query ID, query variable, apply type, and pagination contract. Use when building a filterable listing, debugging a filter that updates the wrong widget or does nothing, configuring content_provider, _element_id, additional providers, pagination, AJAX, reload, or mixed filtering.4---56# Connect filters to a listing78Treat the provider/query ID pair as a foreign key. Most apparent AJAX bugs are9identity or query-variable mismatches.1011## Native JSF Listing recipe12131. Create the listing and its item card, then place the JSF Listing14 widget/block/element on the page.152. Set every filter's content provider to **JSF Listing**16 (`jsf-listing`).173. Give the listing instance a stable, unique query ID. JSF uses the rendered18 `_element_id`; if no ID is available it falls back to `default`.194. Put the same query ID on every related filter, Apply button, Remove20 Filters, Active Filters/Tags, and Pagination control.215. Map each filter to a query variable supported by the listing query:22 taxonomy, meta, search, sort, alphabet, or an intentionally handled plain23 query variable.246. Start with AJAX apply type. Use reload only when the destination query must25 be reconstructed during a normal page request; test mixed mode in both26 paths.277. Test the unfiltered page, one filter, combined filters, reset, no results,28 pagination, back/forward navigation, and two rapid changes.2930## Targeting matrix3132| Symptom | First check |33|---|---|34| Nothing happens | The JSF public script loaded and provider is valid |35| Wrong listing changes | Query ID collision or missing query ID |36| AJAX works but reload does not | Provider's request path / query hook is not wired |37| First page works, pagination does not | Provider props or pagination control targets another pair |38| Results change but UI is stale | Post-render code did not use the JSF lifecycle events |39| Additional listing is unchanged | Additional provider pair was not configured explicitly |4041Do not infer the query ID from a database listing ID. The native provider's42listing ID selects the saved listing definition; its query ID selects the43rendered instance.4445## Native provider contract4647The built-in provider uses:4849- provider ID `jsf-listing`;50- wrapper selector `.jsf-listing`;51- item selector `.jsf-listing__item`;52- wrapper action `replace`;53- in-depth selector lookup enabled.5455It stores the initial query and pagination statistics before the frontend56settings are localized. During AJAX it rebuilds the saved listing, merges the57parsed JSF arguments into the listing query object, and renders it.5859Source compatibility warning: the 3.8.3.1 stored-settings key is misspelled60`lisitng_id`, and AJAX reads the same misspelling. Normal configuration code61should not touch it. Code that filters62`jet-smart-filters/providers/jsf-listing/stored-settings` must preserve that63exact key until the installed version changes it.6465## Integration checklist6667- Use unique IDs that are valid for the target builder and stable across page68 renders.69- Do not bind one pagination control to multiple query IDs.70- Prefer event delegation inside replaced content. Direct listeners disappear71 when the provider wrapper is replaced.72- Keep per-page limits bounded and return accurate `found_posts`,73 `max_num_pages`, and `page` for custom queries.74- If the renderer is not represented by a built-in provider, use75 `jsf-custom-provider-query`; changing CSS selectors alone is not a complete76 provider integration.7778## References7980Verified against JetSmartFilters 3.8.3.1 source:8182- `includes/providers/jsf-listing.php:19-220`83- `includes/providers/base.php:15-101`84- `includes/providers/manager.php:24-146`85- `includes/filters/manager.php:64-111`86- `includes/listing/render/listing-base.php:31-183,335-366`87- `includes/listing/views/blocks/render.php`88- `includes/listing/views/widgets/listing.php`89- `includes/listing/views/bricks/listing.php`
Lonsdale201