web_finder Shortcode
The web_finder shortcode renders a search form with current query, field and result configuration. The Gutenberg Finder family uses the same renderer and assets; neither requires Faceted Search to be enabled.
The attributes below match the current Page Builder controls and public output. Use raw syntax only for reviewed content that cannot be maintained through the visual controls.
Allowed child shortcodes: web_finder_content.
Usage
[web_finder]
Content
[/web_finder]Attributes
| Attribute | Default | Accepted values | Purpose |
|---|---|---|---|
web_finder_action |
— | String unless stated otherwise | The page to open when the form is submitted. Leave blank to reload the current page. This setting is not used when AJAX is enabled. |
web_auto_submit |
— | yes |
Indicates whether the form should submit automatically whenever a field is updated. |
web_finder_ajax |
— | yes |
When AJAX is enabled, there's no need to reload the page. |
web_finder_ajax_show_default_results |
— | yes |
If checked, search results will display on page load. Available when web_finder_ajax is yes. |
web_finder_ajax_loading_img |
Empty; loading text | Media URL | Image to display before results are loaded. Available when web_finder_ajax is yes. |
web_finder_ajax_button_style |
1 |
1 or a configured button-style slug |
Selects the Load More button style. Available when web_finder_ajax is yes. |
web_finder_ajax_button_text |
Load more results |
String unless stated otherwise | Custom text for the Load More button. Available when web_finder_ajax is yes. |
taxonomy_relation |
OR |
OR, AND |
Specifies the relationship between taxonomies. This not only takes into account those chosen in the taxonomy module but also includes those specified in the selected query. |
web_query |
1 |
String unless stated otherwise | You can create new queries from the Custom queries section in Theme settings. |
device_visibility |
— | String unless stated otherwise | Applies the selected responsive visibility rule. |
el_id |
— | Valid unique HTML ID | Enter element ID (Note: make sure it is unique and valid according to w3c specification). |
el_class |
— | String unless stated otherwise | If you wish to style a particular content element differently, then use this field to add a class name and then refer to it in your CSS file. |
Enclosed content
Content between the opening and closing tags is processed as WordPress shortcode content. Keep the parent/child structure shown by the visual builder so nested components receive the context they expect.
Finder composition
This tag belongs to the Finder component family. Preserve its generated parent, row, column, and field nesting when editing raw shortcode content.
Verification
Populate web_finder with web_finder_row and confirm every child remains reachable in the intended order. Pay particular attention to web_finder_action and web_auto_submit.
Shared behavior and limits
Use one results field and up to 50 controls per Finder. Blank action uses POST; a destination uses GET and must contain a matching Finder ID. AJAX always updates the current form. Shared URLs may preselect authored fields without form_submit. A supplied form_id must match the target Finder. Multiple forms remain isolated; IDs must be unique per page. Sorting, filters and page size are validated against authored fields.
Only current published, password-free public content allowed by the visitor's post-type permissions is returned. Saved query page sizes and all-results selections are preserved. Page-size controls accept only authored positive integers or -1 for all results. Public taxonomy and author choices are not truncated at 200; page numbers remain limited to 1,000. Missing queries fail closed. Loading, empty and error feedback use existing theme markup. A basic Finder does not load gallery/carousel assets; field and result dependencies remain conditional with Page Builder administration enabled or disabled.
Public Finder pages support static HTML caching. Their signed configuration has no time-based or visitor-session expiry; every AJAX request still checks the current saved query and content permissions. Keep AJAX responses out of the page cache. Purge a page when changing its authored fields or result layout so visitors receive those changes.
Previously cached WPAS forms can recover from a published page with a same-site referrer, including identifiable multiple forms and forms in explicitly included published content, synced patterns or native text/block widgets. Equivalent duplicate configurations are accepted. Forms that cannot be distinguished from their old saved fields and query identity, archive-only sources, dynamically generated widgets or withheld referrers require fresh page HTML. Protected sources remain unavailable. Client-provided query arrays and template paths are never executed. No database migration or shortcode renaming is required. Result layout and columns belong to web_finder_content_results_field, not this parent.
When Relevanssi is active, text searches retain that provider's query handling. The wpas_response_filter hook receives the result array, current WP_Query and validated request values. Responses contain rendered cards and public result metadata; extensions should not add query objects, private data or executable template paths to them.
Legacy radio and checkbox fields preserve the WPAS group/container classes and adjacent input/label structure for existing site CSS. Blank field labels do not create a visible generic heading. Taxonomy choices retain ancestors with matching descendants. Initial WooCommerce results retain catalogue visibility filters without adding an empty taxonomy condition.