# GPS Map Quick Reference

## Basic Usage

```json
{
  "type": "gps-map",
  "options": {
    "tableName": "your_table",
    "latField": "latitude",
    "lngField": "longitude"
  }
}
```

## Common Patterns

### With Filtering
```json
{
  "tableName": "records",
  "filterField": "user_id",
  "listenColumn": "user_id"
}
```

### With Date Range
```json
{
  "tableName": "records",
  "dateRangeField": "timestamp",
  "timestampField": "timestamp"
}
```

### Color-Coded Markers
```json
{
  "typeField": "status",
  "markerColors": {
    "pending": "#fbbf24",
    "complete": "#10b981",
    "failed": "#ef4444"
  }
}
```

### With Path
```json
{
  "showPath": true,
  "pathColor": "#3b82f6",
  "timestampField": "created_at"
}
```

### Custom Info Windows
```json
{
  "infoWindowTemplate": "<div class='p-3'><h3>{{title}}</h3><p>{{description}}</p></div>"
}
```

## Template Variables

- `{{index}}` - Marker number
- `{{lat}}` - Latitude (6 decimals)
- `{{lng}}` - Longitude (6 decimals)
- `{{field_name}}` - Any record field
- Dates auto-formatted if field contains "date" or "_at"

## Enable Google Maps

```json
{
  "title": "My Module",
  "mapLibraries": {
    "provider": "google",
    "libraries": "geometry"
  }
}
```

## Row Actions

```json
{
  "rowActions": [
    { "label": "View on Map", "onClick": "showOnMap" }
  ]
}
```

```javascript
window.showOnMap = (record) => {
  // Switch to map tab
  // Dispatch filter event
};
```

## Full Example

```json
{
  "type": "tabs",
  "tabs": [
    {
      "label": "List",
      "elements": [
        {
          "type": "table",
          "options": {
            "tableName": "locations",
            "rowClick": "selectRecord",
            "rowActions": [
              { "label": "Map", "onClick": "viewOnMap" }
            ]
          }
        }
      ]
    },
    {
      "label": "Map",
      "elements": [
        {
          "type": "gps-map",
          "id": "myMap",
          "options": {
            "tableName": "locations",
            "latField": "latitude",
            "lngField": "longitude",
            "timestampField": "timestamp",
            "typeField": "type",
            "filterField": "location_id",
            "listenColumn": "location_id",
            "dateRangeField": "timestamp",
            "markerColors": {
              "primary": "#10b981",
              "secondary": "#3b82f6"
            },
            "showPath": true,
            "height": "600px",
            "titleTemplate": "{{type}} - {{name}}",
            "infoWindowTemplate": "<div class='p-3'><h3 class='font-bold'>{{name}}</h3><p>{{description}}</p><p class='text-xs'>{{timestamp}}</p></div>"
          }
        }
      ]
    }
  ]
}
```

## Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `tableName` | string | **required** | IndexedDB table name |
| `latField` | string | `latitude` | Latitude column |
| `lngField` | string | `longitude` | Longitude column |
| `timestampField` | string | `created_at` | Timestamp for sorting |
| `typeField` | string | `null` | Field for marker colors |
| `filterField` | string | `null` | Field to filter by |
| `filterValue` | any | `null` | Value for filter |
| `listenColumn` | string | `null` | Column for filter events |
| `dateRangeField` | string | `null` | Date field for range |
| `dateRange` | object | `null` | `{start, end}` |
| `height` | string | `600px` | Map height |
| `defaultZoom` | number | `12` | Initial zoom |
| `showPath` | boolean | `true` | Draw path line |
| `pathColor` | string | `#3b82f6` | Path color |
| `markerColors` | object | `{default:"#3b82f6"}` | Color map |
| `titleTemplate` | string | auto | Marker title |
| `infoWindowTemplate` | string | auto | Popup HTML |

## Color Codes

- 🟢 Green `#10b981` - Success/In/Active
- 🔴 Red `#ef4444` - Error/Out/Inactive
- 🔵 Blue `#3b82f6` - Info/Default
- 🟡 Yellow `#fbbf24` - Warning/Pending
- ⚫ Gray `#6b7280` - Neutral/Unknown

## Troubleshooting

**No map showing:**
- Check Google Maps API loaded
- Verify `mapLibraries` in module config

**No markers:**
- Check records have valid lat/lng
- Verify `filterField`/`filterValue`
- Check `isdeleted` is false

**Path not drawing:**
- Need 2+ markers
- Set `showPath: true`
- Check `timestampField` exists

**Templates not working:**
- Use `{{field_name}}` format
- Check field names match database
- Watch for typos

## Files

- Component: `FrontEnd/js/components/GpsMapViewer.js`
- Integration: `FrontEnd/js/core/ModalBuilder.js`
- Docs: `docs/frontend/GpsMapViewer.md`