Update the fileReader and jsonReader docs.

Remove a function that was untested and incorrect from the fileReader.
Add tests for the fileReader.

Rename the `jsonReader` to `geojsonReader`.  An alias called
`jsonReader` is maintained to not break existing code.  The
geojsonReader can take style defaults for points, lines, and polygons.

This uses newer language features, such as the spread operator.

This resolves #822.  This resolves #297, though it does not add a load
event.  If that is still desired, a new issue should be made.

CHANGELOG.md

@@ -5,13 +5,15 @@
 ### Features
 - Added an idle property to objects (#894)
 - Better handling and changing of camera clipbounds (#899)
+- File readers (the geojsonReader) now returns a Promise.  The layer will report that it is not idle until this promise is finalized (#905)
 
 ### Bug Fixes
 - Fixed an issue with overlapping, cropped tiles on old browsers (#901)
 
 ### Changes
 - Changed build process: optional dependencies are now included in the bundle by default (#890)
 - Transpile with Babel to support old browsers and new language features (#900)
+- The geojsonReader has been renamed from `jsonReader` to `geojsonReader`.  The old name still works as an alias (#905)
 
 ## Version 0.17.0
 

docs/users.rst

@@ -181,7 +181,7 @@ documentation for each of the classes.
 `geo.fileReader <http://opengeoscience.github.io/geojs/apidocs/geo.fileReader.html>`_
     This is an abstract class defining the interface for file readers.  Currently,
     the only implemented reader is
-    `geo.jsonReader <http://opengeoscience.github.io/geojs/apidocs/geo.jsonReader.html>`_,
+    `geo.geojsonReader <http://opengeoscience.github.io/geojs/apidocs/geo.geojsonReader.html>`_,
     which is an extendable geojson reader.
 
 Coordinate systems

examples/geoJSON/main.css

@@ -3,7 +3,7 @@
   left: 10px;
   top: 80px;
   width: calc(50% - 10px);
-  height: calc(70% - 100px) !important;
+  height: calc(87% - 80px) !important;
   z-index: 50;
   border-radius: 5px;
   border: 1px solid grey;

examples/geoJSON/main.js

@@ -1,7 +1,11 @@
+/* globals utils */
+
 // Run after the DOM loads
 $(function () {
   'use strict';
 
+  var query = utils.getQuery();
+
   // Create a map object
   var map = geo.map({
     node: '#map',
@@ -27,11 +31,15 @@ $(function () {
 
   // Create a layer to put the features in.  We could need point, line, and
   // polygon features, so ask for a layer that supports all of them.
-  var layer = map.createLayer('feature', {features: ['point', 'line', 'polygon']});
+  // Optionally handle a query parameter to try out specific renderers.
+  var layer = map.createLayer('feature', {
+    renderer: query.renderer ? (query.renderer === 'html' ? null : query.renderer) : undefined,
+    features: query.renderer ? undefined : ['point', 'line', 'polygon']
+  });
   map.draw();
 
   // Initialize the json reader.
-  var reader = geo.createFileReader('jsonReader', {'layer': layer});
+  var reader = geo.createFileReader('geojsonReader', {'layer': layer});
 
   // At this point we could just attach the reader to the map like
   // this:

package.json

@@ -31,6 +31,7 @@
     "babel-core": "^6.26.0",
     "babel-loader": "^7.1.5",
     "babel-plugin-istanbul": "^4.1.6",
+    "babel-plugin-transform-object-rest-spread": "^6.26.0",
     "babel-polyfill": "^6.26.0",
     "babel-preset-env": "^1.7.0",
     "body-parser": "^1.15.0",

src/annotationLayer.js

@@ -12,8 +12,9 @@ var textFeature = require('./textFeature');
  * @typedef {object} geo.annotationLayer.labelRecord
  * @property {string} text The text of the label
  * @property {geo.geoPosition} position The position of the label in map gcs
- *      coordinates.
- * @property {object} [style] A {@link geo.textFeature} style object.
+ *    coordinates.
+ * @property {geo.textFeature.styleSpec} [style] A {@link geo.textFeature}
+ *    style object.
  */
 
 /**
@@ -601,7 +602,7 @@ var annotationLayer = function (args) {
    */
   this.geojson = function (geojson, clear, gcs, includeCrs) {
     if (geojson !== undefined) {
-      var reader = registry.createFileReader('jsonReader', {layer: m_this});
+      var reader = registry.createFileReader('geojsonReader', {layer: m_this});
       if (!reader.canRead(geojson)) {
         return;
       }

src/fileReader.js

@@ -3,11 +3,19 @@ var featureLayer = require('./featureLayer');
 var object = require('./object');
 
 /**
- * Create a new instance of class fileReader
+ * Object specification for a fileReader.
+ *
+ * @typedef {object} geo.fileReader.spec
+ * @property {geo.featureLayer} layer The target feature layer.
+ */
+
+/**
+ * Create a new instance of class fileReader.
  *
  * @class
  * @alias geo.fileReader
  * @extends geo.object
+ * @param {geo.fileReader.spec} arg
  * @returns {geo.fileReader}
  */
 var fileReader = function (arg) {
@@ -29,65 +37,93 @@ var fileReader = function (arg) {
   var m_layer = arg.layer;
 
   /**
-   * Get the feature layer attached to the reader
+   * Get the feature layer attached to the reader.
+   *
+   * @returns {geo.featureLayer} The layer associated with the reader.
    */
   this.layer = function () {
     return m_layer;
   };
 
   /**
    * Tells the caller if it can handle the given file by returning a boolean.
+   *
+   * @param {File|Blob|string|object} file This is either a `File` object, a
+   *    `Blob` object, a string representation of a file, or an object
+   *    representing data from a file.
+   * @returns {boolean} `true` if this reader can read a file.
    */
-  this.canRead = function () {
+  this.canRead = function (file) {
     return false;
   };
 
   /**
-   * Reads the file object and calls the done function when finished.  As an
-   * argument to done, provides a boolean that reports if the read was a
-   * success.  Possibly, it can call done with an object containing details
+   * Reads the file and optionally calls a function when finished.  The `done`
+   * function is called with a value that is truthy if the read was a success.
+   * Depending on the specific reader, this value may be an object with details
    * of the read operation.
+   *
+   * @param {File|Blob|string|object} file This is either a `File` object, a
+   *    `Blob` object, a string representation of a file, or an object
+   *    representing data from a file.
+   * @param {function} [done] An optional callback function when the read is
+   *    complete.  This is called with `false` on error or the object that was
+   *    read and parsed by the reader.
+   * @param {function} [progress] A function which is passed `ProgressEvent`
+   *    information from a `FileReader`.  This includes `loaded` and `total`
+   *    each with a number of bytes.
+   * @returns {Promise} A `Promise` that resolves with object parsed by the
+   *    reader or is rejected if the reader fails.
    */
-  this.read = function (file, done) {
-    done(false);
+  this.read = function (file, done, progress) {
+    var promise = new Promise(function (resolve, reject) {
+      if (done) {
+        done(false);
+      }
+      throw new Error('The default file reader always fails');
+    });
+    this.addPromise(promise);
+    return promise;
   };
 
   /**
-   * Return a FileReader with handlers attached.
+   * Return a `FileReader` with handlers attached.
+   *
+   * @param {function} done A callback that receives either the string read
+   *    from the file or a `DOMException` with an error.
+   * @param {function} [progress] A function which is passed `ProgressEvent`
+   *    information from a `FileReader`.  This includes `loaded` and `total`
+   *    each with a number of bytes.
+   * @returns {FileReader} The `FileReader` with done and progress handles
+   *    attached to it.
    */
   function newFileReader(done, progress) {
     var reader = new FileReader();
     if (progress) {
       reader.onprogress = progress;
     }
     reader.onloadend = function () {
-      if (!reader.result) {
-        done(reader.error);
-      }
-      done(reader.result);
+      done(reader.error || reader.result);
     };
     return reader;
   }
 
   /**
-   * Private method for reading a file object as a string.  Calls done with
-   * the string content when finished or an error object if unsuccessful.
-   * Optionally, the caller can provide a progress method that is called
-   * after reading each slice.
+   * Read a file object as a string.  Calls `done` with the string content
+   * when finished or an error object if unsuccessful.
+   *
+   * @param {File|Blob} file A `File` or `Blob` object to read.
+   * @param {function} done A callback that receives either the string read
+   *    from the file or a `DOMException` with an error.
+   * @param {function} [progress] A function which is passed `ProgressEvent`
+   *    information from a `FileReader`.  This includes `loaded` and `total`
+   *    each with a number of bytes.
    */
   this._getString = function (file, done, progress) {
     var reader = newFileReader(done, progress);
     reader.readAsText(file);
   };
 
-  /**
-   * Like _getString, but returns an ArrayBuffer object.
-   */
-  this._getArrayBuffer = function (file, done, progress) {
-    var reader = newFileReader(done, progress);
-    reader.readAsText(file);
-  };
-
   return this;
 };