@grdistro/store-locator-widget
Version:
A modular store locator widget with Mapbox integration that can be embedded in any website
259 lines (206 loc) • 6.13 kB
Markdown
# Store Locator Widget
A modular, embeddable store locator widget that can be easily integrated into any website.
[](https://badge.fury.io/js/@your-org%2Fstore-locator-widget)
[](https://opensource.org/licenses/MIT)
## Features
- 🗺️ Interactive map integration (Mapbox support)
- 🔍 Store search and filtering
- 📍 Geolocation support
- 📱 Mobile responsive design
- 🎨 Customizable themes and styling
- 🔧 Simple JavaScript API
- 🚀 Easy integration with any website
## Installation
### NPM Installation
```bash
npm install @your-org/store-locator-widget
```
### CDN Usage
```html
<script src="https://unpkg.com/@your-org/store-locator-widget@latest/store-locator.min.js"></script>
```
### Download and Host
Download the latest release and include the script:
```html
<script src="store-locator.js"></script>
```
## Quick Start
### NPM Usage
```javascript
import StoreLocator from '@your-org/store-locator-widget';
const storeLocator = new StoreLocator({
containerId: 'store-locator',
stores: [/* your stores */]
});
```
### Script Tag Usage
### 2. Create a Container
```html
<div id="store-locator"></div>
```
### 3. Initialize the Widget
```javascript
const storeLocator = new StoreLocator({
containerId: 'store-locator',
stores: [
{
id: 1,
name: 'Store Name',
address: '123 Main St, City, State 12345',
phone: '(555) 123-4567',
latitude: '40.7580',
longitude: '-73.9855',
isOpen: true
}
]
});
```
## Configuration Options
```javascript
const config = {
// Required
containerId: 'store-locator', // ID of container element
// Store Data
stores: [], // Array of store objects
apiEndpoint: '/api/stores', // API endpoint for loading stores
// Map Configuration
mapboxToken: 'your-token', // Mapbox access token
// UI Options
height: '600px', // Widget height
showSearch: true, // Show search bar
showFilters: true, // Show filter buttons
showMap: true, // Show map component
theme: 'light', // Theme: 'light' or 'dark'
// Callbacks
onStoreSelect: (store) => {}, // Called when store is selected
};
```
## Store Object Format
```javascript
{
id: 1, // Unique identifier
name: 'Store Name', // Store name
address: '123 Main St...', // Full address
phone: '(555) 123-4567', // Phone number
latitude: '40.7580', // Latitude coordinate
longitude: '-73.9855', // Longitude coordinate
isOpen: true, // Current open status
// Optional fields
website: 'https://...', // Store website
hours: {...}, // Operating hours
services: [], // Available services
}
```
## API Methods
```javascript
// Add a new store
storeLocator.addStore(storeObject);
// Remove a store
storeLocator.removeStore(storeId);
// Update store information
storeLocator.updateStore(storeId, updates);
// Get currently selected store
const selected = storeLocator.getSelectedStore();
// Destroy the widget
storeLocator.destroy();
```
## Events
```javascript
// Listen for store selection
document.getElementById('store-locator').addEventListener('storeSelect', (event) => {
console.log('Selected store:', event.detail.store);
});
```
## Integration Examples
### Basic Integration
```html
<!DOCTYPE html>
<html>
<head>
<title>My Store Locator</title>
</head>
<body>
<div id="store-locator"></div>
<script src="store-locator.js"></script>
<script>
new StoreLocator({
containerId: 'store-locator',
stores: [/* your stores */]
});
</script>
</body>
</html>
```
### With API Integration
```javascript
const storeLocator = new StoreLocator({
containerId: 'store-locator',
apiEndpoint: 'https://api.yoursite.com/stores',
mapboxToken: 'your-mapbox-token',
onStoreSelect: (store) => {
// Track analytics
gtag('event', 'store_select', {
store_id: store.id,
store_name: store.name
});
}
});
```
### Shopify Integration
```liquid
<!-- In your Shopify template -->
<div id="shopify-store-locator"></div>
<script src="{{ 'store-locator.js' | asset_url }}"></script>
<script>
const storeLocator = new StoreLocator({
containerId: 'shopify-store-locator',
apiEndpoint: '/apps/store-locator/api/stores',
theme: '{{ settings.theme_style }}',
onStoreSelect: (store) => {
// Shopify analytics
analytics.track('Store Selected', {
store_id: store.id,
store_name: store.name
});
}
});
</script>
```
### WordPress Integration
```php
// In your WordPress theme
function enqueue_store_locator() {
wp_enqueue_script('store-locator', get_template_directory_uri() . '/js/store-locator.js');
}
add_action('wp_enqueue_scripts', 'enqueue_store_locator');
```
```html
<!-- In your template -->
<div id="wp-store-locator"></div>
<script>
document.addEventListener('DOMContentLoaded', function() {
new StoreLocator({
containerId: 'wp-store-locator',
apiEndpoint: '<?php echo admin_url('admin-ajax.php'); ?>?action=get_stores',
});
});
</script>
```
## Styling
The widget uses CSS custom properties for easy theming:
```css
:root {
--primary-color: #3b82f6;
--secondary-color: #64748b;
--background-color: #ffffff;
--border-color: #e2e8f0;
--text-color: #1f2937;
}
```
## Browser Support
- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 79+
## License
MIT License - feel free to use in commercial and personal projects.