# GorillaDash WordPress Plugin

A comprehensive WordPress plugin for integrating GorillaDash services, providing three main components: an interactive store locator map, an enquiry form with tribe search, and a single-store map display.

## Features

- **📝 Enquiry Form Component**: Lead generation form with Google Places autocomplete and nearby store search
- **🗺️ Store Locator Map**: Interactive Google Maps with address search and tribe location finder
- **📍 Single Store Map**: Display individual store locations with auto-detected tribe data
- **🎛️ Gutenberg Block Support**: Modern block editor integration with visual controls
- **🌍 Country Restrictions**: Configurable geographic limitations for map searches
- **⚙️ Admin Settings Panel**: Complete configuration management
- **🔒 Security**: WordPress nonce verification and data sanitization

## Installation and Setup

1. Upload the plugin folder to `wp-content/plugins/` directory
2. Activate the plugin in WordPress admin backend
3. Go to **Settings > GorillaDash** to configure your settings

## Configuration Requirements

### API Credentials
- **API Key**: Your GorillaDash API Key
- **API Secret**: Your GorillaDash API Secret

### Google Maps Integration
- **Google Map Key**: Google Maps API key with the following services enabled:
  - Maps JavaScript API
  - Places API
  - Geocoding API

### Map Default Settings
- **Default Latitude**: Map center latitude (default: 36.76838)
- **Default Longitude**: Map center longitude (default: -96.15804)
- **Default Zoom Level**: Map zoom level 1-20 (default: 4)
- **Country Restriction**: 2-letter ISO country code (default: "us")
- **Tribe Path**: URL path prefix for tribe pages (default: "locations")

## Component Overview

### 1. Gorilla Dash Enquiry Form
An interactive form component that combines lead generation with store locator functionality. Users can search for nearby stores using address autocomplete, select their preferred location, and submit enquiry information with dynamic form fields fetched from the GorillaDash API.

**Key Features:**
- Google Places address autocomplete
- Real-time nearby store search
- Dynamic form fields from API
- Store selection interface
- Automated tribe association

### 2. Gorilla Dash Store Locator
A full-featured interactive map for searching and displaying multiple store locations. Users can search by address and view nearby stores with detailed information cards.

**Key Features:**
- Google Maps integration
- Address search with geocoding
- Multi-store display and search
- Configurable map settings
- Interactive search results

### 3. Gorilla Dash Store Map
A focused map component for displaying a single store location. Automatically detects the tribe slug from the URL path or shortcode parameter and displays the store's location on the map.

**Key Features:**
- Single store display
- Auto-detect tribe from URL
- Google Maps integration
- Store information display
- Dynamic tribe data loading

## Usage Guide

### Method 1: Gutenberg Blocks (Recommended)

#### Enquiry Form Block
1. Add a new block in the WordPress editor
2. Search for "GorillaDash Enquiry" or "Enquiry Component"
3. Configure in the right sidebar:
   - Enquiry Form Slug
   - Default Tribe Slug
   - Page Slug (optional)

#### Store Locator Map Block
1. Add a new block in the WordPress editor
2. Search for "GorillaDash Map" or "Map Block"
3. Configure map dimensions and settings:
   - Map dimensions (width/height)
   - Default coordinates and zoom
   - Country restrictions

#### Store Map Block
1. Add a new block in the WordPress editor
2. Search for "GorillaDash Store Map"
3. Configure:
   - Tribe Slug (or leave empty to auto-detect from URL)
   - Map dimensions (width/height)

### Method 2: Shortcodes

#### Enquiry Form Shortcode
```
[gorilladash_enquiry enquiry_form_slug="revscale-inquiry" tribe_slug="fl-demo" page_slug=""]
```

**Parameters:**
- `enquiry_form_slug`: The slug of the enquiry form in GorillaDash (default: "revscale-inquiry")
- `tribe_slug`: Default tribe slug for form submission (default: "fl-demo")
- `page_slug`: Page identifier for tribe detection (optional, auto-detected from URL if empty)

**Usage Examples:**
```
<!-- Basic usage with defaults -->
[gorilladash_enquiry]

<!-- Custom form and tribe -->
[gorilladash_enquiry enquiry_form_slug="contact-form" tribe_slug="miami-store"]

<!-- With specific page slug -->
[gorilladash_enquiry enquiry_form_slug="contact-form" tribe_slug="miami-store" page_slug="miami"]
```

#### Store Locator Map Shortcode
```
[gorilladash_map height="500px" width="100%" defaultLat="36.76838" defaultLng="-96.15804" defaultZoom="4" countryRestriction="us"]
```

**Parameters:**
- `height`: Map container height (default: "500px")
- `width`: Map container width (default: "100%")
- `defaultLat`: Default map center latitude (default: admin setting)
- `defaultLng`: Default map center longitude (default: admin setting)
- `defaultZoom`: Default zoom level 1-20 (default: admin setting)
- `countryRestriction`: 2-letter ISO country code (default: admin setting)

**Usage Examples:**
```
<!-- Basic usage with defaults -->
[gorilladash_map]

<!-- Custom dimensions -->
[gorilladash_map height="600px" width="100%"]

<!-- Custom location and zoom -->
[gorilladash_map defaultLat="40.7128" defaultLng="-74.0060" defaultZoom="10"]

<!-- Restrict to specific country -->
[gorilladash_map countryRestriction="ca"]
```

#### Single Store Map Shortcode
```
[gorilladash_store_map tribe_slug="fl-demo" height="500px" width="100%"]
```

**Parameters:**
- `tribe_slug`: Tribe slug to display (default: "fl-demo", auto-detected from URL if available)
- `height`: Map container height (default: "500px")
- `width`: Map container width (default: "100%")

**Usage Examples:**
```
<!-- Auto-detect tribe from URL -->
[gorilladash_store_map]

<!-- Specific tribe -->
[gorilladash_store_map tribe_slug="miami-store"]

<!-- Custom dimensions -->
[gorilladash_store_map tribe_slug="miami-store" height="600px" width="100%"]
```

**URL Path Detection:**
The Store Map component automatically detects the tribe slug from URLs following this pattern:
- `/{base_path}/{state_abbreviated}/{tribe_slug}/` (e.g., `/locations/fl/miami-store/`)
- Configure the URL pattern in Settings > GorillaDash > Location Page Path
- Default pattern: `/locations/{state_abbreviated}/{slug}`
- The pattern uses `{state_abbreviated}` and `{slug}` as placeholders that are automatically replaced with actual values

## Component Features

### Enquiry Form Component Features

#### Address Search & Store Selection
- Google Places autocomplete with country restrictions
- Real-time nearby store search based on address
- Interactive store result cards
- Selected store confirmation display
- Ability to change selected store

#### Dynamic Form Fields
- Automatic form field retrieval from GorillaDash API
- Supports multiple field types:
  - Text, Email, Tel, URL inputs
  - Textarea for long-form content
  - Select dropdowns with options
  - Checkboxes
- Required field validation
- Field labels with required indicators

#### Form Submission
- AJAX-based form submission
- WordPress nonce security verification
- Email and phone validation
- Success/error message display
- Integration with GorillaDash enquiry API

### Store Locator Map Features

#### Address Search
- Google Places autocomplete with country restrictions
- Real-time address geocoding
- Interactive marker placement
- Automatic zoom to search results
- Clear search functionality

#### Store Search & Display
- Location-based tribe search via GorillaDash API
- Display multiple nearby stores
- Interactive result cards with selection
- Store information display (name, address, distance)
- Click-to-select store functionality

#### Map Customization
- Configurable default map position
- Adjustable zoom levels
- Country-specific search restrictions
- Responsive map sizing
- Custom map markers

### Single Store Map Features

#### Automatic Tribe Detection
- Auto-detect tribe slug from URL path
- Fallback to WordPress post slug
- Manual tribe slug override via shortcode
- Debug logging for troubleshooting

#### Store Display
- Single store location marker
- Store information display
- Auto-center map on store location
- Loading state management
- Error handling with user-friendly messages

#### Dynamic Data Loading
- AJAX-based tribe data retrieval
- Real-time store information updates
- Google Maps integration
- Responsive map display

## API Integration

### Enquiry Submission
- **Endpoint**: `enquiries`
- **Method**: POST
- **Authentication**: API Key and Secret headers
- **Data**: Form fields, tribe slug, contact information

### Form Fields Retrieval
- **Endpoint**: `enquiry-forms/{slug}`
- **Method**: GET
- **Authentication**: API Key and Secret headers
- **Returns**: Dynamic form field definitions

### Tribe Search by Coordinates
- **Endpoint**: `tribes/search?results=10`
- **Method**: POST
- **Authentication**: API Key and Secret headers
- **Data**: Latitude and longitude coordinates
- **Returns**: Array of nearby tribes with distance information

### Tribe Data by Slug
- **Endpoint**: `tribes/{slug}`
- **Method**: GET
- **Authentication**: API Key and Secret headers
- **Returns**: Complete tribe information (name, address, coordinates, etc.)

## About Gorilla Dash API

This plugin connects to the Gorilla Dash API to provide integrated information services, including:
- **Gorilla Dash Store Locator**: Display the Gorilla Dash Store Locator with address search and store location functionality.
- **Gorilla Dash Store Map**: Display a specific store location on Google Maps with detailed store information.
- **Gorilla Dash Inquiry Form**: A comprehensive inquiry form solution that integrates the store locator and contact form functionalities.

For data submission details, please refer to the API documentation for more information. If you have any questions, feel free to contact us.

**This service is provided by Gorilla Dash:**
- Privacy Policy: https://gorilladash.com/privacy
- API Documentation: https://docs.gorilladash.com/

## Technical Details

### Security Features
- WordPress nonce verification for all AJAX requests
- Input sanitization and validation
- Secure API credential storage
- XSS protection with proper escaping

### Performance Optimizations
- Lazy loading of Google Maps API
- Efficient marker management
- AJAX-based map interactions
- Minimal resource loading

### WordPress Integration
- Full Gutenberg block editor support
- WordPress coding standards compliance
- Proper hook and filter usage
- Translation-ready (i18n support)

### Browser Compatibility
- Modern browser support with fallbacks
- Mobile-responsive design
- Progressive enhancement approach

## File Structure

```
wp-content/plugins/gorilladash/
├── gorilladash-api.php          # Main plugin file
├── README.md                    # This documentation
├── test-page-template.php       # Testing template
└── assets/
    ├── gorilladash-api.js       # Form handling JavaScript
    ├── gorilladash-map.js       # Map functionality JavaScript
    ├── gorilladash-map-block.js # Gutenberg block JavaScript
    └── gorilladash-api.css      # Plugin styles
```

## Testing

Use the provided test template (`test-page-template.php`) to create a WordPress page for testing map functionality.

## Troubleshooting

### Common Issues

1. **Map not loading**: Check Google Maps API key and enabled services
2. **Autocomplete not working**: Ensure Places API is enabled
3. **Country restriction not working**: Check 2-letter ISO country code format
4. **Tribe search failing**: Verify GorillaDash API credentials

### Debug Information

- Check browser console for JavaScript errors
- Review WordPress debug.log for PHP errors
- Verify API key restrictions and quotas
- Test with minimal theme/plugins for conflicts

## Support

For technical support and feature requests, please refer to the plugin documentation or contact your system administrator.

## Version History

- **1.0.0**: Initial release with map functionality
- Enhanced Gutenberg block support
- Added country restrictions
- Improved admin settings panel