Skip to content

User guide: LayerControl section should explain that 'overlay' parameter defaults vary by kind of layer #2107

@elliot-100

Description

@elliot-100

LayerControl: Common layer arguments says:

  • overlay: True if the layer is an overlay, False if the layer is a base layer.
    • base layer: only one of them can be active at a time. Mostly used for tile layers.
    • overlay: multiple can be active at the same time. Used for anything else than tile layers.

But I feel that it's important to tell users that default behaviour actually varies depending on the kind of layer, and mention FeatureGroups as they are layers and used in the following examples - this confused me when looking at issue #2093.

From the API docs,

  • ABC Layer is a base layer by default, but descendants vary:
    • TileLayer, WmsTileLayer are base layer by default
    • FeatureGroup, GeoJSON, ImageOverlay, TopoJson, VideoLayer, Choropleth are overlay by default; looks like all plugins are too.

Also vector_layers members don't have an overlay parameter, which is confusing, but they don't inherit from Layer - I think this is a folium implementation detail, as in Leaflet the equivalents do inherit from a Layer.

For now I propose:

  • overlay: True if the layer is an overlay, False if the layer is a base layer.
    • base layer: only one can be active at a time. Tile layers are base layers by default.
    • overlay: multiple can be active at the same time. FeatureGroups and most non-tile layers are overlays by default.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions