Remove languages from fenced code blocks.

stevage · stevage · commit cd2b5b45ed09 · 2021-11-10T11:33:58.000+11:00
See documentationjs/documentation#1428
diff --git a/README.md b/README.md
@@ -17,19 +17,19 @@ Full documentation: https://stevage.github.io/map-gl-utils
 
 To use without any build process:
 
-```html
+```
 <script src="https://unpkg.com/map-gl-utils"></script>
 ```
 
 then
 
-```js
+```
 U.init(map)
 ```
 
 With Webpack etc:
 
-```js
+```
 const mapgl = require('maplibre-gl'); // or require('mapbox-gl');
 const map = new mapgl.Map({ ... });
 
@@ -43,14 +43,14 @@ require('map-gl-utils').init(map, mapgl);
 
 The default distribution is an ES2015 module with no transpiling. If you experience any syntax issues (such as using older JavaScript versions), use the UMD bundle instead:
 
-```js
+```
 // Adds U property to map, containing these methods.
 require('map-gl-utils/umd').init(map);
 ```
 
 If you want to use Flow types:
 
-```js
+```
 import type MapGlUtils from 'map-gl-utils/src/index'
 ```
 
@@ -61,7 +61,7 @@ import type MapGlUtils from 'map-gl-utils/src/index'
 
 The `props` object passed when adding a layer can freely mix paint, layout and other properties. Property keys can be specified in camelCase or kebab-case:
 
-```js
+```
 map.U.addCircleLayer('trees-circle', 'trees', {
     circleColor: 'green', // paint property
     circleRadius: ['interpolate', ['zoom'], 12, 3, 15, 5], // paint property
@@ -80,15 +80,15 @@ Almost every method that works with existing layers (eg, `show()`) can work with
 
 Methods that add sources return an object ("SourceBoundUtils" in this documentation) that can be chained to allow layers to be added to it:
 
-```js
+```
 map.U.addGeoJSONSource('properties')
 .addCircleLayer('properties-line', { lineWidth: 3 })
 .addSymbolLayer('properties-fill', { fillColor: 'hsla(30,30%,60%,0.5)' })
 ```
 
 ### Adding and removing layers
 
-```js
+```
 // Conveniently add a line feature, mixing paint, layout and other properties.
 // Notice you can use camelCase for all property names.
 map.U.addLineLayer('mylines', 'mysource', {
@@ -112,7 +112,7 @@ map.U.removeLayer(['towns','town-labels']);
 ```
 ### Adding and removing sources
 
-```js
+```
 // Simpler way to create GeoJSON source:
 map.U.addGeoJSON('mysource', geojson);
 
@@ -152,7 +152,7 @@ map.U.setLayerSource('buildings', 'mylocalbuildings', null);
 
 ### Setting properties and updating data
 
-```js
+```
 // Every property has a setXxx() form:
 map.U.setTextSize('mylayer', 12);
 
@@ -192,7 +192,7 @@ map.U.addRasterLayer('myrasterlayer', 'myrastersource', { rasterSaturation: 0.5
 
 ### Hovering and clicking
 
-```js
+```
 // Use the mouse 'finger' cursor when hovering over this layer.
 map.U.hoverPointer('mylayer');
 
@@ -249,7 +249,7 @@ remove(); // no more hover popup
 
 ### Other functions
 
-```js
+```
 // Like on('load') but fires immediately (and reliably) any time after map already loaded.
 map.U.onLoad(callback);
 // returns a promise if no callback:
@@ -303,7 +303,7 @@ map.U.addSymbolLayer('labels', 'mysource', { textFont: fonts[0], textField: '{la
 ```
 
 ### Contrived example
-```js
+```
 map.U.onload(() => {
     map.U.addGeoJSON('towns');
     map.U.addCircleLayer('small-towns', 'towns', { circleColor: 'green', filter: ['==', 'size', 'small']});
diff --git a/docs/index.html b/docs/index.html
@@ -2,7 +2,7 @@
 <html lang="en">
 <head>
   <meta charset='utf-8'>
-  <title>map-gl-utils 0.42.0 | Documentation</title>
+  <title>map-gl-utils 0.42.1 | Documentation</title>
   <meta name='description' content='Utility functions for Mapbox GL JS or Maplibre GL JS'>
   <meta name='viewport' content='width=device-width,initial-scale=1'>
   <link href='assets/bass.css' rel='stylesheet'>
@@ -15,7 +15,7 @@
       <div id='split-left' class='overflow-auto fs0 height-viewport-100'>
         <div class='py1 px2'>
           <h3 class='mb0 no-anchor'>map-gl-utils</h3>
-          <div class='mb1'><code>0.42.0</code></div>
+          <div class='mb1'><code>0.42.1</code></div>
           <input
             placeholder='Filter'
             id='filter-input'
@@ -3129,13 +3129,39 @@ <h2>Major features:</h2>
 </ul>
 <h2>Usage</h2>
 <p>To use without any build process:</p>
+<pre><code>&#x3C;script src="https://unpkg.com/map-gl-utils">&#x3C;/script>
+</code></pre>
 <p>then</p>
+<pre><code>U.init(map)
+</code></pre>
 <p>With Webpack etc:</p>
+<pre><code>const mapgl = require('maplibre-gl'); // or require('mapbox-gl');
+const map = new mapgl.Map({ ... });
+
+// or:
+import U from 'map-gl-utils';
+U.init(map);
+
+// A small number of methods (eg hoverPopup) require access to the maplibre-gl/mapbox-gl library itself, in order to instantiate other objects.
+require('map-gl-utils').init(map, mapgl);
+</code></pre>
 <p>The default distribution is an ES2015 module with no transpiling. If you experience any syntax issues (such as using older JavaScript versions), use the UMD bundle instead:</p>
+<pre><code>// Adds U property to map, containing these methods.
+require('map-gl-utils/umd').init(map);
+</code></pre>
 <p>If you want to use Flow types:</p>
+<pre><code>import type MapGlUtils from 'map-gl-utils/src/index'
+</code></pre>
 <h3>Guide</h3>
 <h2>Working with layers</h2>
 <p>The <code>props</code> object passed when adding a layer can freely mix paint, layout and other properties. Property keys can be specified in camelCase or kebab-case:</p>
+<pre><code>map.U.addCircleLayer('trees-circle', 'trees', {
+    circleColor: 'green', // paint property
+    circleRadius: ['interpolate', ['zoom'], 12, 3, 15, 5], // paint property
+    circleSortKey: ['get', 'tree-sort-key'], // layout property
+    filter: ['!=', 'type', 'stump'], // other property
+});
+</code></pre>
 <p>Almost every method that works with existing layers (eg, <code>show()</code>) can work with multiple layers. There are four ways to specify the layer(s) you want to modify:</p>
 <ul>
 <li>string: <code>map.U.show('trees-label'); map.U.show('trees-circle');</code></li>
@@ -3145,12 +3171,228 @@ <h2>Working with layers</h2>
 </ul>
 <h2>Adding sources</h2>
 <p>Methods that add sources return an object ("SourceBoundUtils" in this documentation) that can be chained to allow layers to be added to it:</p>
+<pre><code>map.U.addGeoJSONSource('properties')
+.addCircleLayer('properties-line', { lineWidth: 3 })
+.addSymbolLayer('properties-fill', { fillColor: 'hsla(30,30%,60%,0.5)' })
+</code></pre>
 <h3>Adding and removing layers</h3>
+<pre><code>// Conveniently add a line feature, mixing paint, layout and other properties.
+// Notice you can use camelCase for all property names.
+map.U.addLineLayer('mylines', 'mysource', {
+    lineWidth: 3,
+    lineCap: 'round',
+    minzoom: 11
+});
+
+// Also addFillLayer, addFillExtrusionLayer, addRasterLayer, addVideoLayer, addSymbolLayer, addHillshadeLayer, addHeatmapLayer
+map.U.addCircleLayer('mycircles', 'mysource', { circleStrokeColor: 'red' });
+// if the layer already exists, calling add*Layer simply updates any of the properties
+map.U.addCircleLayer('mycircles', 'mysource', { circleStrokeColor: 'red', circleRadius: 4, filter: ['==', 'type', 'active'});
+
+
+// and of course add the layer "before" another layer if needed:
+map.U.addLineLayer('mylayer', 'mysource', { lineColor: 'red' }, 'toplayer');
+
+// removeLayer() doesn't throw errors if the layers don't exist
+map.U.removeLayer(['towns','town-labels']);
+
+</code></pre>
 <h3>Adding and removing sources</h3>
+<pre><code>// Simpler way to create GeoJSON source:
+map.U.addGeoJSON('mysource', geojson);
+
+// Or create a GeoJSON source with initially blank data. This is very convenient if you're loading
+// the data separately and will call .setData() later.
+map.U.addGeoJSON('mysource');
+
+// Simpler ways to create a vector tile source:
+map.U.addVector('mysource', 'mapbox://foo.blah');
+map.U.addVector('mysource', 'https://example.com/tiles/{z}/{x}/{y}.pbf');
+
+// Additional properties still work
+map.U.addVector('mysource', 'https://example.com/tiles/{z}/{x}/{y}.pbf', { maxzoom: 13 });
+
+// There's also addRaster(), addRasterDem(), addImage(), addVideo()
+// Calling any of the add* functions simply updates the source definition if it exists already.
+
+// Automatically removes any layers using these sources. Not an error if sources don't exist.
+map.U.removeSource(['buildings', 'roads']);
+
+// You can also use the returned object to add layers conveniently:
+map.U.addGeoJSON('buildings', 'data/buildings.geojson')
+    .addFillExtrusion('buildings-3d', {
+        fillExtrusionHeight: 100,
+        fillExtrusionColor: 'grey'
+    }).addLineLayer('buildings-footprint', {
+        lineColor: 'lightblue'
+    });
+
+// Replace the source on an existing layer. (Actually removes and re-adds it.)
+map.U.setLayerSource('buildings', 'newsource');
+map.U.setLayerSource(['buildings-3d', 'buildings-outline]', 'newsource', 'newsourcelayer');
+
+// To change the source layer, pass a third argument, or null to clear it (if switching from vector tiles to geojson)
+map.U.setLayerSource('buildings', 'mylocalbuildings', null);
+</code></pre>
 <h3>Setting properties and updating data</h3>
+<pre><code>// Every property has a setXxx() form:
+map.U.setTextSize('mylayer', 12);
+
+// And they all work on multiple layers at once:
+map.U.setLineWidth(['mylayer', 'mylayer-highlight'], 4);
+map.U.setLineOpacity(/^border-/, 0);
+map.U.setFillColor(layer => layer.source === 'farms', 'green');
+
+// There's also a more familiar setProperty() form.
+map.U.setProperty('mylayer', 'line-width', 3);
+// Existing properties aren't touched
+map.U.setProperty('mylayer', {
+    textSize: 12,
+    textColor: 'red'
+});
+
+// There's a `get...` version of every function, too.
+map.U.getFillColor('water')
+
+// Simpler way to update source data:
+map.U.setData('mysource', data);
+
+// you can leave out the data parameter to clear out a GeoJSON source:
+map.U.setData('mysource');
+
+// Easier to remember way to turn layers on and off:
+map.U.show('mylayer');
+map.U.hide('mylayer');
+map.U.toggle(['mylayer', 'myotherlayer'], isVisible);
+
+// To avoid name clashes such as with 'raster', you can use a longer form ending
+// with either ...Layer() or ...Source()
+
+map.U.addRasterSource('myrastersource', { type: 'raster', url: 'mapbox://mapbox.satellite', tileSize: 256 });
+map.U.addRasterLayer('myrasterlayer', 'myrastersource', { rasterSaturation: 0.5 });
+</code></pre>
 <h3>Hovering and clicking</h3>
+<pre><code>// Use the mouse 'finger' cursor when hovering over this layer.
+map.U.hoverPointer('mylayer');
+
+// If you pass several layers, it correctly handles moving from one layer to another
+// Use the mouse 'finger' cursor when hovering over this layer.
+map.U.hoverPointer(['regions-border', 'regions-fill']);
+
+// Sets a "hover" feature-state to be true or false as the mouse moves over features in this layer.
+// Requires that features have an `id`.
+map.U.hoverFeatureState('mylayer');
+
+// Want to apply the hover feature-state to a different source?
+// For instance, you hover over a label, but want to highlight the surrounding boundary.
+map.U.hoverFeatureState('town-labels', 'boundaries', 'town-boundaries');
+
+// You can also add additional event handlers:
+map.U.hoverFeatureState('mylayer', 'mysource', 'mysourcelayer',
+    e => console.log(`Entered ${e.features[0].id}`),
+    e => console.log(`Left ${e.oldFeatureid}`);
+
+// Shows a popup when a feature is hovered over or clicked.
+// The third argument is an options object, passed to the Popup constructor.
+// callback is called as: (feature, popup) => htmlString
+// Make sure you passed the mapboxgl library itself when initialising: U.init(map, mapboxgl).
+map.U.hoverPopup('mylayer', f => `&#x3C;h3>${f.properties.Name}&#x3C;/h3> ${f.properties.Description}`, { anchor: 'left' });
+map.U.clickPopup('mylayer', f => `&#x3C;h3>${f.properties.Name}&#x3C;/h3> ${f.properties.Description}`, { maxWidth: 500 });
+
+// clickLayer() is like .on('click)', but can take an array and adds a 'features' member
+// to the event, for what got clicked on.
+map.U.clickLayer(['towns', 'town-labels'], e => panel.selectedId = e.features[0].id);
+
+// clickOneLayer tests multiple layers in order, firing callback on the first one that
+// is hit. The callback is passed { feature, features, layer, event }.
+map.U.clickOneLayer(['town-labels', 'state-boundaries'], e => {
+    if (e.layer === 'town-labels') {
+        setView('town');
+        panel.selectedId = e.features[0].id;
+    } else if (e.layer === 'state-boundaries') {
+        setView('state');
+        panel.selectedId = e.features[0].id;
+    }
+});
+
+// Optionally pass in an extra callback which is fired for clicks that miss all layers:
+map.U.clickOneLayer(['town-labels', 'state-boundaries'], e => {...}, e => {
+    console.log('Missed everything');
+});
+
+// All these functions return an "undo" function that removes the handlers added:
+const remove = map.U.hoverPopup('mylayer', showPopupFunc);
+//...
+remove(); // no more hover popup
+</code></pre>
 <h3>Other functions</h3>
+<pre><code>// Like on('load') but fires immediately (and reliably) any time after map already loaded.
+map.U.onLoad(callback);
+// returns a promise if no callback:
+await map.U.onLoad();
+
+// Gets the layer definition. Mapbox's `getLayer()` has weird paint and layout properties.
+const layer = map.U.getLayerStyle('mylayer');
+
+// Resets all other properties to default first. Ignores non-paint, non-layout properties.
+map.setLayerStyle('mylayer', {
+    lineWidth: 3
+});
+
+// properties() converts an object to a layer object accepted by Mapbox-GL-JS
+map.addLayer(map.U.properties({
+    id: 'mylayer',
+    source: 'mysource',
+    type: 'line',
+    lineWidth: 3,
+    lineCap: 'round',
+    minzoom: 11,
+    filter: ['==', 'status', 'confirmed']
+}));
+
+// layerStyle() is flexible, pass as many or as few of id, source, and type (in that order) as you like:
+map.U.layerStyle('mylayer', 'mysource', 'line', { ... })
+map.U.layerStyle('mylayer', 'mysource', { ... })
+map.U.layerStyle('mylayer', { ... })
+map.U.layerStyle({ ... })
+
+
+// Hide/show/toggle all the layers attached to this source
+map.U.hideSource('buildings');
+map.U.showSource('buildings');
+map.U.toggleSource('buildings', true);
+
+// Update several filters at once.
+map.U.setFilter(['buildings-fill', 'buildings-outline', 'buildings-label'], [...]);
+
+// Conveniently load an image into the map in one step
+map.U.loadImage('marker', '/assets/marker-pin.png');
+map.U.loadImage('marker', '/assets/marker-pin@2x.png', { pixelRatio: 2}).then(/* ... */;
+
+
+// Update the map style's root "transition" property
+map.U.setTransition({ delay: 1000, delay: 0});
+
+// Get a list of fonts used in symbol layers with fontsUsed(). Useful for quickly getting some text displaying.
+const fonts = map.U.fontsInUse();
+map.U.addSymbolLayer('labels', 'mysource', { textFont: fonts[0], textField: '{label}' });
+</code></pre>
 <h3>Contrived example</h3>
+<pre><code>map.U.onload(() => {
+    map.U.addGeoJSON('towns');
+    map.U.addCircleLayer('small-towns', 'towns', { circleColor: 'green', filter: ['==', 'size', 'small']});
+    map.U.addCircleLayer('large-towns', 'towns', {
+        circleColor: 'red',
+        filter: ['==', 'size', ['large']],
+        circleStrokeWidth: ['case', ['to-boolean', ['feature-state', 'hover']], 5, 1]
+    );
+    map.U.setCircleRadius(['small-towns', 'large-towns'], 12);
+    map.U.hoverPointer(['small-towns', 'large-towns']);
+    map.U.hoverFeatureState('large-towns');
+    // update the source layer when data is available
+    d3.json('http://example.com/towns.json', data => map.U.setData('towns', data));
+});
+</code></pre>
 <h2>Credits</h2>
 <p>Map-GL-Utils was written by, and maintained, by Steve Bennett, a <a href="https://hire.stevebennett.me">freelance map developer</a>.</p>
 <p>Documentation built with <a href="https://github.com/documentationjs/documentation">documentation.js</a>.</p>
