Merge pull request #11628 from simonseyock/vector-source-load-events

VectorSource load events

src/ol/featureloader.js

@@ -16,15 +16,19 @@ let withCredentials = false;
  * load features.
  *
  * This function takes an {@link module:ol/extent~Extent} representing the area to be loaded,
- * a `{number}` representing the resolution (map units per pixel) and an
+ * a `{number}` representing the resolution (map units per pixel), an
- * {@link module:ol/proj/Projection} for the projection  as
+ * {@link module:ol/proj/Projection} for the projection and success and failure callbacks as
  * arguments. `this` within the function is bound to the
  * {@link module:ol/source/Vector} it's called from.
  *
  * The function is responsible for loading the features and adding them to the
  * source.
- * @typedef {function(this:(import("./source/Vector").default|import("./VectorTile.js").default), import("./extent.js").Extent, number,
+ * @typedef {function(this:(import("./source/Vector").default|import("./VectorTile.js").default),
- *                    import("./proj/Projection.js").default): void} FeatureLoader
+ *           import("./extent.js").Extent,
+ *           number,
+ *           import("./proj/Projection.js").default,
+ *           function(Array<import("./Feature.js").default>): void=,
+ *           function(): void=): void} FeatureLoader
  * @api
  */
 
@@ -43,81 +47,77 @@ let withCredentials = false;
 /**
  * @param {string|FeatureUrlFunction} url Feature URL service.
  * @param {import("./format/Feature.js").default} format Feature format.
- * @param {function(this:import("./VectorTile.js").default, Array<import("./Feature.js").default>, import("./proj/Projection.js").default, import("./extent.js").Extent): void|function(this:import("./source/Vector").default, Array<import("./Feature.js").default>): void} success
+ * @param {import("./extent.js").Extent} extent Extent.
- *     Function called with the loaded features and optionally with the data
+ * @param {number} resolution Resolution.
- *     projection. Called with the vector tile or source as `this`.
+ * @param {import("./proj/Projection.js").default} projection Projection.
- * @param {function(this:import("./VectorTile.js").default): void|function(this:import("./source/Vector").default): void} failure
+ * @param {function(Array<import("./Feature.js").default>, import("./proj/Projection.js").default): void} success Success
- *     Function called when loading failed. Called with the vector tile or
+ *      Function called with the loaded features and optionally with the data projection.
- *     source as `this`.
+ * @param {function(): void} failure Failure
- * @return {FeatureLoader} The feature loader.
+ *      Function called when loading failed.
  */
-export function loadFeaturesXhr(url, format, success, failure) {
+export function loadFeaturesXhr(
-  return (
+  url,
-    /**
+  format,
-     * @param {import("./extent.js").Extent} extent Extent.
+  extent,
-     * @param {number} resolution Resolution.
+  resolution,
-     * @param {import("./proj/Projection.js").default} projection Projection.
+  projection,
-     * @this {import("./source/Vector").default|import("./VectorTile.js").default}
+  success,
-     */
+  failure
-    function (extent, resolution, projection) {
+) {
-      const xhr = new XMLHttpRequest();
+  const xhr = new XMLHttpRequest();
-      xhr.open(
+  xhr.open(
-        'GET',
+    'GET',
-        typeof url === 'function' ? url(extent, resolution, projection) : url,
+    typeof url === 'function' ? url(extent, resolution, projection) : url,
-        true
+    true
-      );
-      if (format.getType() == FormatType.ARRAY_BUFFER) {
-        xhr.responseType = 'arraybuffer';
-      }
-      xhr.withCredentials = withCredentials;
-      /**
-       * @param {Event} event Event.
-       * @private
-       */
-      xhr.onload = function (event) {
-        // status will be 0 for file:// urls
-        if (!xhr.status || (xhr.status >= 200 && xhr.status < 300)) {
-          const type = format.getType();
-          /** @type {Document|Node|Object|string|undefined} */
-          let source;
-          if (type == FormatType.JSON || type == FormatType.TEXT) {
-            source = xhr.responseText;
-          } else if (type == FormatType.XML) {
-            source = xhr.responseXML;
-            if (!source) {
-              source = new DOMParser().parseFromString(
-                xhr.responseText,
-                'application/xml'
-              );
-            }
-          } else if (type == FormatType.ARRAY_BUFFER) {
-            source = /** @type {ArrayBuffer} */ (xhr.response);
-          }
-          if (source) {
-            success.call(
-              this,
-              format.readFeatures(source, {
-                extent: extent,
-                featureProjection: projection,
-              }),
-              format.readProjection(source)
-            );
-          } else {
-            failure.call(this);
-          }
-        } else {
-          failure.call(this);
-        }
-      }.bind(this);
-      /**
-       * @private
-       */
-      xhr.onerror = function () {
-        failure.call(this);
-      }.bind(this);
-      xhr.send();
-    }
   );
+  if (format.getType() == FormatType.ARRAY_BUFFER) {
+    xhr.responseType = 'arraybuffer';
+  }
+  xhr.withCredentials = withCredentials;
+  /**
+   * @param {Event} event Event.
+   * @private
+   */
+  xhr.onload = function (event) {
+    // status will be 0 for file:// urls
+    if (!xhr.status || (xhr.status >= 200 && xhr.status < 300)) {
+      const type = format.getType();
+      /** @type {Document|Node|Object|string|undefined} */
+      let source;
+      if (type == FormatType.JSON || type == FormatType.TEXT) {
+        source = xhr.responseText;
+      } else if (type == FormatType.XML) {
+        source = xhr.responseXML;
+        if (!source) {
+          source = new DOMParser().parseFromString(
+            xhr.responseText,
+            'application/xml'
+          );
+        }
+      } else if (type == FormatType.ARRAY_BUFFER) {
+        source = /** @type {ArrayBuffer} */ (xhr.response);
+      }
+      if (source) {
+        success(
+          /** @type {Array<import("./Feature.js").default>} */
+          (format.readFeatures(source, {
+            extent: extent,
+            featureProjection: projection,
+          })),
+          format.readProjection(source)
+        );
+      } else {
+        failure();
+      }
+    } else {
+      failure();
+    }
+  };
+  /**
+   * @private
+   */
+  xhr.onerror = failure;
+  xhr.send();
 }
 
 /**
@@ -130,25 +130,38 @@ export function loadFeaturesXhr(url, format, success, failure) {
  * @api
  */
 export function xhr(url, format) {
-  return loadFeaturesXhr(
+  /**
-    url,
+   * @param {import("./extent.js").Extent} extent Extent.
-    format,
+   * @param {number} resolution Resolution.
-    /**
+   * @param {import("./proj/Projection.js").default} projection Projection.
-     * @param {Array<import("./Feature.js").default>} features The loaded features.
+   * @param {function(): void=} success Success
-     * @param {import("./proj/Projection.js").default} dataProjection Data
+   *      Function called when loading succeeded.
-     * projection.
+   * @param {function(): void=} failure Failure
-     * @this {import("./source/Vector").default|import("./VectorTile.js").default}
+   *      Function called when loading failed.
-     */
+   * @this {import("./source/Vector").default}
-    function (features, dataProjection) {
+   */
-      const sourceOrTile = /** @type {?} */ (this);
+  return function (extent, resolution, projection, success, failure) {
-      if (typeof sourceOrTile.addFeatures === 'function') {
+    const source = /** @type {import("./source/Vector").default} */ (this);
-        /** @type {import("./source/Vector").default} */ (sourceOrTile).addFeatures(
+    loadFeaturesXhr(
-          features
+      url,
-        );
+      format,
-      }
+      extent,
-    },
+      resolution,
-    /* FIXME handle error */ VOID
+      projection,
-  );
+      /**
+       * @param {Array<import("./Feature.js").default>} features The loaded features.
+       * @param {import("./proj/Projection.js").default} dataProjection Data
+       * projection.
+       */
+      function (features, dataProjection) {
+        if (success !== undefined) {
+          success(features);
+        }
+        source.addFeatures(features);
+      },
+      /* FIXME handle error */ failure ? failure : VOID
+    );
+  };
 }
 
 /**

src/ol/source/Vector.js

@@ -40,16 +40,24 @@ export class VectorSourceEvent extends Event {
   /**
    * @param {string} type Type.
    * @param {import("../Feature.js").default<Geometry>=} opt_feature Feature.
+   * @param {Array<import("../Feature.js").default<Geometry>>=} opt_features Features.
    */
-  constructor(type, opt_feature) {
+  constructor(type, opt_feature, opt_features) {
     super(type);
 
     /**
-     * The feature being added or removed.
+     * The added or removed feature for the `ADDFEATURE` and `REMOVEFEATURE` events, `undefined` otherwise.
      * @type {import("../Feature.js").default<Geometry>|undefined}
      * @api
      */
     this.feature = opt_feature;
+
+    /**
+     * The loaded features for the `FEATURESLOADED` event, `undefined` otherwise.
+     * @type {Array<import("../Feature.js").default<Geometry>>|undefined}
+     * @api
+     */
+    this.features = opt_features;
   }
 }
 
@@ -904,7 +912,29 @@ class VectorSource extends Source {
         }
       );
       if (!alreadyLoaded) {
-        this.loader_.call(this, extentToLoad, resolution, projection);
+        this.dispatchEvent(
+          new VectorSourceEvent(VectorEventType.FEATURESLOADSTART)
+        );
+        this.loader_.call(
+          this,
+          extentToLoad,
+          resolution,
+          projection,
+          function (features) {
+            this.dispatchEvent(
+              new VectorSourceEvent(
+                VectorEventType.FEATURESLOADEND,
+                undefined,
+                features
+              )
+            );
+          }.bind(this),
+          function () {
+            this.dispatchEvent(
+              new VectorSourceEvent(VectorEventType.FEATURESLOADERROR)
+            );
+          }.bind(this)
+        );
         loadedExtentsRtree.insert(extentToLoad, {extent: extentToLoad.slice()});
         this.loading = this.loader_ !== VOID;
       }

src/ol/source/VectorEventType.js

@@ -34,4 +34,25 @@ export default {
    * @api
    */
   REMOVEFEATURE: 'removefeature',
+
+  /**
+   * Triggered when features starts loading.
+   * @event module:ol/source/Vector.VectorSourceEvent#featureloadstart
+   * @api
+   */
+  FEATURESLOADSTART: 'featuresloadstart',
+
+  /**
+   * Triggered when features finishes loading.
+   * @event module:ol/source/Vector.VectorSourceEvent#featureloadend
+   * @api
+   */
+  FEATURESLOADEND: 'featuresloadend',
+
+  /**
+   * Triggered if feature loading results in an error.
+   * @event module:ol/source/Vector.VectorSourceEvent#featureloaderror
+   * @api
+   */
+  FEATURESLOADERROR: 'featuresloaderror',
 };

src/ol/source/VectorTile.js

@@ -528,11 +528,22 @@ export default VectorTile;
  * @param {string} url URL.
  */
 export function defaultLoadFunction(tile, url) {
-  const loader = loadFeaturesXhr(
+  tile.setLoader(
-    url,
+    /**
-    tile.getFormat(),
+     * @param {import("../extent.js").Extent} extent Extent.
-    tile.onLoad.bind(tile),
+     * @param {number} resolution Resolution.
-    tile.onError.bind(tile)
+     * @param {import("../proj/Projection.js").default} projection Projection.
+     */
+    function (extent, resolution, projection) {
+      loadFeaturesXhr(
+        url,
+        tile.getFormat(),
+        extent,
+        resolution,
+        projection,
+        tile.onLoad.bind(tile),
+        tile.onError.bind(tile)
+      );
+    }
   );
-  tile.setLoader(loader);
 }

test/spec/ol/featureloader.test.js

@@ -19,8 +19,10 @@ describe('ol.featureloader', function () {
     it('adds features to the source', function (done) {
       loader = xhr(url, format);
       source.on('addfeature', function (e) {
-        expect(source.getFeatures().length).to.be.greaterThan(0);
+        setTimeout(function () {
-        done();
+          expect(source.getFeatures().length).to.be.greaterThan(0);
+          done();
+        }, 0);
       });
       loader.call(source, [], 1, 'EPSG:3857');
     });
@@ -33,8 +35,10 @@ describe('ol.featureloader', function () {
         loader = xhr(url, format);
 
         source.on('addfeature', function (e) {
-          expect(source.getFeatures().length).to.be.greaterThan(0);
+          setTimeout(function () {
-          done();
+            expect(source.getFeatures().length).to.be.greaterThan(0);
+            done();
+          }, 0);
         });
         loader.call(source, [], 1, 'EPSG:3857');
       });
@@ -54,5 +58,23 @@ describe('ol.featureloader', function () {
         loader.call(source, [], 1, 'EPSG:3857');
       });
     });
+
+    it('it calls the success callback', function (done) {
+      const errorSpy = sinon.spy();
+      loader = xhr(url, format);
+      loader.call(
+        source,
+        [],
+        1,
+        'EPSG:3857',
+        function () {
+          setTimeout(function () {
+            expect(errorSpy.callCount).to.be(0);
+            done();
+          }, 0);
+        },
+        errorSpy
+      );
+    });
   });
 });

test/spec/ol/source/vector.test.js

@@ -559,6 +559,35 @@ describe('ol.source.Vector', function () {
   });
 
   describe('#loadFeatures', function () {
+    it('fires the FEATURESLOADSTART event', function (done) {
+      const source = new VectorSource();
+      source.on('featuresloadstart', function () {
+        done();
+      });
+      source.loadFeatures(
+        [-10000, -10000, 10000, 10000],
+        1,
+        getProjection('EPSG:3857')
+      );
+    });
+
+    it('fires the FEATURESLOADEND event if the default load function is used', function (done) {
+      const source = new VectorSource({
+        format: new GeoJSON(),
+        url: 'spec/ol/source/vectorsource/single-feature.json',
+      });
+      source.on('featuresloadend', function (event) {
+        expect(event.features).to.be.an('array');
+        expect(event.features.length).to.be(1);
+        done();
+      });
+      source.loadFeatures(
+        [-10000, -10000, 10000, 10000],
+        1,
+        getProjection('EPSG:3857')
+      );
+    });
+
     describe('with the "bbox" strategy', function () {
       it('requests the view extent plus render buffer', function (done) {
         const center = [-97.6114, 38.8403];
@@ -661,6 +690,54 @@ describe('ol.source.Vector', function () {
           getProjection('EPSG:3857')
         );
       });
+
+      it('fires the FEATURESLOADEND event if the load function uses the callback', function (done) {
+        const source = new VectorSource();
+        const spy = sinon.spy();
+        source.on('featuresloadend', spy);
+
+        const features = [new Feature(), new Feature()];
+
+        source.setLoader(function (bbox, resolution, projection, success) {
+          success(features);
+          setTimeout(function () {
+            expect(spy.calledOnce).to.be(true);
+            const event = spy.getCall(0).args[0];
+            expect(event.features).to.be(features);
+            done();
+          }, 0);
+        });
+        source.loadFeatures(
+          [-10000, -10000, 10000, 10000],
+          1,
+          getProjection('EPSG:3857')
+        );
+      });
+
+      it('fires the FEATURESLOADERROR event if the load function uses the callback', function (done) {
+        const source = new VectorSource();
+        const spy = sinon.spy();
+        source.on('featuresloaderror', spy);
+
+        source.setLoader(function (
+          bbox,
+          resolution,
+          projection,
+          success,
+          failure
+        ) {
+          failure();
+          setTimeout(function () {
+            expect(spy.calledOnce).to.be(true);
+            done();
+          }, 0);
+        });
+        source.loadFeatures(
+          [-10000, -10000, 10000, 10000],
+          1,
+          getProjection('EPSG:3857')
+        );
+      });
     });
   });