Architectural Overview: Bidirectional Leaflet.js Integration (Wix Velo)

​

This implementation utilizes a decoupled architecture to integrate a Leaflet.js mapping engine within a Wix Velo environment. The system relies on an asynchronous, event-driven communication bridge (via the postMessage API) to synchronize the Wix UI state (Repeaters and Filters) with a custom HTML5 iFrame.

​

1. The View Layer (HTML/Leaflet iFrame)

The iFrame acts as a specialized renderer for GeoJSON data. It is state-neutral until it receives an array of features from the parent window.

• Rendering Engine: Uses Leaflet 1.9.4 with CARTO Voyager tiles.

• Styling Logic: Implements a conditional style-override function (getFeatureColor). It prioritizes business logic (hardcoded Tier 3/4 colors) over raw database values to ensure visual consistency.

• Feature Handling: * Supports polymorphic geometries (Point, LineString, Polygon).

  • Point geometries are rendered as L.circleMarker for performance.

  • Non-Point geometries use flyToBounds for spatial fitting.

• Dynamic Legend: On every data update, the script iterates through the current feature set to rebuild the legend UI, ensuring the map key always reflects filtered data.​

​

2. The Controller Layer (Wix Velo Page Code)

The Wix side manages data orchestration, state filtering, and data normalization.

• Data Aggregation: Queries the ProjectTracker collection. It performs dual-action filtering: updating the local dataset1 (for the Repeater UI) and a raw wixData.query (for the Map).

• Normalization Pipeline (sendDataToMap): The database stores GeoJSON as a stringified object.

  • The controller parses this string, extracts the geometry, and attaches relevant metadata (ID, title, priority, cost) to the properties object of a standard GeoJSON Feature.

• Input Debouncing: Implements a 500ms debounce on the search input to mitigate redundant API calls and UI jitter during rapid text entry.

​

3. State Management & Interaction

1. Selection Feedback: The highlightRepeaterItem function provides visual confirmation by cycling the background color of the active Repeater item while resetting non-active siblings.

2. Navigation Flow: Note that navigation is proxied through the parent window. Since the iFrame is sandboxed, it cannot trigger top-level window redirects directly; it must request the parent to execute wix-location commands.

​

Technical Constraints & Error Handling

• Validation: The GeoJSON parser includes try/catch blocks to prevent malformed database entries from breaking the Leaflet render cycle.

• Scale: The queries are currently capped at a limit(1000) per the applyFilters logic. If the collection grows beyond this, we will need to implement server-side clustering or bounding-box-based queries.