Skip to main content

Suma Dealer Locator

Overview​

The Suma Dealer Locator plugin provides store/dealer location functionality with map display, proximity search, and category filtering. Users can find authorized Walkers retailers nearest to their location.

Plugin Details​

Plugin Name: Suma Dealer Locator
Version: 3.0.2
Developer: Rhino Group
Location: wp-content/plugins/suma-dealer-locator/
Namespace: Suma\DealerLocator\

Features​

  • Interactive Map: Google Maps integration with custom markers
  • Proximity Search: Find dealers by address, city, or ZIP code
  • Category Filtering: Filter by dealer type or product specialization
  • Responsive Design: Bootstrap-free responsive templates
  • Gutenberg Block: Native WordPress editor block
  • Visual Composer Support: Legacy VC integration
  • Elementor Widget: Custom Elementor integration
  • IP-Based Location: MaxMind GeoIP automatic location detection
  • Directions: Get directions link from user location to dealer

Directory Structure​

suma-dealer-locator/
├── suma-dealer-locator.php    # Main plugin file
├── readme.txt                 # Plugin readme
├── admin/                     # Admin interface
├── frontend/                  # Public-facing functionality
├── includes/                  # Core classes
│   ├── class-activator.php   # Activation logic
│   ├── class-deactivator.php # Deactivation logic
│   ├── class-suma-dealer-locator.php  # Main plugin class
│   ├── class-custom-routes.php        # REST API routes
│   ├── class-elementor-block.php      # Elementor widget
│   ├── class-elementor.php            # Elementor integration
│   ├── class-geo-ip-lookup.php        # GeoIP functionality
│   ├── class-utils.php                # Utility functions
│   └── class-visual-composer.php      # VC integration
├── framework/                 # Suma framework
├── templates/                 # Frontend templates
├── assets/                    # CSS, JS, images
├── languages/                 # Translation files
└── vendor/                    # Composer dependencies

Installation & Activation​

Activation Process​

When activated, the plugin:

  1. Creates custom post type: dealer
  2. Registers dealer taxonomies
  3. Flushes rewrite rules
  4. Creates database tables (if needed)
  5. Sets default options

Dependencies​

  • Carbon Fields: Custom field management (bundled)
  • MaxMind GeoIP: IP-based location detection (optional)
  • Google Maps API: Map display and geocoding (API key required)

Custom Post Type: Dealer​

Post Type: dealer
Supports: title, editor, thumbnail, excerpt
Hierarchical: No
Public: Yes (queryable)
Show in REST: Yes

Custom Fields (Carbon Fields)​

Dealer location data stored as post meta:

FieldTypePurpose
dealer_addressTextStreet address
dealer_cityTextCity
dealer_stateText/SelectState/province
dealer_zipTextPostal code
dealer_countrySelectCountry
dealer_phoneTextPhone number
dealer_emailEmailContact email
dealer_websiteURLDealer website
dealer_latitudeHiddenGeocoded latitude
dealer_longitudeHiddenGeocoded longitude

Taxonomies​

dealer_category:

  • Hierarchical: Yes
  • Purpose: Categorize dealers (e.g., "Authorized Retailer", "Service Center")

Shortcodes​

Main Dealer Locator​

[suma_dealer_locator]

Attributes:

  • categories — Comma-separated category IDs or slugs to filter
  • radius — Default search radius in miles (default: 25)
  • zoom — Initial map zoom level (default: 10)
  • height — Map height in pixels (default: 500)

Example:

[suma_dealer_locator categories="authorized-retailer" radius="50" height="600"]

Gutenberg Block​

Block Name: Suma Dealer Locator
Category: Widgets
Icon: Location marker

Settings:

  • Category selection
  • Default radius
  • Map height
  • Initial zoom level

Elementor Widget​

Widget Name: Suma Dealer Locator
Category: Suma Widgets

Controls:

  • Map Settings: Height, zoom, center point
  • Search Settings: Default radius, units (miles/km)
  • Filter Settings: Enable/disable category filters
  • Style Settings: Colors, fonts, spacing

Frontend Functionality​

Search Flow​

User enters address/ZIP
    ↓
Geocode address via Google Maps API
    ↓
Query dealers by proximity (SQL with Haversine formula)
    ↓
Display results on map + in list
    ↓
User clicks marker or listing
    ↓
Show dealer info window

Proximity Search Query​

Uses Haversine formula to calculate distance:

SELECT *,
  ( 3959 * acos(
    cos( radians( :user_lat ) ) *
    cos( radians( dealer_latitude ) ) *
    cos( radians( dealer_longitude ) - radians( :user_lng ) ) +
    sin( radians( :user_lat ) ) *
    sin( radians( dealer_latitude ) )
  ) ) AS distance
FROM dealers
HAVING distance < :radius
ORDER BY distance ASC
LIMIT :limit

Units:

  • Miles: 3959 (Earth radius in miles)
  • Kilometers: 6371 (Earth radius in km)

GeoIP Auto-Location​

MaxMind Integration (class-geo-ip-lookup.php):

  1. Detect user's IP address
  2. Query MaxMind GeoIP database
  3. Get approximate latitude/longitude
  4. Auto-populate search field with detected location

Fallback: Browser geolocation API (requires user permission)

Templates​

Template Hierarchy​

Plugin templates can be overridden in theme:

Plugin Location: plugins/suma-dealer-locator/templates/
Theme Override: themes/your-theme/suma-dealer-locator/

Available Templates​

  • dealer-locator.php — Main locator interface
  • dealer-list.php — Dealer list display
  • dealer-map.php — Map container
  • dealer-info-window.php — Map marker popup
  • dealer-filters.php — Category filter UI
  • dealer-search-form.php — Search input form

Template Example​

<?php
/**
 * Theme override: suma-dealer-locator/dealer-locator.php
 */
?>
<div class="suma-dealer-locator">
    <?php echo do_action('suma_dealer_locator_before_search'); ?>
    
    <div class="dealer-search">
        <input type="text" id="dealer-search-input" placeholder="Enter ZIP or address">
        <button id="dealer-search-btn">Search</button>
    </div>
    
    <div class="dealer-map" id="dealer-map"></div>
    
    <div class="dealer-results" id="dealer-results">
        <!-- Results populated via AJAX -->
    </div>
</div>

REST API Endpoints​

Search Dealers​

Endpoint: /wp-json/suma-dealer-locator/v1/search
Method: GET

Parameters:

  • lat (required) — User latitude
  • lng (required) — User longitude
  • radius (optional) — Search radius in miles (default: 25)
  • categories (optional) — Comma-separated category IDs
  • limit (optional) — Maximum results (default: 20)

Response:

{
  "dealers": [
    {
      "id": 123,
      "name": "Joe's Gun Shop",
      "address": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "phone": "(555) 123-4567",
      "website": "https://joesgunshop.com",
      "latitude": 39.7817,
      "longitude": -89.6501,
      "distance": 2.34,
      "categories": ["Authorized Retailer"]
    }
  ],
  "count": 1
}

Geocode Address​

Endpoint: /wp-json/suma-dealer-locator/v1/geocode
Method: GET

Parameters:

  • address (required) — Address string to geocode

Response:

{
  "latitude": 39.7817,
  "longitude": -89.6501,
  "formatted_address": "Springfield, IL 62701, USA"
}

JavaScript API​

Map Initialization​

// Included in plugin assets
SumaDealerLocator.init({
  mapElement: '#dealer-map',
  defaultRadius: 25,
  zoomLevel: 10,
  markerIcon: '/path/to/custom-marker.png'
});

Events​

Dealer selected:

jQuery(document).on('dealer_selected', function(e, dealer) {
  console.log('Selected dealer:', dealer);
});

Search completed:

jQuery(document).on('dealer_search_complete', function(e, results) {
  console.log('Found dealers:', results.length);
});

Styling​

CSS Classes​

Main wrapper classes:

  • .suma-dealer-locator — Overall container
  • .dealer-search — Search form container
  • .dealer-map — Map container
  • .dealer-results — Results list container
  • .dealer-card — Individual dealer card
  • .dealer-info-window — Map popup content

Responsive Breakpoints​

  • Mobile: < 768px (single column, map below search)
  • Tablet: 768px - 1024px (side-by-side layout)
  • Desktop: > 1024px (full layout with filters)

Configuration​

Google Maps API Key​

Location: WordPress admin → Settings → Suma Dealer Locator

Required APIs:

  • Maps JavaScript API
  • Geocoding API
  • Places API (optional, for autocomplete)

MaxMind GeoIP​

Setup:

  1. Download MaxMind GeoLite2 database
  2. Upload to wp-content/uploads/geoip/
  3. Configure path in plugin settings

Database Update: Monthly (automated via wp-cron)

Changelog​

Version 3.0.2 (Current)​

  • Fixed broken Visual Composer blocks after refactoring
  • Improved compatibility with latest VC version

Version 3.0.1​

  • Fixed broken Visual Composer blocks after refactoring

Version 3.0.0​

  • Added: Gutenberg editor block with sidebar settings
  • Converted: Front-end templates to remove Bootstrap CSS dependency
  • Improved: Descriptions on default options
  • Removed: ACF dependency, integrated Carbon Fields

Version 2.0.6​

  • Integrated MaxMind IP lookup for auto-loading locations

Version 2.0.5​

  • Added pin bounce on listing hover
  • Added "Get Directions" functionality in map info box
  • Added dynamic zoom based on bounding shape of closest 10 locations

Version 2.0.4​

  • Fixed category filter
  • Added "Get Directions" feature

Version 2.0.0​

  • Added Suma Framework integration
  • Reworked for scalability

Performance Considerations​

Database Optimization​

  • Indexes: Add indexes on dealer_latitude and dealer_longitude meta keys
  • Caching: Geocode results cached as transients (24 hours)
  • Pagination: Limit initial results to 20, load more on demand

Asset Loading​

  • Conditional loading: Only load on pages with shortcode/widget
  • Deferred Maps API: Load Google Maps JS asynchronously
  • Minified assets: Production CSS/JS minified

Troubleshooting​

Map Not Displaying​

  1. Verify Google Maps API key is set
  2. Check browser console for API errors
  3. Ensure API key has required APIs enabled
  4. Verify billing is enabled (Google requires CC on file)

No Results Found​

  1. Check that dealers have latitude/longitude populated
  2. Verify geocoding is working (test address in Geocoding API directly)
  3. Increase search radius
  4. Check category filters are not over-restrictive

GeoIP Not Working​

  1. Verify MaxMind database exists in correct path
  2. Check database file permissions (readable by PHP)
  3. Ensure cron job is updating database
  4. Fallback to manual entry or browser geolocation

Next Steps​