ol-layerswitcher
v4.1.2
Published
Layer switcher control for OpenLayers
Downloads
28,390
Readme
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 atype: 'base'
property. See the comments in examples/layerswitcher.js for other layer/ group options includingcombine
andfold
.
- Create a layer switcher control. Each layer to be displayed in the layer switcher has a
- 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).
- Makes the panel scroll vertically, the height of the layer switcher is controlled by setting the
- 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.
- Demonstrates rendering the layer tree into a Turbo87/sidebar-v2 pane. This uses the static method
- Collapse groups
- Shows the effect of setting the
fold
property of a Group to allow the group to be collapsed.
- Shows the effect of setting the
- 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 thegroupSelectStyle
to easily see the effect of the different values.
- Demonstrates setting the
- 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 - usecollapseLabel
to set its text (default iscollapseLabel: '»'
, 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:
- Shows setting
.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;
}
- 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.
- Example with the layer switcher starting open using
- 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
Browser
JS
Load ol-layerswitcher.js
after OpenLayers. The layerswitcher control is available as LayerSwitcher
or ol.control.LayerSwitcher
.
<script src="https://unpkg.com/[email protected]"></script>
CSS
<link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/ol-layerswitcher.css" />
Parcel, Rollup, Webpack, TypeScript etc.
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 [email protected]
.
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:
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
- LayerSwitcher#show
- LayerSwitcher#hide
- Options
- RenderOptions
- GroupSelectStyle
- BaseLayerOptions
- GroupLayerOptions
LayerSwitcher
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:
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:
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.
var layerSwitcher = new LayerSwitcher({
reverse: true,
groupSelectStyle: 'group'
});
map.addControl(layerSwitcher);
Parameters
opt_options
Options? LayerSwitcher options, see LayerSwitcher Options and RenderOptions which LayerSwitcherOptions
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 forpanel
HTMLElement The DOM Element into which the layer tree will be renderedoptions
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
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 underlyr
.
Returns void
uuid
[static] - Generate a UUID Adapted from http://stackoverflow.com/a/2117523/526860
Returns String UUID
LayerSwitcher#show
Event triggered after the panel has been shown.
Listen to the event via the on
or once
methods; for example:
var layerSwitcher = new LayerSwitcher();
map.addControl(layerSwitcher);
layerSwitcher.on('show', (evt) => {
console.log('show', evt);
});
LayerSwitcher#hide
Event triggered after the panel has been hidden.
Options
Extends ControlOptions, RenderOptions
[interface] - LayerSwitcher Options specified when creating a LayerSwitcher instance, extends RenderOptions and Control Options.
Default values:
{
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
RenderOptions
[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
GroupSelectStyle
[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"
)
BaseLayerOptions
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"
GroupLayerOptions
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
Beta release
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