'update' 👉 'content', update tests, docs 📝

src/source/geojson_source.js

@@ -108,11 +108,9 @@ class GeoJSONSource extends Evented {
                 this.fire('error', {error: err});
                 return;
             }
-            // `update` is included here to prevent a race condition where `Style#_updateSources` is called
-            // before the TileJSON arrives. this makes sure the tiles needed are loaded once TileJSON arrives
-            // ref: https://github.com/mapbox/mapbox-gl-js/pull/4347#discussion_r104418088
+            // although GeoJSON sources contain no metadata, we fire this event to let the SourceCache
+            // know its ok to start requesting tiles.
             this.fire('data', {dataType: 'source', sourceDataType: 'metadata'});
-            this.fire('data', {dataType: 'source', sourceDataType: 'update'});
         });
     }
 
@@ -134,7 +132,7 @@ class GeoJSONSource extends Evented {
             if (err) {
                 return this.fire('error', { error: err });
             }
-            this.fire('data', {dataType: 'source', sourceDataType: 'update'});
+            this.fire('data', {dataType: 'source', sourceDataType: 'content'});
         });
 
         return this;

src/source/image_source.js

@@ -123,7 +123,7 @@ class ImageSource extends Evented {
                 Math.round((zoomedCoord.row - centerCoord.row) * EXTENT));
         });
 
-        this.fire('data', {dataType:'source', sourceDataType: 'update'});
+        this.fire('data', {dataType:'source', sourceDataType: 'content'});
         return this;
     }
 

src/source/raster_tile_source.js

@@ -33,11 +33,11 @@ class RasterTileSource extends Evented {
             }
             util.extend(this, tileJSON);
 
-            // `update` is included here to prevent a race condition where `Style#_updateSources` is called
+            // `content` is included here to prevent a race condition where `Style#_updateSources` is called
             // before the TileJSON arrives. this makes sure the tiles needed are loaded once TileJSON arrives
             // ref: https://github.com/mapbox/mapbox-gl-js/pull/4347#discussion_r104418088
             this.fire('data', {dataType: 'source', sourceDataType: 'metadata'});
-            this.fire('data', {dataType: 'source', sourceDataType: 'update'});
+            this.fire('data', {dataType: 'source', sourceDataType: 'content'});
 
         });
     }

src/source/source.js

@@ -50,8 +50,9 @@ exports.setType = function (name, type) {
  * @param {string} options.type The source type, matching the value of `name` used in {@link Style#addSourceType}.
  * @param {Dispatcher} dispatcher A {@link Dispatcher} instance, which can be used to send messages to the workers.
  *
- * @fires data to indicate source data has been loaded, so that it's okay to call `loadTile`
- * @fires change to indicate source data has changed, so that any current caches should be flushed
+ * @fires data with `{dataType: 'source', sourceDataType: 'metadata'}` to indicate that any necessary metadata
+ * has been loaded so that it's okay to call `loadTile`; and with `{dataType: 'source', sourceDataType: 'content'}`
+ * to indicate that the source data has changed, so that any current caches should be flushed.
  * @property {string} id The id for the source.  Must match the id passed to the constructor.
  * @property {number} minzoom
  * @property {number} maxzoom

src/source/source_cache.js

@@ -35,7 +35,7 @@ class SourceCache extends Evented {
 
             // for sources with mutable data, this event fires when the underlying data
             // to a source is changed. (i.e. GeoJSONSource#setData and ImageSource#serCoordinates)
-            if (this._sourceLoaded && e.dataType==="source" && e.sourceDataType==='update') {
+            if (this._sourceLoaded && e.dataType==="source" && e.sourceDataType==='content') {
                 this.reload();
                 if (this.transform) {
                     this.update(this.transform);

src/source/vector_tile_source.js

@@ -39,7 +39,12 @@ class VectorTileSource extends Evented {
                 return;
             }
             util.extend(this, tileJSON);
+             // `content` is included here to prevent a race condition where `Style#_updateSources` is called
+            // before the TileJSON arrives. this makes sure the tiles needed are loaded once TileJSON arrives
+            // ref: https://github.com/mapbox/mapbox-gl-js/pull/4347#discussion_r104418088
             this.fire('data', {dataType: 'source', sourceDataType: 'metadata'});
+            this.fire('data', {dataType: 'source', sourceDataType: 'content'});
+
         });
     }
 

src/ui/map.js

@@ -1676,26 +1676,15 @@ function removeNode(node) {
  */
 
 /**
- * Fired when one of the map's sources loads or changes. This event is not fired
- * if a tile belonging to a source loads or changes (that is handled by
- * `tiledata`). See [`MapDataEvent`](#MapDataEvent) for more information.
+ * Fired when one of the map's sources loads or changes, including if a tile belonging
+ * to a source loads or changes. See [`MapDataEvent`](#MapDataEvent) for more information.
  *
  * @event sourcedata
  * @memberof Map
  * @instance
  * @property {MapDataEvent} data
  */
 
- /**
-  * Fired when one of the map's sources' tiles loads or changes. See
-  * [`MapDataEvent`](#MapDataEvent) for more information.
-  *
-  * @event tiledata
-  * @memberof Map
-  * @instance
-  * @property {MapDataEvent} data
-  */
-
 /**
  * Fired when any map data (style, source, tile, etc) begins loading or
  * changing asyncronously. All `dataloading` events are followed by a `data`
@@ -1720,43 +1709,34 @@ function removeNode(node) {
 
 /**
  * Fired when one of the map's sources begins loading or changing asyncronously.
- * This event is not fired if a tile belonging to a source begins loading or
- * changing (that is handled by `tiledataloading`). All `sourcedataloading`
- * events are followed by a `sourcedata` or `error` event. See
- * [`MapDataEvent`](#MapDataEvent) for more information.
+ * All `sourcedataloading` events are followed by a `sourcedata` or `error` event.
+ * See [`MapDataEvent`](#MapDataEvent) for more information.
  *
  * @event sourcedataloading
  * @memberof Map
  * @instance
  * @property {MapDataEvent} data
  */
 
-/**
- * Fired when one of the map's sources' tiles begins loading or changing
- * asyncronously. All `tiledataloading` events are followed by a `tiledata`
- * or `error` event. See [`MapDataEvent`](#MapDataEvent) for more information.
- *
- * @event tiledataloading
- * @memberof Map
- * @instance
- * @property {MapDataEvent} data
- */
-
  /**
   * A `MapDataEvent` object is emitted with the [`Map#data`](#Map.event:data)
   * and [`Map#dataloading`](#Map.event:dataloading) events. Possible values for
   * `dataType`s are:
   *
   * - `'source'`: The non-tile data associated with any source
   * - `'style'`: The [style](https://www.mapbox.com/mapbox-gl-style-spec/) used by the map
-  * - `'tile'`: A vector or raster tile
   *
   * @typedef {Object} MapDataEvent
   * @property {string} type The event type.
   * @property {string} dataType The type of data that has changed. One of `'source'`, `'style'`.
   * @property {boolean} [isSourceLoaded] True if the event has a `dataType` of `source` and the source has no outstanding network requests.
   * @property {Object} [source] The [style spec representation of the source](https://www.mapbox.com/mapbox-gl-style-spec/#sources) if the event has a `dataType` of `source`.
-  * @property {Coordinate} [coord] The coordinate of the tile if the event has a `dataType` of `tile`.
+  * @property {string} [sourceDataType] Included if the event has a `dataType` of `source` and the event signals
+  * that internal data has been received or changed. Possible values are `metadata` and `content`.
+  * @property {Object} [tile] The tile being loaded or changed, if the event has a `dataType` of `source` and
+  * the event is related to loading of a tile.
+  * @property {Coordinate} [coord] The coordinate of the tile if the event has a `dataType` of `source` and
+  * the event is related to loading of a tile.
   */
 
  /**

test/unit/source/source_cache.test.js

@@ -312,7 +312,7 @@ test('SourceCache / Source lifecycle', (t) => {
         sourceCache.on('data', (e) => {
             if (e.dataType === 'source' && e.sourceDataType === 'metadata') {
                 sourceCache.update(transform);
-                sourceCache.getSource().fire('data', {dataType: 'source', sourceDataType: 'update'});
+                sourceCache.getSource().fire('data', {dataType: 'source', sourceDataType: 'content'});
             }
         });
 

test/unit/source/vector_tile_source.test.js

@@ -71,7 +71,7 @@ test('VectorTileSource', (t) => {
         window.server.respondWith('/source.json', JSON.stringify(require('../../fixtures/source')));
         const source = createSource({ url: "/source.json" });
         source.on('data', (e)=>{
-            if (e.sourceDataType === 'metadata') t.end();
+            if (e.sourceDataType === 'content') t.end();
         });
         window.server.respond();
     });
@@ -85,8 +85,10 @@ test('VectorTileSource', (t) => {
         });
         const source = createSource({ url: "/source.json", eventedParent: evented });
         source.on('data', (e) => {
-            if (e.sourceDataType === 'metadata' && !dataloadingFired) t.fail();
-            t.end();
+            if (e.sourceDataType === 'metadata') {
+                if (!dataloadingFired) t.fail();
+                t.end();
+            }
         });
         window.server.respond();
     });