OpenLayers LayerSwitcher

Grouped layer list control for an OpenLayer map.

To be shown in the LayerSwitcher layers should have a title property; base
layers should have a type property set to base. Group layers
(LayerGroup) 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 API documentation and 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
- Makes the panel scroll vertically, the height of the layer switcher is controlled by setting the max-height style (see examples/scroll.css) and it's position relative to the bottom of the map (see the .layer-switcher.shown selector in dist/ol-layerswitcher.css).
- Side bar
- Demonstrates rendering the layer tree into a Turbo87/sidebar-v2 pane. This uses the static method LayerSwitcher.renderPanel which can be used to render the layer tree to any arbitrary HTML element.
- Collapse groups
- Shows the effect of 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 effect of the different values.
- Bundling with ol package (Browserify, Parcel, Webpack...)
- Activate panel with click
- Shows setting activationMode: 'click' (default is 'mouseover'). When using this mode the control's button persists in the panel - use collapseLabel to set its text (default is collapseLabel: '»', see the comments in examples/layerswitcher.js for other examples). The close button is positioned to the left of the panel, to move it to the right add the following to your CSS:

``CSS
.layer-switcher.shown.layer-switcher-activation-mode-click {
padding-right: 34px;
}
.layer-switcher.shown.layer-switcher-activation-mode-click > button {
right: 0;
border-left: 0;
}
`

- Start with panel active
- Example with the layer switcher starting open using startActive: true. Here shown in combination with \activationMode: 'click' which, while not required, is probably the most common scenario.
- Multiple maps

- Demonstrates creating two independent maps each with a layer switcher control.

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

The source for all examples can be found in examples.

Changelog

See CHANGELOG for details of changes in each release.

Install

$3

#### JS

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

``HTML

`

#### CSS

`HTML

`

$3

NPM package: ol-layerswitcher.

#### JS

Install the package via npm

npm install ol-layerswitcher --save

:warning: 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/dist

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

#### TypeScript type definition

TypeScript types are shipped with the project in the dist directory and should be automatically used in a TypeScript project. Interfaces are provided for LayerSwitcher Options as well as extend interfaces for BaseLayer and LayerGroup Options that include the LayerSwitcher specific properties such as title, combine etc.

These interfaces can be imported into your project and used to cast object literals passed to layer or group constructors:

`typescript
import 'ol/ol.css';
import 'ol-layerswitcher/dist/ol-layerswitcher.css';

import Map from 'ol/Map';
import View from 'ol/View';
import LayerGroup from 'ol/layer/Group';
import LayerTile from 'ol/layer/Tile';
import SourceOSM from 'ol/source/OSM';
import SourceStamen from 'ol/source/Stamen';

import LayerSwitcher from 'ol-layerswitcher';
import { BaseLayerOptions, GroupLayerOptions } from 'ol-layerswitcher';

const osm = new LayerTile({
title: 'OSM',
type: 'base',
visible: true,
source: new SourceOSM()
} as BaseLayerOptions);

const watercolor = new LayerTile({
title: 'Water color',
type: 'base',
visible: false,
source: new SourceStamen({
layer: 'watercolor'
})
} as BaseLayerOptions);

const baseMaps = new LayerGroup({
title: 'Base maps',
layers: [osm, watercolor]
} as GroupLayerOptions);

const map = new Map({
target: 'map',
layers: [baseMaps]
});

const layerSwitcher = new LayerSwitcher({
reverse: true,
groupSelectStyle: 'group'
});
map.addControl(layerSwitcher);
`

See BaseLayerOptions and GroupLayerOptions.

API

#### Table of Contents

- LayerSwitcher
- Parameters
- setMap
- Parameters
- showPanel
- hidePanel
- renderPanel
- renderPanel
- Parameters
- isBaseGroup
- Parameters
- getGroupsAndLayers
- Parameters
- forEachRecursive
- Parameters
- uuid
- LayerSwitcher#show
- LayerSwitcher#hide
- Options
- activationMode
- startActive
- label
- collapseLabel
- tipLabel
- collapseTipLabel
- RenderOptions
- groupSelectStyle
- reverse
- GroupSelectStyle
- BaseLayerOptions
- title
- type
- GroupLayerOptions
- combine
- fold

$3

Extends ol/control/Control~Control

OpenLayers LayerSwitcher Control, displays a list of layers and groups
associated with a map which have a title property.

To be shown in the LayerSwitcher panel layers must have a title property;
base map layers should have a type property set to base. Group layers
(LayerGroup) 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 BaseLayerOptions for a full list of LayerSwitcher
properties for layers (TileLayer, ImageLayer, VectorTile etc.) and
GroupLayerOptions for group layer (LayerGroup)
LayerSwitcher properties.

Layer and group properties can either be set by adding extra properties
to their options when they are created or via their set method.

Specify a title for a Layer by adding a title property to it's options object:

`javascript
var lyr = new ol.layer.Tile({
// Specify a title property which will be displayed by the layer switcher
title: 'OpenStreetMap',
visible: true,
source: new ol.source.OSM()
});
`

Alternatively the properties can be set via the set method after a layer has been created:

`javascript
var lyr = new ol.layer.Tile({
visible: true,
source: new ol.source.OSM()
});
// Specify a title property which will be displayed by the layer switcher
lyr.set('title', 'OpenStreetMap');
`

To create a LayerSwitcher and add it to a map, create a new instance then pass it to the map's addControl method.

`javascript
var layerSwitcher = new LayerSwitcher({
reverse: true,
groupSelectStyle: 'group'
});
map.addControl(layerSwitcher);
`

#### Parameters

- opt_options Options? LayerSwitcher options, see LayerSwitcher Options and RenderOptions which LayerSwitcher Options extends for more details.

#### setMap

Set the map instance the control is associated with.

##### Parameters

- map Map The map instance.

Returns void

#### showPanel

Show the layer panel. Fires 'show' event.

Returns void

#### hidePanel

Hide the layer panel. Fires 'hide' event.

Returns void

#### renderPanel

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

Returns void

#### renderPanel

_[static]_ - Re-draw the layer panel to represent the current state of the layers.

##### Parameters

- map Map The OpenLayers Map instance to render layers for
- panel HTMLElement The DOM Element into which the layer tree will be rendered
- options RenderOptions Options for panel, group, and layers

Returns void

#### isBaseGroup

_[static]_ - Determine if a given layer group contains base layers

##### Parameters

- grp LayerGroup Group to test

Returns boolean

#### getGroupsAndLayers

_[static]_ - Get an Array of all layers and groups displayed by the LayerSwitcher (has a 'title' property)
contained by the specified map or layer group; optionally filtering via filterFn

##### Parameters

- grp (Map | LayerGroup) The map or layer group for which layers are found.
- filterFn function (lyr: BaseLayer, idx: number, arr: Array<BaseLayer>): boolean Optional function used to filter the returned layers

Returns Array<BaseLayer>

#### forEachRecursive

_[static]_ - Call the supplied function for each layer in the passed layer group
recursing nested groups.

##### Parameters

- lyr (Map | LayerGroup) The layer group to start iterating from.
- fn function (lyr: BaseLayer, idx: number, arr: Array<BaseLayer>): void Callback which will be called for each layer
found under lyr.

Returns void

#### uuid

_[static]_ - Generate a UUID
Adapted from

Returns String UUID

$3

Event triggered after the panel has been shown.
Listen to the event via the on or once methods; for example:

`js
var layerSwitcher = new LayerSwitcher();
map.addControl(layerSwitcher);

layerSwitcher.on('show', (evt) => {
console.log('show', evt);
});
`

$3

Event triggered after the panel has been hidden.

$3

Extends ControlOptions, RenderOptions

_[interface]_ - LayerSwitcher Options specified when creating a LayerSwitcher
instance, extends RenderOptions and
Control Options.

Default values:

`javascript
{
activationMode: 'mouseover',
startActive: false,
label: ''
collapseLabel: '\u00BB',
tipLabel: 'Legend',
collapseTipLabel: 'Collapse legend',
groupSelectStyle: 'children',
reverse: false
}
`

#### activationMode

Event to use on the button to collapse or expand the panel. Defaults to
"mouseover".

Type: ("mouseover" \| "click")

#### startActive

Whether panel is open when created. Defaults to false.

Type: boolean

#### label

Text label to use for the button that opens the panel. E.g.: '' (default), '«' or '\u00AB', '+'.

Type: string

#### collapseLabel

Text label to use for the button that closes the panel. E.g.: '»' (default) or '\u00BB', '-' or '\u2212'. Only used when activationMode: 'mouseover'.

Type: string

#### tipLabel

The button tooltip when the panel is closed.

Type: string

#### collapseTipLabel

The button tooltip when the panel is open.

Type: string

$3

_[interface]_ - LayerSwitcher Render Options as passed to LayerSwitcher
constructor as part of Options and static
LayerSwitcher.renderPanel

#### groupSelectStyle

How layers and groups behave when a given layer's visibility is set. See GroupSelectStyle type for possible values.

Type: GroupSelectStyle

#### reverse

Should the order of layers in the panel be reversed?

Type: boolean

$3

_[type]_ - How layers and groups behave when a given layer's visibility is set, 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).

Type: ("none" \| "children" \| "group")

$3

Extends ol/layer/Base~Options

_[interface]_ - Extended BaseLayer Options interface adding properties
used by the LayerSwitcher

#### title

Title of the layer displayed in the LayerSwitcher panel

Type: string

#### type

Type of the layer, a layer of type: 'base' is treated as a base map
layer by the LayerSwitcher and is displayed with a radio button

Type: "base"

$3

Extends ol/layer/Group~Options, BaseLayerOptions

_[interface]_ - Extended LayerGroup Options interface adding
properties used by the LayerSwitcher.

#### combine

When true child layers are not shown in the Layer Switcher panel

Type: boolean

#### fold

Fold state of the group, if set then the group will be displayed with a
button to allow the user to show/ hide the child layers.

Type: ("open" \| "close")

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.

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
# Determine new version number (check current with git tag --list, check npm and GitHub)
# Update version number in package.json and README.md
# Add entry to CHANGELOG.md
git commit package.json CHANGELOG.md README.md
git tag vX.Y.Z
git push origin master --tags
npm publish

$3

npm run build
# Tests/ examples
# Beta version should be X.Y.Z-beta.N
# Update version number in package.json and README.md`
# Add entry to CHANGELOG.md
git commit package.json CHANGELOG.md README.md
git tag vX.Y.Z-beta.N
git push --tags
npm publish --tag beta
# To list all version on npm
npm show ol-layerswitcher versions --json