Style OpenLayers vector layers using SLD data
npm install ol-sld-stylerbash
npm install --save ol-sld-styler
`
Note: Internet Explorer is not supported.
Basic usage
This package must be imported as a module - it is not designed to be loaded directly with a \ tag. The examples (above) best demonstrate usage with the API section (below) defining the exact function parameters and return values. However, the following pseudocode segment outlines the basic methodology:
`javascript
import 'ol/ol.css';
import 'ol-sld-styler/dist/ol-sld-styler.css';
import {createAllLayers, styleLayers, checkForMissingData,
insertLegend, showLayerSwitcherSymbols} from 'ol-sld-styler';
var dataLayerList; // Ordered list of OpenLayers data layers/groups
var selectableLayers; // Layers marked selectable in dataLayersConfig
// Parse data layer definitions and create placeholder layers
// - dataLayersConfig {object}: ol-sld-styler layer-specific configuration
[dataLayerList, selectableLayers] = createAllLayers(dataLayersConfig);
// (Load and extract all layer data and styles -
// e.g. use ol-load-geopackage module)
// (Create OpenLayers map using dataLayerList)
// Assign data sources to layers and do all OpenLayers layer styling
// Parameters:
// - view: target OpenLayers map view
// - sourceDescription {string}: sources lineage (for diagnostics only)
// - dataSources {object}: OpenLayers vector sources (key = table name)
// - sldLayerStyles {object}: data source-specific SLDs (key = table name)
// - sldStylesOverride {object}: shared SLDs (key = table name)
// - sldStylerOptions {object}: ol-sld-styler general configuration
styleLayers(view, sourceDescription, dataSources, sldLayerStyles,
sldStylesOverride, sldStylerOptions);
// Apply optional extra ol-sld-styler functions
showLayerSwitcherSymbols(...)
insertLegend(...)
checkForMissingData(...)
`
Webpack bundling
The (shared) support files used to bundle the examples using Webpack 5 (package.json, webpack.config.js) are in the examples folder. If you clone the repository then you can (re-)build the code bundles (for both examples) with the following commands. Note that the "sql-install" script is to fulfill the requirements from the ol-load-geopackage module which is incorporated in all the examples. It simply copies the sql.js web assembly file (sql-wasm.wasm) from folder _node_modules/sql.js/dist/_ to the folder where the web page is to be loaded from.
`bash
cd examples
npm install
npm run-script sql-install
npm run-script build
`
The Webpack dev-server can be used to automatically re-build, act as a webhost and trigger the browser to reload every time the code changes. One of the following script commands (defined in package.json) can be used to start the dev-server for each of the examples:
`bash
npm run-script start-basic
npm run-script start-sldfiles
npm run-script start-layersw
npm run-script start-legend
npm run-script start-full
`
API
The JavaScript module has 5 exported functions which are described in the separate API Specification:
- createAllLayers(): Parse data layer definitions and create placeholder OpenLayers layers/groups
- styleLayers(): Connect data sources to placeholder layers and style them with SLD data
- showLayerSwitcherSymbols(): Add symbology icons to an ol-layerswitcher Layer Switcher.
- insertLegend(): Generate map legend for all layers/groups defined in data layers definition.
- checkForMissingData(): Detect (and mark in Layer Switcher) any layers with missing data tables
Usage Recommendations
Use QGIS as a primary source for layer styling and OGC GeoPackage generation:
- You can view in QGIS the project file that can be used to re-generate the GeoPackages for all the ol-sld-styler Examples (file ol-sld-styler example.qgz). Note that this is a version of the original file that has had its data sources redirected to the GeoPackages that were output by the original.
- Before choosing your own QGIS layer styling, consider ol-sld-styler styling limitations.
- Within QGIS, use Processing Toolbox > Package Layers and select Save layer styles into package to generate an OGC GeoPackage which includes a table _layer_styles_ which contains the SLD information.
- Be aware that if you have layers that use the same source data tables, then Package Layers will repeatedly write out all the data for each of these layers.
- Hence for simplicity and minimum GeoPackage size, try to combine layers using the same source data table using QGIS "Categorized" symbology. ol-sld-styler will display all the separate symbols and labels in a legend and/or layer switcher for such multi-symbol layers. However, bear in mind that ol-layerswitcher/OpenLayers can only switch visibility on/off for a whole layer.
- Where multiple layers do end up using the same source data table, you can minimize the GeoPackage size by only including one of these layers in the GeoPackage but saving the SLD for the other layers as ".sld" files using QGIS Layer Properties > Symbology > Style > Save Style... > As SLD Style File. Such ".sld" files can then be passed to ol-sld-styler to generate additional layers from the same data source table (see SLD File Load example for just such an example).
When using ol-sld-styler:
- Even if you are not using QGIS to export the data and styles, consider using OGC GeoPackages as a source format: they are a very efficient way to store and retrieve spatial data and have been supported by all major GIS applications for many years.
- If you are using GeoPackages and do not require sophisticated handling operations, consider using ol-load-geopackage (as used in all the examples).
- To ease creation of the required dataLayersConfig array, you can generate a template of all the tables in your GeoPackage using the debugShowTableJson() function provided in the examples - the Fully-featured example version of this includes generation of the _popupAttr_ properties (extracting all attributes for each layer).
- If you want to modify the styles extracted from SLD, use styleLayers() option tweakFeatureTypeStyle() in preference to tweakOlStyle() to improve performance. To help in using the former, the _debugShowFeatureTypeStyle_ option of styleLayers() will export to the browser console the featureTypeStyle extracted from each layer.
- Consider using the WebPack bundler (other bundlers like Parcel should work but have not been tested).
- The examples all use a separate file ("\*\_mapconfig.js") which does not get included in the bundler but is loaded separately in the HTML file with its own \ tag. Although less optimized, this approach allows the styling to be quickly modified without any Webpack rebuilding (just a browser refresh). In the examples this file includes definitions for dataLayersConfig, styleLayers() options (listed as sldStylerOptions which includes the tweakFeatureTypeStyle() and tweakOlStyle() functions) and any other constants that are helpful to be able to tweak (like source file names and map extent).
Creating an offline map viewer:
- By using an OGC GeoPackage as a primary data/styling source, you can create an _offline_ map viewer for mobile phones or tablets which have poor (or non-existent) network connectivity. When a network connection is available, data and stying updates could then be done by downloading just 1 file.
- Offline usage will require hosting an ol-sld-styler web site on a simple web server running locally on the device (simply opening the files in a browser will not work).
- On Android, one minimal web server option is to install Tiny Web Server which seems to work well even though it is old and no longer maintained. However, note that this (and many others) lack correct mime-type support for SVG files. If you were intending to use SVG, then a workaround is to instead use raster files as demonstrated in the Fully-featured example. Various websites can be used for online SVG to PNG conversion (including transparency) including:
- https://cloudconvert.com/svg-to-png
- https://image.online-convert.com/convert/svg-to-png
Styling Limitations
_(Brief summary - see separate Styling Limitations page for full details, including some suggested workarounds.)_
If you are using QGIS to design your map layer styling, it is important to understand that there are some limitations on layer styling exported from QGIS to what can be automatically rendered in OpenLayers by ol-sld-styler. Limitations are due to several factors:
- QGIS SLD export (either through Package Layers or Save Style as SLD style file`) is not fully implemented. (QGIS sometimes puts "not implemented yet" comments in the SLD to indicate this).