Notes on using the v4 Mapbox API

changelog/upgrade-notes.md

@@ -4,6 +4,23 @@
 
 This option is no longer needed, so it was removed from the API.
 
+#### XHR loading for `ol.source.TileUTFGrid`
+
+The `ol.source.TileUTFGrid` now uses XMLHttpRequest to load UTFGrid tiles by default.  This works out of the box with the v4 Mapbox API.  To work with the v3 API, you must use the new `jsonp` option on the source.  See the examples below for detail.
+
+```js
+// To work with the v4 API
+var v4source = new ol.source.TileUTFGrid({
+  url: 'http://api.tiles.mapbox.com/v4/example.json?access_token=' + YOUR_KEY_HERE
+});
+
+// To work with the v3 API
+var v3source = new ol.source.TileUTFGrid({
+  jsonp: true, // <--- this is required for v3
+  url: 'http://api.tiles.mapbox.com/v3/example.json?access_token=' + YOUR_KEY_HERE
+});
+```
+
 ### v3.15.0
 
 #### Internet Explorer 9 support

examples/tileutfgrid.html

@@ -6,6 +6,8 @@ docs: >
   <p>Point to a country to see its name and flag.</p>
   Tiles made with [TileMill](http://tilemill.com). Hosting on MapBox.com or with open-source [TileServer](https://github.com/klokantech/tileserver-php/).
 tags: "utfgrid, tileutfgrid, tilejson"
+cloak:
+  pk.eyJ1IjoiYWhvY2V2YXIiLCJhIjoiRk1kMWZaSSJ9.E5BkluenyWQMsBLsuByrmg: Your Mapbox access token from http://mapbox.com/ here
 ---
 <div id="map" class="map"></div>
 <div style="display: none;">

examples/tileutfgrid.js

@@ -5,15 +5,17 @@ goog.require('ol.layer.Tile');
 goog.require('ol.source.TileJSON');
 goog.require('ol.source.TileUTFGrid');
 
+var key = 'pk.eyJ1IjoiYWhvY2V2YXIiLCJhIjoiRk1kMWZaSSJ9.E5BkluenyWQMsBLsuByrmg';
+
 var mapLayer = new ol.layer.Tile({
   source: new ol.source.TileJSON({
-    url: 'http://api.tiles.mapbox.com/v3/mapbox.geography-class.json'
+    url: 'http://api.tiles.mapbox.com/v4/mapbox.geography-class.json?access_token=' + key
   })
 });
 
+
 var gridSource = new ol.source.TileUTFGrid({
-  jsonp: true, // for v4 and above, leave this option off
-  url: 'http://api.tiles.mapbox.com/v3/mapbox.geography-class.json'
+  url: 'http://api.tiles.mapbox.com/v4/mapbox.geography-class.json?access_token=' + key
 });
 
 var gridLayer = new ol.layer.Tile({source: gridSource});