WS-StoreLocatore

Generic, fast store locator plugin for WordPress with a modern UI and dual map providers (Google Maps or OpenStreetMap/Leaflet). It renders a searchable sidebar list and an interactive map with custom marker icons, hours, services/products, and built‑in directions.

Features

• Dual map providers: Google Maps or OpenStreetMap (Leaflet) fallback
• Search box with optional Google Places Autocomplete (when API key is provided)
• Sidebar list with collapsible sections for Open Hours, Fuel Available, and Services & Amenities
• Geolocation “Locate Me” button to pan the map to the user
• Directions:
  • Popup: “Get directions” opens Google Maps in a new tab
  • Sidebar: “Directions” draws the route directly on the site (OSRM for Leaflet, Google Directions for Google)
• Custom marker icons per store + global default icon set in settings
• Optional marker clustering
• CSV import with sample file (supports icons and hours)
• Clean REST API endpoint that returns store data for the frontend

Requirements

• WordPress 5.8+ (recommended)
• PHP 7.4+ (recommended)
• Optional: Google Maps API key (required to use Google Maps provider and Places Autocomplete)

Installation

1. Copy the plugin folder to wp-content/plugins/wp-storelocatore.
2. In the WordPress admin, go to Plugins and activate “WS‑StoreLocatore”.
3. Go to Stores → Settings to configure:
   • Map Provider: Google Maps or OpenStreetMap (Leaflet). If Google is selected without an API key, Leaflet is used automatically.
   • Google Maps API Key.
   • Default Marker Icon (chosen via the WordPress media library).
   • Enable Clustering.
   • Map Height (e.g., 600px, 60vh).
   • Default Zoom (1–21).

Creating Stores

Add stores using the custom post type:

• In the admin, go to Stores → Add Store.
• Fill in Title, Address, Phone, Website, Latitude, and Longitude.
• Add Open Hours (per day), Services & Amenities, and Fuel Available (Products).
• You can attach icons to individual services/products via the media picker.
• Optionally set a per‑store custom marker icon. If unset, the global default icon is used.

Shortcode Usage

Place the shortcode on any page where you want the locator to appear:

[ws_store_map]

Attributes (optional — they override settings):

• height: CSS size for the map container. Example: [ws_store_map height="700px"]
• zoom: Initial zoom level (1–21). Example: [ws_store_map zoom="10"]
• center: Initial center as lat,lng. Example: [ws_store_map center="37.7749,-122.4194"]

Examples:

[ws_store_map]
[ws_store_map height="500px" zoom="12"]
[ws_store_map center="40.7128,-74.0060" zoom="11"]

Map Behavior

• Leaflet/OpenStreetMap:

  • Tiles from OpenStreetMap.
  • Routing uses the public OSRM API to draw a polyline on the site.
  • Marker clustering is enabled when “Enable Clustering” is checked.

• Google Maps:

  • Requires an API key.
  • Directions use DirectionsService + DirectionsRenderer to draw on the site.
  • Places Autocomplete powers the search box, when enabled.

Directions Actions

• Popup: “Get directions” opens Google Maps externally in a new tab.
• Sidebar list: the “Directions” button uses geolocation as origin and draws the route directly on the site.

Note: users must grant location permission for on‑site directions to work. If geolocation is denied or unavailable, the route cannot be drawn.

CSV Import

Import stores from a CSV via Stores → Import CSV.

• Download the sample CSV from the Import page.
• Supported columns include: title,address,phone,website,lat,lng,services,products,hours_mon,...,hours_sun,icon_id.
• Services/products items may carry icons using Name|ICON_ID or Name|ICON_URL. Commas or semicolons are accepted as separators.
• Advanced: services_json and products_json accept JSON arrays of { name, icon_id | icon_url }.

REST API

The frontend consumes a single route to load store data:

• GET /wp-json/ws-storelocatore/v1/stores

Each store includes fields like: id, title, address, phone, website, lat, lng, services[], products[], hours{}, icon_url, permalink.

Styling & Customization

• Core styles are in assets/css/storelocatore.css.
• You can override or extend styles in your theme. Common targets:
  • .ws-store-map-wrapper, .ws-store-sidebar, .ws-store-item
  • .ws-infowindow .ws-directions-ext and .ws-store-actions .button

Demo (for development)

For a quick demo outside WordPress, open assets/demo.html with a static server:

cd wp-content/plugins/wp-storelocatore
python3 -m http.server 8000
# Open http://localhost:8000/assets/demo.html

Troubleshooting

• Media picker not opening: ensure the WordPress media scripts load (the plugin enqueues them on settings and store edit screens).
• On‑site directions not drawing: users must allow geolocation; the OSRM service may be temporarily unavailable; Google provider requires a valid API key.
• Markers missing: verify each store has valid lat and lng values.
• Search autocomplete not appearing: requires Google Maps API key; otherwise the search works as a simple text filter.

Version

• Current plugin version: 0.2.0