Merge pull request #904 from OpenGeoscience/style-spec

Added style typedefs.

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### 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)
@@ -13,6 +14,7 @@
 ### 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:

jsdoc/plugins/typedef_augments.js

@@ -44,10 +44,10 @@ exports.handlers = {
          * reversing the augments list). */
         doclet.augments.slice().reverse().forEach(function (augmentName) {
           if (augmentName !== name && typedefs[augmentName] && typedefs[augmentName].properties) {
-            typedefs[augmentName].properties.forEach(function (prop) {
-              if (!properties[prop.name]) {
+            typedefs[augmentName].properties.forEach(function (origprop) {
+              if (!properties[origprop.name]) {
                 /* Make a copy so we don't mutate the original property. */
-                prop = Object.assign(prop);
+                var prop = Object.assign({}, origprop);
                 /* Add a value that a rendering template could use to show that
                  * the property was inherted from a parent.  Since that in turn
                  * could have been inherited, preserve a known value. */

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/action.js

@@ -4,6 +4,7 @@
  *
  * @namespace
  * @alias geo.action
+ * @enum {string}
  */
 var geo_action = {
   momentum: 'geo_action_momentum',

src/annotation.js

@@ -1082,13 +1082,10 @@ var annotation = function (type, args) {
  *    coordinates.  These must be in order around the perimeter of the
  *    rectangle (in either direction).
  * @property {geo.geoPosition[]} [coordinates] An alternate name for `corners`.
- * @property {object} [style] The style to apply to a finished rectangle.  This
- *    uses styles for polygons, including `fill`, `fillColor`, `fillOpacity`,
- *    `stroke`, `strokeWidth`, `strokeColor`, and `strokeOpacity`.
- * @property {object} [editStyle] The style to apply to a rectangle in edit
- *    mode.  This uses styles for polygons and lines, including `fill`,
- *    `fillColor`, `fillOpacity`, `stroke`, `strokeWidth`, `strokeColor`, and
- *    `strokeOpacity`.
+ * @property {geo.polygonFeature.styleSpec} [style] The style to apply to a
+ *    finished rectangle.  This uses styles for {@link geo.polygonFeature}.
+ * @property {geo.polygonFeature.styleSpec} [editStyle] The style to apply to a
+ *    rectangle in edit mode.
  */
 
 /**
@@ -1470,13 +1467,10 @@ registerAnnotation('rectangle', rectangleAnnotation, rectangleRequiredFeatures);
  *    (in either direction).
  * @property {geo.geoPosition[]} [coordinates] An alternate name for
  *    `vertices`.
- * @property {object} [style] The style to apply to a finished polygon.  This
- *    uses styles for polygons, including `fill`, `fillColor`, `fillOpacity`,
- *    `stroke`, `strokeWidth`, `strokeColor`, and `strokeOpacity`.
- * @property {object} [editStyle] The style to apply to a polygon in edit mode.
- *    This uses styles for polygons and lines, including `fill`, `fillColor`,
- *    `fillOpacity`, `stroke`, `strokeWidth`, `strokeColor`, and
- *    `strokeOpacity`.
+ * @property {geo.polygonFeature.styleSpec} [style] The style to apply to a
+ *    finished polygon.  This uses styles for {@link geo.polygonFeature}.
+ * @property {geo.polygonFeature.styleSpec} [editStyle] The style to apply to ai
+ *    polygon in edit mode.
  */
 
 /**
@@ -1735,12 +1729,10 @@ registerAnnotation('polygon', polygonAnnotation, polygonRequiredFeatures);
  *    coordinates.
  * @property {geo.geoPosition[]} [coordinates] An alternate name for
  *    `vertices`.
- * @property {object} [style] The style to apply to a finished line.  This uses
- *    styles for lines, including `strokeWidth`, `strokeColor`,
- *    `strokeOpacity`, `strokeOffset`, `closed`, `lineCap`, and `lineJoin`.
- * @property {object} [editStyle] The style to apply to a line in edit mode.
- *    This uses styles for lines, including `strokeWidth`, `strokeColor`,
- *    `strokeOpacity`, `strokeOffset`, `closed`, `lineCap`, and `lineJoin`.
+ * @property {geo.lineFeature.styleSpec} [style] The style to apply to a
+ *    finished line.  This uses styles for {@link geo.lineFeature}.
+ * @property {geo.lineFeature.styleSpec} [editStyle] The style to apply to a
+ *    line in edit mode.
  */
 
 /**
@@ -2120,14 +2112,14 @@ registerAnnotation('line', lineAnnotation, lineRequiredFeatures);
  * @property {geo.geoPosition} [position] A coordinate in map gcs coordinates.
  * @property {geo.geoPosition[]} [coordinates] An array with one coordinate to
  *    use in place of `position`.
- * @property {object} [style] The style to apply to a finished point.  This
- *    uses styles for points, including `radius`, `fill`, `fillColor`,
- *    `fillOpacity`, `stroke`, `strokeWidth`, `strokeColor`, `strokeOpacity`,
- *    and `scaled`.  If `scaled` is `false`, the point is not scaled with zoom
- *    level.  If it is `true`, the radius is based on the zoom level at first
- *    instantiation.  Otherwise, if it is a number, the radius is used at that
+ * @property {geo.pointFeature.styleSpec} [style] The style to apply to a
+ *    finished point.  This uses styles for {@link geo.pointFeature}.
+ * @property {boolean|number} [style.scaled=false] If `false`, the point is not
+ *    scaled with zoom level.  If `true`, the radius is based on the zoom level
+ *    at first instantiation.  If a number, the radius is used at the `scaled`
  *    zoom level.
- * @property {object} [editStyle] The style to apply to a point in edit mode.
+ * @property {geo.pointFeature.styleSpec} [editStyle] The style to apply to a
+ *    point in edit mode.
  */
 
 /**

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/contourFeature.js

@@ -7,22 +7,27 @@ var meshFeature = require('./meshFeature');
  * @typedef {geo.feature.spec} geo.contourFeature.spec
  * @property {object[]} [data=[]] An array of arbitrary objects used to
  *    construct the feature.
- * @property {object} [style] An object that contains style values for the
- *    feature.
- * @property {number|function} [style.opacity=1] The opacity on a scale of 0 to
- *    1.
- * @property {geo.geoPosition|function} [style.position=data] The position of
- *    each data element.  This defaults to just using `x`, `y`, and `z`
- *    properties of the data element itself.  The position is in the feature's
- *    gcs coordinates.
- * @property {number|function} [style.value=data.z] The value of each data
- *    element.  This defaults `z` properties of the data element.  If the value
- *    of a grid point is `null` or `undefined`, that point and elements that
- *    use that point won't be included in the results.
+ * @property {geo.contourFeature.styleSpec} [style] An object that contains
+ *    style values for the feature.
  * @property {geo.contourFeature.contourSpec} [contour] The contour
  *    specification for the feature.
  */
 
+/**
+ * Style specification for a contour feature.
+ *
+ * @typedef {geo.feature.styleSpec} geo.contourFeature.styleSpec
+ * @extends geo.feature.styleSpec
+ * @property {geo.geoPosition|function} [position=data] The position of each
+ *    data element.  This defaults to just using `x`, `y`, and `z` properties
+ *    of the data element itself.  The position is in the feature's gcs
+ *    coordinates.
+ * @property {number|function} [value=data.z] The value of each data element.
+ *    This defaults to the `z` property of the data elements.  If the value of
+ *    a grid point is `null` or `undefined`, the point and elements that use
+ *    that point won't be included in the results.
+ */
+
 /**
  * Contour specification.  All of these properties can be functions, which get
  * passed the {@link geo.meshFeature.meshInfo} object.

src/feature.js

@@ -33,10 +33,16 @@ var geo_event = require('./event');
  *   feature within its parent's list of children as the bin number.
  * @property {geo.renderer?} [renderer] A reference to the renderer used for
  *   the feature.
- * @property {object} [style] An object that contains style values for the
- *   feature.
- * @property {number|function} [style.opacity=1] The opacity on a scale of 0 to
- *   1.
+ * @property {geo.feature.styleSpec} [style] An object that contains style
+ *   values for the feature.
+ */
+
+/**
+ * Style specification for a feature.
+ *
+ * @typedef {object} geo.feature.styleSpec
+ * @property {number|function} [opacity=1] The opacity for the whole feature on
+ *    a scale of 0 to 1.
  */
 
 /**
@@ -420,8 +426,8 @@ var feature = function (arg) {
    * has a subfeature style, with `(subfeatureElement, subfeatureIndex,
    * dataElement, dataIndex)`.
    *
-   * See the feature's specification ({@link geo.feature.spec}) for available
-   * styles.
+   * See the <a href="#.styleSpec">style specification
+   * <code>styleSpec</code></a> for available styles.
    *
    * @param {string|object} [arg1] If `undefined`, return the current style
    *    object.  If a string and `arg2` is undefined, return the style