Dealer/Store Locator - Xtreme Locator
| 开发者 | williqs |
|---|---|
| 更新时间 | 2026年9月1日 05:43 |
| PHP版本: | 7.0 及以上 |
| WordPress版本: | 7.1 |
| 版权: | GPLv2 or later |
| 版权网址: | 版权信息 |
详情介绍:
A WordPress dealer locator / store locator plugin powered by Xtreme Locator. It outputs Xtreme Locator's embed forms directly into your page's HTML — the same markup Xtreme Locator normally distributes for direct embedding, packaged as a WordPress shortcode and widget so it can be dropped in anywhere without editing theme files or using an iframe on the search box itself.
Requires an Xtreme Locator account
This plugin is the WordPress integration for Xtreme Locator's location search service — it does not include location data or search logic of its own. You'll need a Site ID from an Xtreme Locator account to configure it:
- New to Xtreme Locator? Start a free trial. Xtreme Locator's free plan supports up to 15 locations at no cost, so smaller businesses can use this plugin without paying anything.
- Already have an account? Enter your Site ID under Settings → Xtreme Locator after installing.
type shortcode attribute or the site-wide default in Settings → Xtreme Locator:
zip— a single zip/postal code field (the original default).zip_distance— zip code plus a distance/radius field.international— a country dropdown plus a postal code field, powered by Xtreme Locator's own country-picker script.near_me— a single "Locations Near Me" button that uses the visitor's browser location (no typing required).
- Only one "International" search box can be placed per page. Xtreme Locator's country-picker script (
searchByCountryJS.php) targets fixed field IDs, so a second instance on the same page would conflict with the first. - I wasn't able to inspect Xtreme Locator's
searchByCountryJS.phporapi/search.jsscripts directly (they didn't return readable source through my tools), so the International and Near Me search types are implemented based on the embed code you provided plus reasonable assumptions about how those scripts behave. Please test both after installing — in particular, confirm the International search box still submits to your own site rather than being redirected elsewhere by Xtreme Locator's script, and that the Near Me results page renders a proper results page inside the iframe rather than raw data. - The "Postal code search not available for this country" message (see below) assumes Xtreme Locator's script disables or read-onlys the postal code field when a country doesn't support postal code search — that's the standard pattern for this kind of widget, but since I can't inspect their script directly, please verify it actually shows for an unsupported country after installing. If their script signals unavailability a different way, let me know what you observe and I can adjust the detection.
- The Custom Search Form field (Settings → Xtreme Locator → Custom Search Form) is stored and displayed as entered — it is not filtered through WordPress's usual HTML sanitization, since that would strip the
<form>/<input>/<select>elements a search form needs. Only paste code from a source you trust. A relative<form action="...">is automatically resolved against app.xtremelocator.com and results are routed into an iframe instead of navigating away, but surrounding markup (labels, layout, a stray "Back" link, etc.) is left exactly as pasted — trim a full copied page down to just the form and its buttons before pasting for the cleanest result.
安装:
- If you don't already have an Xtreme Locator account, start a free trial (free for up to 15 locations) to get your Site ID.
- In your WordPress admin, go to Plugins → Add New Plugin → Upload Plugin (or search "Xtreme Locator Search" if installing from the WordPress.org plugin directory).
- Install and Activate the plugin.
- Go to Settings → Xtreme Locator and enter your Site ID.
- Add the shortcode
[xtreme_locator_search]to any page or post, or add the "Xtreme Locator Search" widget to a sidebar. - Optionally revisit Settings → Xtreme Locator to adjust the search box's text, colors, layout, and the results iframe's width/height/scrollbar.
屏幕截图:
常见问题:
Do I need an Xtreme Locator account?
Yes. This plugin is the WordPress integration for Xtreme Locator's location search service; it needs a Site ID from an Xtreme Locator account to know which locations to search. Start a free trial if you don't have one — the free plan supports up to 15 locations at no cost.
Is there a free plan?
Yes, Xtreme Locator's free plan supports up to 15 locations. Larger location counts require a paid plan — see xtremelocator.com for pricing.
Nothing shows up where I placed the shortcode — what's wrong?
Most likely no Site ID has been entered yet. Site admins will see a short setup reminder in place of the search box; other visitors simply won't see anything until it's configured. Go to Settings → Xtreme Locator and enter your Site ID.
Does this use an iframe?
The search box itself is plain HTML — no iframe. After a visitor searches, the results are shown on your own site inside a sandboxed iframe pointed at Xtreme Locator, so the results (which can include a map or other embedded script) stay isolated from the rest of your page.
Can I have more than one search box, or different search types on different pages?
Yes. Add the shortcode with a type attribute wherever you like, e.g. [xtreme_locator_search type="near_me"]. The one exception is the "International" search type, which can only appear once per page (see Known Limitations).
更新日志:
1.8.8
- Updated the Screenshots section captions/order to match the actual screenshot images (search box, results with map, settings page) being added to the plugin's directory page assets.
- Renamed the plugin from "Xtreme Locator Search" to "Dealer/Store Locator - Xtreme Locator" (in both the plugin file's
Plugin Nameheader and this readme's title) — cosmetic only, the plugin's directory slug/URL (xtreme-locator-search) and everything else are unchanged. - Updated the Tags line and short description/first description paragraph to include "dealer locator" so the plugin surfaces for that search term on WordPress.org, alongside the existing "store locator" wording.
- Renamed the "Site ID (sid)" field label to "Account ID (sid)" on the Settings → Xtreme Locator page. Cosmetic only — the underlying
sidsetting, shortcode attribute, and everywhere else it's referenced are unchanged.
- Fixed: the 1.8.4 centering/label-font script was never actually reaching the page at all. It was attached to WordPress's own
jqueryscript handle, which most themes have already printed in<head>by the time a shortcode runs — andwp_add_inline_script()silently does nothing once its target handle has already been printed, so the fix never loaded no matter what the pasted embed code looked like. It's now attached to this plugin's own dedicated handle (loaded in the footer, after the shortcode has definitely run), the same technique already used by the "Near Me" script elsewhere in this plugin. Verified this time that the script tag itself is actually present in the rendered page.
- Fixed (for real this time — verified live against a reported page): the Custom Search Form still wasn't centering on some pages even after 1.8.2/1.8.3. Root cause traced to a page-builder layout where the content column is a flex item that hugs its own content width and doesn't center itself within its row — something CSS from inside that column can't correct, since the ancestor doing the misplacement is outside anything this plugin renders. A small script now runs once the page loads, finds that specific situation at runtime (only when it's actually present — it does nothing on a normal theme layout), and centers it. Verified against the reported page: box now sits centered instead of flush left.
- Added: field labels in pasted Custom Search Form code now follow the plugin's Font family setting and use the same readable label size as the built-in search types (1.1em), instead of whatever the pasted embed code hardcodes. Xtreme Locator's own embed markup typically sets each label's font-size inline with its own
!important, which no CSS rule — however specific or!important— can out-rank; only editing the element's own inline style directly can, so this is handled by the same runtime script as the centering fix above.
- Fixed: on a page whose theme/page-builder template wraps content in a column narrower than the "Custom search box width" setting (seen on a page using a page-builder "full width"/blank-canvas template), the setting had no visible effect at all. The previous CSS only ever shrank the box to fit its container (a max-width cap); it's now an explicit width, so the box actually resizes as configured, growing past a narrow container if needed.
- Fixed: once a box is wider than its immediate container, plain CSS centering (
margin: auto) can't center it — it just hangs off the container's right edge. The Custom Search Form's search box and results iframe now use a centering technique that works correctly even when the box is wider than the column it sits in.
- Fixed: the "Custom search box width" setting had no visible effect on some pasted embed code. The outer search-box container was resizing correctly, but a pasted
<table>or<form>with its own fixed width (common in older Xtreme Locator embed markup) was silently overriding it. Both are now forced to fill (not exceed) the box, so the width setting actually controls what's visible. - Fixed: the search box (both the built-in search types and the Custom Search Form) sat flush against the left edge of its container instead of centering. It now centers the same way the results iframe does.
- Fixed: the Custom Search Form's Reset/Clear button (when the pasted embed code has one) wasn't styled by the Button color setting at all. It now gets the plugin's own "xlocator-clear" class automatically, using the same Button color as the Search button — styled as an outline so the two stay visually distinguishable.
- Fixed: the Custom Search Form's results iframe sat flush against the left edge of the page instead of centering the way the built-in search types' results page does. The results iframe now centers itself within its container.
- Added a new "Custom search box width" setting (Settings → Xtreme Locator → Custom Search Form), so the Custom Search Form's box can be sized independently of "Form width" under Colors & Appearance, which still controls only the four built-in search types. Defaults to 600px.
- Added an optional "Custom Search Form" feature for search forms with a different field set than the four built-in types (Zip / Zip and Distance / International / Near Me). Paste an Xtreme Locator embed snippet into the new Settings → Xtreme Locator → Custom Search Form textarea, then place it on a page with the new
[xtreme_locator_custom_search]shortcode. - The pasted form's results are routed into an on-page iframe next to the form (results stay on your own site) via the form's
targetattribute — no parsing of the form's individual fields is required, so any field set works. - A relative
<form action="...">in the pasted code (e.g.findLocations.php) is automatically resolved against app.xtremelocator.com. - The pasted form's Submit button automatically picks up this plugin's button color/text color styling from Settings → Xtreme Locator → Colors & Appearance, matching the built-in search types.
<script>tags in the pasted code are stripped automatically; everything else is output as entered. This field is admin-only (Settings page,manage_options) and is intentionally not run through WordPress's usual HTML sanitization, since that would strip the<form>/<input>/<select>elements a search form needs — documented in both the field description and this readme.
- The "Advanced Search" link now routes through the plugin's own in-site results page (same sandboxed-iframe pattern used for regular searches) instead of navigating the visitor directly to app.xtremelocator.com.
- Fixed the Button color setting (Settings → Xtreme Locator → Colors & Appearance) not visibly applying to the Search button or the Advanced Search link on some themes. The plugin's own button color/text-color/border styling now takes precedence over theme button styles that were silently overriding it.
- Removed the "Powered By XtremeLocator" credit link feature entirely — the Settings checkbox, the option, and the front-end markup are all gone. It no longer exists in any form, on by default or otherwise.
- Updated defaults: Zip/Postal Code label defaults to "Zip Code" and placeholder to "Enter your zip code"; Distance placeholder defaults to "Enter search distance"; Advanced Search link defaults to off; results iframe defaults to 900px wide by 1100px tall. (Only affects sites that have never saved Settings → Xtreme Locator — existing saved settings are never overwritten.)
- Tested up to WordPress 7.1.
- Removed the hard-coded default Site ID (previously baked in for a single private install). The plugin now ships with no default Site ID, and clearly prompts site admins to enter their own under Settings → Xtreme Locator — with a link to start a free Xtreme Locator trial (free for up to 15 locations) if they don't have an account yet.
- Added a setup reminder shown to site admins (only) wherever the shortcode/widget is placed, or on the results page, if no Site ID is configured yet. Regular visitors simply see nothing until it's set up.
- Updated plugin metadata (Plugin URI, Author URI) and prepared the plugin/readme for listing in the WordPress.org plugin directory.
- The "International" search type's country-picker script is now properly enqueued via
wp_enqueue_script()instead of being printed as a raw<script>tag. - Added
uninstall.phpso the plugin's one stored option is removed when the plugin is deleted (not just deactivated). - Added an optional "Powered By XtremeLocator" credit link under the search box, off by default — an admin must explicitly opt in under Settings → Xtreme Locator. (Settings-only by design — not a shortcode attribute — so only the site administrator's own action can turn it on.)
- Fixed a Plugin Check error (missing translators comment) and two warnings (latitude/longitude sanitization not recognized by the automated scanner) flagged during WordPress.org submission review.
- On the Plugins list screen, this plugin's row now reads "Xtreme Locator by IQServices.com" in place of WordPress' default "By Xtreme Locator" credit line.
- Fixed inconsistent short description ("results shown instead of an iframe" vs. the actual sandboxed-iframe results page).
- The "Powered By XtremeLocator" credit link is now off by default; showing it requires an explicit admin opt-in (was previously on by default).
- The International search type's postal-availability watcher script is now attached via
wp_add_inline_script()instead of a raw inline<script>tag. - Added direct links to Xtreme Locator's terms of service and privacy policy in the readme's External Services section (previously linked only to the homepage).
- Removed the
show_powered_byshortcode attribute. The "Powered By XtremeLocator" credit link can now only be enabled from the site admin's own Settings → Xtreme Locator checkbox — not overridable via shortcode, so only the administrator's explicit action can turn it on.
- Fixed a black box appearing around the search box on some themes: many themes apply a default border/background to bare
<form>elements (e.g. for comment/contact forms), which was leaking into the search box since the plugin's own box styling lives on an inner wrapper, not the outer<form>tag. The outer element now explicitly resets border/background/box-shadow so only this plugin's own settings (or none, by default) show.
- International search type: the postal code field's placeholder now switches to a configurable message ("Postal code search not available for this country" by default, editable under Settings → Xtreme Locator or via the
postal_unavailable_textshortcode attribute) whenever Xtreme Locator's own script disables that field for the selected country.
- Added three more search types alongside the original Zip search: Zip and Distance, International (country + postal code), and Near Me (one button using the visitor's browser location). Choose the default under Settings → Xtreme Locator, or per-instance with a shortcode's
typeattribute. - All four search types now route their results through your own site's iframe results page — including Near Me, which Xtreme Locator's own code normally opens in a new tab on their domain.
- Added matching text settings/shortcode attributes:
dist_label,dist_placeholder,country_label,near_me_button_text.
- Added full customization for the search box under Settings → Xtreme Locator (and matching shortcode attributes): text/labels (heading, zip field label & placeholder, button text, advanced link text), colors & appearance (button, heading, text, background, border colors; border width; font family; form width), and layout (inline vs. stacked).
- Rebuilt the search box markup from an HTML
<table>to a semantic, flexbox-based layout for cleaner styling and better responsiveness.
- Added a Settings → Xtreme Locator admin page: configure the default Site ID, heading, Advanced Search link, and button color used by the shortcode/widget, plus the results iframe's width, height, and scrollbar behavior (auto / always / never).
- Widened the search box table and made the zip field/table responsive so the box no longer looks cramped in narrow columns.
- Results now display on your own WordPress domain inside a sandboxed iframe, instead of a raw server-side passthrough. This avoids running Xtreme Locator's results-page scripts with full trust in your site's page, while still keeping the visitor's address bar on your domain throughout.
- Added a "Open results in a new tab" fallback link under the iframe.
- (Superseded by 1.2.0) Results rendered on your own WordPress domain via a server-side fetch/passthrough instead of a redirect to app.xtremelocator.com.
- Added a friendly error message if the results service is unreachable or returns an unexpected response.
- Added a page title for the results page.
- Initial release. Converts the original XtremeLocator embed snippet (sid 1462) into a shortcode + widget, with escaping/sanitization and an external stylesheet in place of inline styles.