Perspective Map: UI Views Use Layers, Not Z-Index

The browser renders the Perspective Map, map tiles, geographic UI layers, and ordinary view components through different paths. Follow the packet and then the render stack: tile delivery supplies the background, the map layer resolves latitude and longitude, and the embedded view supplies live process information. An ordinary component placed over the map stops at the stacking stage because the Map renders above it. A coordinate-bound view must enter through Map.layers.ui.view.

Where does the overlay path stop?

Layer one first. Confirm that the client can load and navigate the map before diagnosing an overlay. If the background does not load, moves incorrectly, or cannot reach the required area, troubleshoot tile delivery and map initialization separately. An embedded view does not repair a missing tile path.

Once the map itself works, inspect the rendering path. Perspective assigns the Map a stacking level above ordinary components. Adding another component later, changing its component order, or attempting to raise its z-index does not create a reliable overlay because the Map remains on top. Popups use a higher rendering level, but they solve a different interaction pattern.

Check: pan the working map and confirm that the failed component remains a stacking problem rather than a missing-map problem.

Should the view follow a coordinate or stay on screen?

Choose the coordinate system before configuring the overlay. A pump-station display belongs to a latitude/longitude point and must move as the user pans or zooms. A re-center button belongs to the screen and must remain visible regardless of map coordinates.

Do not use a geographic layer for a control that must remain in a corner. Conversely, do not position a station view by screen coordinates; it will lose its relationship to the station after navigation.

Check: write one sentence describing the required motion. If it says “follow this latitude and longitude,” proceed with the UI view layer.

How do you place an embedded view at latitude and longitude?

1. Create the embedded View that will display the station information. Build and test it outside the map first so its bindings, layout, and parameters can be checked independently.
2. Open the Map component configuration and add an entry under Map.layers.ui.view.
3. Select the embedded View for that entry.
4. Configure the entry at the required latitude and longitude using the location fields exposed by the Map UI view entry.
5. Set the view size and internal layout so the intended icon, values, and labels remain readable at the operating zoom levels.

The Map now owns both the geographic placement and the rendering order. That is the mechanism that ordinary component stacking lacks. The view is no longer merely positioned over the rectangular Map component; it is part of the Map layer model.

Check: pan away from the point and return. The view must remain attached to the same geographic location rather than the same screen pixel.

How does the map pass pressure and flow into the view?

Use the UI view entry's Map.layers.ui.view[x].params object to pass values into the selected View. Match each object key to an input parameter defined by that View. This separates geographic configuration from presentation: the map entry identifies where the station appears, while the embedded View decides how pressure, flow, status, and labels appear.

1. Define the required input parameters on the embedded View.
2. Open the corresponding entry under Map.layers.ui.view.
3. Add matching values to Map.layers.ui.view[x].params.
4. Bind each visual element inside the View to its input parameter.
5. Change one source value and observe the rendered value before adding more stations.

For multiple locations, create one UI view entry per displayed point and pass that point's values through its own params object. Reuse the same View when the stations share a presentation. A missing value then traces cleanly through source value, entry parameter, View input, and component binding.

Check: change pressure and flow independently. Each displayed field must update without changing the view's coordinate.

How do you add a fixed re-center control?

A re-center control follows a separate viewport path. If the built-in map UI does not provide the required behavior, disable its zoom controls with Map.zoom.controls = false and provide custom UI. Keep that control fixed relative to the screen, not a latitude/longitude point.

The following script sends the sibling Map back to the initial center recorded in props.init.center:

self.getSibling('Map').flyTo(latLng={'lat':self.getSibling('Map').props.init.center.lat, 'lng':self.getSibling('Map').props.init.center.lng})

The sibling lookup depends on the component actually being named Map and sharing the expected container relationship with the control. If either condition changes, update the lookup path. This call restores the initial center; it does not specify a zoom level, so test zoom restoration separately if that behavior is required.

Check: pan away, activate the control, and confirm that the center returns to props.init.center.lat and props.init.center.lng.

How do you verify the complete display path?

1. Load the map and confirm that its background and navigation work before any embedded-view test.
2. Navigate to the configured latitude and longitude and confirm that the embedded View appears above the map.
3. Pan and zoom through the operating range. Confirm that the View follows its coordinate while fixed controls remain stationary in the viewport.
4. Change every value supplied through Map.layers.ui.view[x].params. Confirm that only the intended station display changes.
5. Navigate away and run the re-center script. Confirm that the Map returns to its initial center.

Do not mix tile-cache or offline-map work into this test. Tile availability controls the background path; Map.layers.ui.view controls the coordinate-bound information path. Test each path independently before combining them.

FAQ