Placeholder areas

[kkaefer]

I'm proposing to introduce placeholder areas: Annotations are currently located in a layer that is above all other layers, meaning that annotations will always cover existing features, such as labels. Similarly, when adding new layers, you'll have to explicitly name an existing layer as the beforeLayerID parameter to have the layer inserted below that layer.

Placeholder areas would be named regions within a style that can be referenced when inserting new layers, or adding annotations (i.e. every placeholder area would have its own annotation layer). An example JSON excerpt would look like this:

"layers": [
  // background layer
  // water layer
  {
    "area": "landmass"
  },
  // ... other layers ...
  {
    "area": "overlay"
  },
  // ... label layers ...
]

We'd have to establish some convention for style authors to follow, but it'll help the common case of a user inserting some annotations that cover up the labels.

There might be some way we could reuse Studio metadata (which has layer groups) to accomplish this as well.

/cc @lucaswoj @kronick @jfirebaugh @1ec5 @tmcw

[1ec5]

Annotations are specific to the native SDKs are aren't mentioned in this specification. Could the native SDKs (or mbgl) address the problem of inserting layers above annotations (but not the broader idea of placeholder areas) by keeping track of the bottommost annotation layer and always inserting before it?

[1ec5]

Note that the automatically added point annotation layer is already used as a placeholder of sorts for view-backed annotations that are (due to platform limitations) always rendered atop the entire map, regardless of any layers that may sit above the point annotation layer in the style.

[andrewharvey]

This could be useful in the GL JS context as well to put client side layers (such as annotations; basically extra layers in the application code not from the Studio Style) below the labels from the Style. With the default Mapbox styles, this usually means for Streets a beforeLayer of housenum-label and for Satellite Streets a beforeLayer of waterway-label (event though ferry-label is lower).

What about a "placeholder" layer type. So you could for example add an annotation placeholder layer to your Style then do beforeLayer annotation?

[1ec5]

Since a style JSON file is expected to be platform-agnostic, it shouldn’t assume support for a platform-specific feature – annotations in this case, but the canvas layer type added in mapbox/mapbox-gl-style-spec#656 is problematic for the same reason.

A no-op “divider” layer could be useful for a developer to cede control over the exact z-ordering of a runtime-inserted layer to their style designer. At runtime, the developer would insert above or below the divider (doesn’t matter which) without replacing the divider. However, I don’t think the SDK could rely on the designer to add a dedicated placeholder or divider layer for something like annotations that has to work in every style (even a barren style with no layers or sources).

[jfirebaugh]

Previously: https://github.com/mapbox/mapbox-gl-styles/issues/34, https://github.com/mapbox/mapbox-gl-styles/issues/258.

[lucaswoj]

This issue was moved to mapbox/mapbox-gl-js#4173