MyClub/DOCS/MAP_LINK_IMPORT_FEATURE.md

Map Link Import Feature

Overview

This feature allows administrators to easily import map coordinates from popular map services (mapy.cz and Google Maps) by simply pasting a URL. The system automatically extracts coordinates and displays a live preview of the location.

Implementation Summary

1. URL Parser Utility (src/utils/mapUrlParser.ts)

Purpose: Parse map URLs from various sources and extract coordinates

Features:

• Supports mapy.cz URLs (mapy.com/mapy.cz domains)
• Supports Google Maps URLs (various formats)
• Automatic protocol detection and normalization
• Coordinate validation
• Extracts: latitude, longitude, zoom level, and location name (when available)

Supported URL Formats:

• mapy.cz: mapy.com/en/letecka?x=17.6996859&y=50.0947150&z=19
• Google Maps:
  • google.com/maps/place/@50.0946232,17.6987331,226m
  • google.com/maps/@lat,lng,zoom
  • google.com/maps?q=lat,lng

Example Usage:

import { parseMapUrl } from './utils/mapUrlParser';

const result = parseMapUrl('mapy.com/en/letecka?x=17.6996859&y=50.0947150&z=19');
// Returns: {
//   latitude: 50.0947150,
//   longitude: 17.6996859,
//   zoom: 19,
//   address: 'krnov stadion',
//   source: 'mapy.cz'
// }

2. MapLinkImporter Component (src/components/admin/MapLinkImporter.tsx)

Purpose: React component for importing map coordinates with live preview

Features:

• URL input field with real-time parsing
• Automatic recognition of map service (mapy.cz/Google Maps)
• Visual feedback with success/error messages
• Live map preview using existing ContactMap component
• Shows parsed coordinates, zoom level, and location name
• Import button to apply coordinates to settings
• Manual coordinate override support

Props:

interface MapLinkImporterProps {
  onImport: (coordinates: MapCoordinates) => void;
  currentLatitude?: number;
  currentLongitude?: number;
  currentZoom?: number;
}

3. Settings Admin Page Integration (src/pages/admin/SettingsAdminPage.tsx)

Purpose: New "Kontakt & Mapa" tab in admin settings

Added Features:

• New tab: "Kontakt & Mapa" between "Sociální sítě" and "Videa"
• Contact information fields:
  • Address (street)
  • City
  • Postal code
  • Country
  • Phone
  • Email
• Map coordinate import section with MapLinkImporter component
• Manual coordinate input (latitude, longitude, zoom)
• Map display toggle for homepage
• Map style selection (Default/Dark/Satellite)

4. Updated Type Definitions (src/services/settings.ts)

New AdminSettings Fields:

{
  contact_address?: string;
  contact_city?: string;
  contact_zip?: string;
  contact_country?: string;
  contact_phone?: string;
  contact_email?: string;
  location_latitude?: number;
  location_longitude?: number;
  map_zoom_level?: number;
  show_map_on_homepage?: boolean;
  map_style?: 'default' | 'dark' | 'satellite';
}

Usage Instructions

For Administrators:

1. Navigate to Settings:

   • Go to Admin Panel → Settings
   • Click on "Kontakt & Mapa" tab

2. Import from Map URL:

   • Copy a URL from mapy.cz or Google Maps
   • Paste it into the "Importovat z URL mapy" field
   • The system will automatically:
     • Parse the coordinates
     • Display the location details
     • Show a live map preview
   • Click "Importovat" to apply the coordinates

3. Manual Entry (Alternative):

   • Scroll to "Ruční nastavení souřadnic"
   • Enter latitude, longitude, and zoom level manually

4. Configure Display:

   • Toggle "Zobrazit mapu na titulní stránce" to show/hide map on homepage
   • Select map style (Default, Dark, or Satellite)

5. Save Settings:

   • Click "Uložit nastavení" at the bottom of the page

Example URLs to Test:

mapy.cz:

mapy.com/en/letecka?q=krnov%20stadion&source=firm&id=12954454&ds=2&x=17.6996859&y=50.0947150&z=19

Google Maps:

www.google.com/maps/place/Fotbalový+stadión/@50.0946232,17.6987331,226m/data=!3m1!1e3!4m10!1m2!2m1!1skrnov+stadion!3m6!1s0x4711826a3559a643:0x4d71cca773c76501!8m2!3d50.0948669!4d17.7001456

Technical Details

Files Created:

1. src/utils/mapUrlParser.ts - URL parsing utility
2. src/utils/mapUrlParser.test.ts - Test suite
3. src/components/admin/MapLinkImporter.tsx - Import component

Files Modified:

1. src/pages/admin/SettingsAdminPage.tsx - Added new tab and integration
2. src/services/settings.ts - Extended AdminSettings type

Testing

Running Tests:

npm test -- mapUrlParser.test.ts

Manual Testing:

1. Navigate to /admin/settings
2. Go to "Kontakt & Mapa" tab
3. Paste one of the example URLs
4. Verify the coordinates are correctly extracted
5. Check that the map preview displays correctly
6. Click "Importovat" and verify coordinates are applied
7. Save settings and verify they persist

Benefits

✅ User-Friendly: No need to manually find coordinates ✅ Accurate: Directly extracts coordinates from map URLs ✅ Visual Feedback: Live map preview before importing ✅ Flexible: Supports multiple map services ✅ Robust: Validates coordinates and handles errors ✅ Integrated: Works seamlessly with existing ContactMap component

Future Enhancements (Optional)

• Add support for more map services (OpenStreetMap, Bing Maps, etc.)
• Geocoding: Convert address to coordinates automatically
• Reverse geocoding: Auto-fill address from coordinates
• Map marker drag-and-drop for coordinate selection
• Batch import for multiple locations

Backend Requirements

The backend should support the following fields in the settings model:

• contact_address (string)
• contact_city (string)
• contact_zip (string)
• contact_country (string)
• contact_phone (string)
• contact_email (string)
• location_latitude (float/double)
• location_longitude (float/double)
• map_zoom_level (integer)
• show_map_on_homepage (boolean)
• map_style (enum: 'default', 'dark', 'satellite')

These should be added to the existing settings table/model.