Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
elliot-100 opened this issue Mar 11, 2025 · 1 comment

Comments

@elliot-100
Copy link

elliot-100 commented Mar 11, 2025

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.
@elliot-100 elliot-100 changed the title User guide LayerControl should say that 'overlay' parameter defaults vary by kind of layer User guide: LayerControl secrtion should explain that 'overlay' parameter defaults vary by kind of layer Mar 11, 2025
@elliot-100 elliot-100 changed the title User guide: LayerControl secrtion should explain that 'overlay' parameter defaults vary by kind of layer User guide: LayerControl section should explain that 'overlay' parameter defaults vary by kind of layer Mar 11, 2025
elliot-100 added a commit to elliot-100/folium that referenced this issue Mar 11, 2025
Explain which layer kinds are base layer / overlay by default.
@elliot-100
Copy link
Author

Raised PR #2108.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant