/ol-layerswitcher

Layer control for OpenLayers

Primary LanguageJavaScript

OpenLayers LayerSwitcher

Grouped layer list control for an OpenLayer map.

To be shown in the layer switcher layers should have a title property; base layers should have a type property set to base. Group layers (ol.layer.Group) can be used to visually group layers together; a group with a fold property set to either open or close will be displayed with a toggle. See Examples for usage.

Compatible with OpenLayers version 3, 4, 5 and 6 (see note in Install - Parcel, Webpack etc. regarding installing the appropriate version of ol-layerswitcher for OpenLayers).

Examples

The examples demonstrate usage and can be viewed online thanks to raw.githack.com:

  • Basic usage
    • Create a layer switcher control. Each layer to be displayed in the layer switcher has a title property as does each Group; each base map layer has a type: 'base' property. See the comments in examples/layerswitcher.js for other layer/ group options including combine and fold.
  • Add layer
    • Add a layer to an existing layer group after the layer switcher has been added to the map.
  • Scrolling
    • Demonstrate the panel scrolling vertically, control the height of the layer switcher by setting the max-height (see examples/scroll.css) and it's position relative to the bottom of the map (see the .layer-switcher.shown selector in src/ol-layerswitcher.css).
  • Side bar
  • Collapse groups
    • Demonstrates setting the fold property of a Group to allow the group to be collapsed.
  • Selectable Groups
    • Demonstrates setting the groupSelectStyle option which determines if groups have a checkbox and how toggling a groups visibility affects it's children. The demo includes the ability to change the groupSelectStyle to easily see the affect of the different values.
  • Bundling with ol package (Browserify, Parcel, Webpack...)

The source for all examples can be found in examples.

Install

Browser

JS

Load ol-layerswitcher.js after OpenLayers. The layerswitcher control is available as LayerSwitcher or ol.control.LayerSwitcher.

<script src="https://unpkg.com/ol-layerswitcher@3.5.0"></script>

CSS

<link rel="stylesheet" href="https://unpkg.com/ol-layerswitcher@3.5.0/src/ol-layerswitcher.css" />

Parcel, Webpack etc.

NPM package: ol-layerswitcher.

JS

Install the package via npm

npm install ol-layerswitcher --save

⚠️ If you're using the ol package prior to v5 you'll need to install ol-layerswitcher@v2.0.0.

CSS

The CSS file ol-layerswitcher.css can be found in ./node_modules/ol-layerswitcher/src

To use the layerswitcher with the ol package and a module bundler such as Parcel, Webpack etc. see ol-layerswitcher-examples.

Tests

To run the tests you'll need to install the dependencies via npm. In the root of the repository run:

npm install

Then run the tests by opening test/index.html in a browser.

API

Table of Contents

LayerSwitcher

Extends ol/control/Control~Control

OpenLayers Layer Switcher Control. See the examples for usage.

Parameters

  • opt_options Object Control options, extends ol/control/Control~Control#options adding:
    • opt_options.activationMode String Event to use on the button to collapse or expand the panel. 'mouseover' (default) the layerswitcher panel stays expanded while button or panel are hovered. 'click' a click on the button toggles the layerswitcher visibility.
    • opt_options.collapseLabel String Text label to use for the expanded layerswitcher button. E.g.: '»' (default) or '\u00BB', '-' or '\u2212'. Not visible if activation mode is 'mouseover'
    • opt_options.label String Text label to use for the collapsed layerswitcher button. E.g.: '' (default), '«' or '\u00AB', '+'.
    • opt_options.tipLabel String the button tooltip.
    • opt_options.groupSelectStyle String either 'none' - groups don't get a checkbox, 'children' (default) groups have a checkbox and affect child visibility or 'group' groups have a checkbox but do not alter child visibility (like QGIS).
    • opt_options.reverse boolean Reverse the layer order. Defaults to true.

setMap

Set the map instance the control is associated with.

Parameters

  • map ol/Map~Map The map instance.

showPanel

Show the layer panel.

hidePanel

Hide the layer panel.

renderPanel

Re-draw the layer panel to represent the current state of the layers.

renderPanel

Static Re-draw the layer panel to represent the current state of the layers.

Parameters

  • map ol/Map~Map The OpenLayers Map instance to render layers for
  • panel Element The DOM Element into which the layer tree will be rendered
  • options

forEachRecursive

Static Call the supplied function for each layer in the passed layer group recursing nested groups.

Parameters

  • lyr ol/layer/Group~LayerGroup The layer group to start iterating from.
  • fn Function Callback which will be called for each ol/layer/Base~BaseLayer found under lyr. The signature for fn is the same as ol/Collection~Collection#forEach

uuid

Static Generate a UUID Adapted from http://stackoverflow.com/a/2117523/526860

Returns String UUID

License

MIT (c) Matt Walker.

Also see

If you find the layer switcher useful you might also like the ol-popup.

Publishing

npm run build
# Open ./tests/ in browser
# Open examples and manually test
# Update version number in `package.json`, `bower.json` and `README.md`
# Determine new version number (check current with `git tag --list`, check npm and GitHub)
git tag vX.Y.Z
git push origin master --tags
npm publish