How it works

Locator turns your locator_store posts into a searchable directory. This page explains exactly how it renders, how the search behaves, and what its accessibility markup does.

Server-side rendering first

When a page contains the [locator] shortcode, Locator queries every published location and prints them as cards directly in the HTML, a single list, ordered by the page-attributes Order value then alphabetically by name. Because the cards are in the page from the start, the directory works with JavaScript disabled and search engines see the full content. If no locations are published yet, the shortcode prints a short “No store locations have been added yet.” message instead.

Each card

A card shows the store name (always), then any toggled field that has a value:

• Address, rendered as an <address> block: street line, then postcode + city, then country, with blank parts skipped.
• Opening hours, shown under an “Opening hours” label, line breaks preserved as you typed them.
• Phone, a click-to-call link; the visible text keeps your formatting, while the tel: href is stripped to digits and +.

Email, the post description, the featured image and coordinates are not printed by the current template.

Instant client-side filtering

When JavaScript is available and the search box is on, typing filters the cards already on the page. The match is a case-insensitive substring test against a per-card haystack built from name, address, city, postcode and country, so a shopper can find a shop by any of those, not just the city. Input is debounced (about 120 ms) so fast typing stays smooth.

No request is made and no data leaves the page. The result count above the list updates live, it shows the total when nothing is typed, and visible / total while filtering, and is announced through an ARIA live region (role="status", aria-live="polite"). When nothing matches, a “No locations match your search.” line appears.

If the search box is turned off in settings, no field renders and the full list simply shows.

Without JavaScript

Every card is server-rendered, so with JavaScript disabled the complete list is present and readable. Only the live filtering is unavailable, there is no functionality hidden behind a script.

Accessibility

• The search field has a real, visible label (“Find a store”) and a descriptive placeholder, and is fully keyboard-operable.
• The result count is a live region, so screen-reader users hear how many stores match as they type.
• Cards and the phone link use focus-visible outlines for keyboard users.
• The decorative map-pin icon is aria-hidden, so it is not announced.
• Storefront styles follow prefers-color-scheme (light/dark) and honour prefers-reduced-motion, which disables the subtle “narrowing” pin animation that plays as the list filters.

Performance

Locator registers its stylesheet and script on wp_enqueue_scripts but only enqueues them in the footer when the shortcode actually rendered on that request, pages without [locator] ship none of its assets. The script is plain vanilla JavaScript with no jQuery and no external request. Cards reserve their space, so filtering and load add no Cumulative Layout Shift.

Customising the markup

Locator does not support theme template overrides, the storefront template is loaded only from inside the plugin, so a copy in your theme is not picked up. To restyle the directory, target its classes (.locator, .locator__card, .locator__name, .locator__address, .locator__hours, .locator__phone, and the .locator__search block) from your theme stylesheet. The storefront CSS is built for this, and there are no merchant- or developer-facing filters or actions in the free edition to alter the output in PHP.