dawarich/LAYER_CONTROL_UPGRADE.md

Layer Control Upgrade - Leaflet.Control.Layers.Tree

Summary

Successfully installed and integrated the Leaflet.Control.Layers.Tree plugin to replace the standard Leaflet layer control with a hierarchical tree-based control that better organizes map layers and styles.

Changes Made

1. Installation

• Plugin: Installed leaflet.control.layers.tree via importmap
• CSS: Added plugin CSS file at app/assets/stylesheets/leaflet.control.layers.tree.css

2. Maps Controller Updates

File: app/javascript/controllers/maps_controller.js

Import Changes:

• Added import for leaflet.control.layers.tree
• Removed import for createPlacesControl (now integrated into tree control)

Initialization Changes:

• Removed standalone Places control initialization
• Added this.userTags property to store user tags for places filtering
• Updated layer control initialization to use createTreeLayerControl()

New Methods:

1. createTreeLayerControl(additionalLayers = {})

   • Creates a hierarchical tree structure for map layers
   • Organizes layers into two main groups:
     • Map Styles: All available base map layers
     • Layers: All overlay layers with nested groups
   • Supports dynamic additional layers (e.g., Family Members)

   Structure:

   + Map Styles
     - OpenStreetMap
     - OpenStreetMap.HOT
     - ...
   + Layers
     - Points
     - Routes
     - Tracks
     - Heatmap
     - Fog of War
     - Scratch map
     - Areas
     - Photos
     + Visits
       - Suggested
       - Confirmed
     + Places
       - All
       - Untagged
       - (each tag with icon)
   

Updated Methods:

• updateLayerControl(): Simplified to just recreate the tree control with additional layers
• Updated all layer control recreations throughout the file to use createTreeLayerControl()

3. Places Manager Updates

File: app/javascript/maps/places.js

New Methods:

1. createFilteredLayer(tagIds)

   • Creates a layer group for filtered places
   • Returns a layer that loads places when added to the map
   • Supports tag-based and untagged filtering

2. loadPlacesIntoLayer(layer, tagIds)

   • Loads places into a specific layer with tag filtering
   • Handles API calls with tag_ids or untagged parameters
   • Creates markers using existing createPlaceMarker() method

Features

Hierarchical Organization

• Map styles and layers are now clearly separated
• Related layers are grouped together (Visits, Places)
• Easy to expand/collapse sections

Places Layer Integration

• No longer needs a separate control
• All places filters are now in the tree control
• Each tag gets its own layer in the tree
• Places group has "All", "Untagged", and individual tag layers regardless of tags
• "Untagged" shows only places without tags

Dynamic Layer Support

• Family Members layer can be added dynamically
• Additional layers can be easily integrated
• Maintains compatibility with existing layer management

Improved User Experience

• Cleaner UI with collapsible sections
• Better organization of many layers
• Consistent interface for all layer types
• Select All checkbox for grouped layers (Visits, Places)

API Changes

Places API

The Places API now supports an untagged parameter:

• GET /api/v1/places?untagged=true - Returns only untagged places
• GET /api/v1/places?tag_ids=1,2,3 - Returns places with specified tags

Testing Recommendations

1. Basic Functionality

   • Verify all map styles load correctly
   • Test all overlay layers (Points, Routes, Tracks, etc.)
   • Confirm layer visibility persists correctly

2. Places Integration

   • Test "All" layer shows all places
   • Verify "Untagged" layer shows only untagged places
   • Test individual tag layers show correct places
   • Confirm places load when layer is enabled

3. Visits Integration

   • Test Suggested and Confirmed visits layers
   • Verify visits load correctly when enabled

4. Family Members

   • Test Family Members layer appears when family is available
   • Verify layer updates when family locations change

5. Layer State Persistence

   • Verify enabled layers are saved to user settings
   • Confirm layer state is restored on page load

Migration Notes

Removed Components

• Standalone Places control button (📍)
• createPlacesControl function no longer used in maps_controller

Behavioral Changes

• Places layer is no longer managed by a separate control
• All places filtering is now done through the layer control
• Places markers are created on-demand when layer is enabled

Future Enhancements

1. Layer Icons: Add custom icons for each layer type
2. Layer Counts: Show number of items in each layer
3. Custom Styling: Theme the tree control to match app theme
4. Layer Search: Add search functionality for finding layers
5. Layer Presets: Allow saving custom layer combinations

Files Modified

1. app/javascript/controllers/maps_controller.js - Main map controller
2. app/javascript/maps/places.js - Places manager with new filtering methods
3. config/importmap.rb - Added tree control import (via bin/importmap)
4. app/assets/stylesheets/leaflet.control.layers.tree.css - Plugin CSS

Rollback Plan

If needed, to rollback:

1. Remove import "leaflet.control.layers.tree" from maps_controller.js
2. Restore import { createPlacesControl } from places_control
3. Revert createTreeLayerControl() to L.control.layers()
4. Restore Places control initialization
5. Remove leaflet.control.layers.tree from importmap
6. Remove CSS file