Manage a map with Locations and Routes
This document provides a comprehensive overview of the Map feature within the application, explaining its functionality from the perspective of both Standard Users (Publishers) and Coordinators (Admins).
Overview
The Map feature allows congregations to visually manage and display geographical points of interest (Locations) and areas/paths (Routes). It can be used to coordinate public witnessing locations, define specific territories, or highlight important areas for the publishers.
The map utilizes OpenStreetMap tiles and Leaflet for rendering. It also supports showing user locations, displaying congregation borders, and uploading images for specific locations.
User Roles
- Standard Users (Publishers): Can view the map, locations, routes, and associated details (like images and hints) if the map is made visible to them by a Coordinator.
- Coordinators (Admins): Have full management access. They can configure map settings, create/edit/delete locations and routes, manage location images, and draw polygons for routes.
Standard User (Publisher) View
If the Coordinator has enabled the "Map visible for all publishers" setting, Standard Users can access the map via the navigation menu (under Other -> Map).
Viewing the Map
- Auto-centering: The map automatically adjusts its bounds to fit all available locations and routes. If none are present, it defaults to the center point configured by the Coordinator.
- Markers & Shapes:
- Locations are displayed as map markers with custom colors and icons.
- Routes are displayed as colored polygons or lines on the map.
- Congregation Borders are displayed as non-interactive orange outlines (if enabled by the Coordinator).
- Map Style: The map may be displayed in standard colors or in grayscale (monochrome) based on the calendar's settings.
Interacting with Map Elements
Clicking on a marker (Location) or a polygon (Route) opens a details dialog:
- Location Details:
- Displays the name and description.
- Shows Important hints (highlighted in red for visibility).
- Displays a gallery of associated images. Clicking on a thumbnail opens a full-screen Lightbox for zooming and navigating through the images.
- Route Details:
- Displays the name and description.
- Lists any locations that are associated with that specific route.
"Locate Me" Feature
Users can click the "Show my location" button (target icon in the top right corner of the map) to prompt their browser to find and display their current geographical position on the map. This is useful for finding the nearest witnessing locations.
Coordinator (Admin) View
Coordinators manage the Map feature from the Admin area under Manage Map (`/admin/map`). From here, they can configure global settings, manage Locations, and manage Routes.
1. Map Settings
Accessed via the settings (gear) icon on the Manage Map dashboard.
Center Latitude & Longitude
- Center latitude
- Center longitude
- Pick center on map
What it does: Sets the default geographical center point of the map. This determines the initial view when the map is loaded.
Where it appears / Effect: On the main map view when any user opens the map section, the map will initially pan to these exact coordinates.
Map visible for all publishers
What it does: Toggles whether the map feature is restricted to administrators and coordinators, or if it is accessible to standard users (publishers) as well.
Where it appears / Effect: Controls the appearance of the Map menu link in the main navigation. If enabled, all publishers see the "Map" item in their menu and can view the configured locations and routes.
Use monochrome tiles
What it does: Changes the base map styling from full color to grayscale (monochrome).
Where it appears / Effect: Applies directly to the map backgrounds viewed by all users. The map background becomes black and white, which can help custom colored routes and location markers stand out more prominently.
Show congregation borders
What it does: Enables the drawing of predefined congregation boundary lines on the map.
Where it appears / Effect: An overlay of borders will be superimposed onto the main map view for all users, outlining specific areas.
2. Managing Locations
Locations represent specific points on the map (e.g., a cart location, a meeting point).
Creating / Editing a Location:
Name
What it does: The primary identifier or title for the location.
Where it appears / Effect: Shows up as the title when a user clicks on the location marker on the map, in the list of locations in the administration area, and in any association dropdowns.
Color / Icon
- Color:
- What it does: Determines the color tint of the map marker.
- Where it appears / Effect: The pin icon on the actual map view will be rendered in this selected color.
- Icon:
- What it does: Allows the selection of a specific symbol or glyph to be placed inside the map marker.
- Where it appears / Effect: The selected icon will be visible inside the colored pin on the map view, helping users quickly identify the type of location at a glance.
Coordinates
Latitude and Longitude. A "Coordinate Picker" tool is provided to select the exact point on a map.
Description
What it does: A rich text field for providing general information about the location.
Where it appears / Effect: Appears within the popup or details panel when a user clicks the location marker on the map.
Important hints
What it does: A secondary rich text field specifically for critical alerts, rules, or warnings related to the location.
Where it appears / Effect: Appears prominently in the location details panel when clicked on the map, often styled to catch the user's attention.
Associated routes
What it does: Links the location to one or more predefined routes.
Where it appears / Effect: Currently acts as a logical grouping. When routes or locations are queried, they are linked together in the database, which may influence how they are filtered or displayed together on the map.
Validity period
What it does: Defines a start and end date for when this location should be considered active.
Where it appears / Effect: If the current date falls outside of this range, the location will automatically be hidden from the public map view, even if the "Active" toggle is checked.
Active
What it does: A master switch to enable or disable the location entirely.
Where it appears / Effect: If unchecked, the location marker disappears from the map for all users immediately, regardless of its validity period.
Managing Location Images:
After saving a location, Coordinators can upload images to it.
- Images are automatically resized into small (600px width) and large (1600px width) versions for optimized loading in the frontend gallery and lightbox.
- Coordinators can provide a Title and Description for each image.
- Images can be toggled as Active or deleted entirely.
3. Managing Routes
Routes represent polygons, lines, or specific areas on the map (e.g., a specific public witnessing zone, a walking path).
Creating / Editing a Route:
Name
What it does: The primary identifier for the route.
Where it appears / Effect: Visible in the administration area list of routes, inside association dropdowns, and as a title if the route is clicked on the map.
Color
What it does: Sets the color of the route's lines and fill area.
Where it appears / Effect: The shape drawn on the map will be rendered in this color with varying opacity.
Description
What it does: General text detailing information about the route.
Where it appears / Effect: Visible when clicking on the route area on the map.
Route Drawer (Polygons)
An interactive map tool that allows the Coordinator to draw shapes (polygons) directly onto the map to define the route's geographical boundaries.
Associations
- Associated locations:
- What it does: Links the route to one or more predefined map locations.
- Where it appears / Effect: Allows locations to be logically grouped to this route. It may impact filter views or grouping on the main map.
- Associated Reservable Items:
- What it does: Links the geographical route to calendar items that users can reserve.
- Where it appears / Effect: This ties the map feature directly into the reservation calendar. When a user is interacting with a specific reservable item, this route can be referenced or shown.
- Associated Campaigns:
- What it does: Links the geographical route to specific reservation Campaigns (logical groupings of shifts).
- Where it appears / Effect: When managing or viewing campaigns within the calendar, this geographical context provides a visual representation of where the campaign takes place on the map.