Add new powerful apply() function

README.md

@@ -9,73 +9,67 @@ To use a standalone build of ol-mapbox-style, just include 'dist/olms.js' on you
 The code below creates a Mapbox Streets v7 layer with the bright v9 style:
 
 ```js
-import * as olms from 'ol-mapbox-style';
-// OpenLayers imports from https://npmjs.com/package/ol
-import tilegrid from 'ol/tilegrid';
-import VectorTileLayer from 'ol/layer/vectortile';
-import VectorTileSource from 'ol/source/vectortile';
-import MVT from 'ol/format/MVT';
+import { apply } from 'ol-mapbox-style';
 
 var key = 'Your Mapbox Access Token here';
-
-var tileGrid = tilegrid.createXYZ({tileSize: 512, maxZoom: 22});
-var layer = new VectorTileLayer({
-  source: new VectorTileSource({
-    attributions: '© <a href="https://www.mapbox.com/map-feedback/">Mapbox</a> ' +
-      '© <a href="http://www.openstreetmap.org/copyright">' +
-      'OpenStreetMap contributors</a>',
-    format: new MVT(),
-    tileGrid: tileGrid,
-    tilePixelRatio: 8,
-    url: 'http://{a-d}.tiles.mapbox.com/v4/mapbox.mapbox-streets-v7/' +
-        '{z}/{x}/{y}.vector.pbf?access_token=' + key
-  })
-});
-
-fetch('https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=' + key).then(function(response) {
-  response.json().then(function(glStyle) {
-    glStyle.sprite = 'https://api.mapbox.com/styles/v1/mapbox/bright-v9/sprite?access_token=' + key;
-    olms.applyStyle(layer, glStyle, 'mapbox').then(function() {
-      // Style is ready to use - add the layer to your OpenLayers Map instance
-      map.addLayer(layer);
-    });
-  });
-});
+apply('map', 'https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=' + key);
 ```
 
 Only commonly available system fonts and [Google Fonts](https://developers.google.com/fonts/) will automatically be available for text defined in the Mapbox Style object. It is the responsibility of the application to load other fonts.
 
-To apply the properties of the Mapbox Style's `background` layer to the map, use the `applyBackground` function.
+To apply a subset of the layers defined in the Mapbox Style layer to a custom OpenLayers layer, use the `applyStyle()` function.
+
+To apply the properties of the Mapbox Style's `background` layer to the map, use the `applyBackground()` function.
 
 ## API
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
 ### applyStyle
 
-Applies a style function to an `ol.layer.VectorTile` with an
-`ol.source.VectorTile`. The style function will render all layers from the
-`glStyle` object that use the specified `source`, which needs to be a
-`"type": "vector"` source.
+Applies a style function to an `ol.layer.VectorTile` or `ol.layer.Vector`
+with an `ol.source.VectorTile` or an `ol.source.Vector`. The style function
+will render all layers from the `glStyle` object that use the specified
+`source`, or a subset of layers from the same source. The source needs to be
+a `"type": "vector"` or `"type": "geojson"` source.
 
 **Parameters**
 
 -   `layer` **ol.layer.VectorTile** OpenLayers layer.
 -   `glStyle` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** Mapbox Style object.
--   `source` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** `source` key from the Mapbox Style object.
+-   `source` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** `source` key or an array of layer `id`s from the
+    Mapbox Style object. When a `source` key is provided, all layers for the
+    specified source will be included in the style function. When layer `id`s
+    are provided, they must be from layers that use the same source.
 
 Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Promise which will be resolved when the style can be used
 for rendering.
 
 ### applyBackground
 
-Applies properties of the Mapbox Style's `background` layer to the map.
+Applies properties of the Mapbox Style's first `background` layer to the map.
 
 **Parameters**
 
--   `map` **ol.Map** OpenLayers Map. Must have a `target` configured.
+-   `map` **ol.Map** OpenLayers Map.
 -   `glStyle` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** Mapbox Style object.
 
+### apply
+
+Loads and applies a Mapbox Style object to an OpenLayers Map.
+
+**Parameters**
+
+-   `map` **(ol.Map | [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) | stribng)** Either an existing OpenLayers Map
+    instance, or a HTML element, or the id of a HTML element that will be the
+    target of a new OpenLayers Map.
+-   `style` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** Url pointing to a Mapbox Style object. When using
+    Mapbox APIs, the url must contain an access token and look like
+    `https://api.mapbox.com/styles/v1/mapbox/bright-v9?access_token=[your_access_token_here]`.
+
+Returns **ol.Map** The OpenLayers Map instance that will be populated with the
+contents described in the Mapbox Style object.
+
 ## Building the library
 
     npm install

example/index.html

@@ -2,6 +2,7 @@
 <html>
 <head>
   <title>Mapbox Bright V9</title>
+  <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Open+Sans" />
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/ol3/3.20.1/ol.css">
   <style>
     html, body {

example/index.js

@@ -6,34 +6,4 @@ if (!key) {
   document.cookie = 'mapbox_access_token=' + key + '; expires=Fri, 31 Dec 9999 23:59:59 GMT';
 }
 
-var tilegrid = ol.tilegrid.createXYZ({tileSize: 512, maxZoom: 22});
-var layer = new ol.layer.VectorTile({
-  source: new ol.source.VectorTile({
-    attributions: '© <a href="https://www.mapbox.com/map-feedback/">Mapbox</a> ' +
-      '© <a href="http://www.openstreetmap.org/copyright">' +
-      'OpenStreetMap contributors</a>',
-    format: new ol.format.MVT(),
-    tileGrid: tilegrid,
-    tilePixelRatio: 8,
-    url: 'https://{a-d}.tiles.mapbox.com/v4/mapbox.mapbox-streets-v7/' +
-        '{z}/{x}/{y}.vector.pbf?access_token=' + key
-  })
-});
-var map = new ol.Map({
-  target: 'map',
-  view: new ol.View({
-    center: [1822363, 6141705],
-    zoom: 11,
-    maxResolution: 78271.51696402048
-  })
-});
-
-fetch(baseUrl + '?access_token=' + key).then(function(response) {
-  response.json().then(function(glStyle) {
-    olms.applyBackground(map, glStyle);
-    glStyle.sprite = baseUrl + '/sprite?access_token=' + key;
-    olms.applyStyle(layer, glStyle, 'mapbox').then(function() {
-      map.addLayer(layer);
-    });
-  });
-});
+olms.apply('map', baseUrl + '?access_token=' + key);