From 4d31a3ed3a5e5120327337d8f83a85ac5b8e3675 Mon Sep 17 00:00:00 2001
From: Tim Schaub <tim.schaub@gmail.com>
Date: Tue, 28 Feb 2012 05:37:28 -0700
Subject: [PATCH] Method for getting both feature id and data.

Having to call two methods to get complete feature information (id and data) is cumbersome.  The `getFeatureInfo` method returns an object with both feature id and data.
---
 examples/utfgrid.html             | 25 +++++++++++++------------
 examples/utfgrid_twogrids.html    | 17 +++++++++--------
 lib/OpenLayers/Control/UTFGrid.js | 12 ++++++------
 lib/OpenLayers/Layer/UTFGrid.js   | 27 ++++++++++++++++-----------
 lib/OpenLayers/Tile/UTFGrid.js    | 29 ++++++++++++++++++++---------
 tests/Tile/UTFGrid.html           | 19 +++++++++++--------
 6 files changed, 75 insertions(+), 54 deletions(-)

diff --git a/examples/utfgrid.html b/examples/utfgrid.html
index 4f9dd83064..c176c987b3 100644
--- a/examples/utfgrid.html
+++ b/examples/utfgrid.html
@@ -8,8 +8,8 @@
     <link rel="stylesheet" href="style.css" type="text/css">
     <script src="../lib/OpenLayers.js"></script>
     <style>
-        #attrsdiv {
-            float: right;
+        #attrs {
+            height: 1.5em;
         }
         #controlToggle li { list-style: none; }
     </style>
@@ -21,11 +21,11 @@
         <div id="shortdesc">
             This page demonstrates the use of the OpenLayers UTFGrid Controls. 
         </div>
-        <div id="attrsdiv"></div>
         <div id="themap" class="smallmap"></div>
         <p>
             When the selected event is triggered, the underlying feature attributes are shown below.
         </p>
+        <div id="attrs">&nbsp;</div>
         <ul id="controlToggle">
             <li>
                 <input type="radio" name="type" value="move" id="moveHandler" 
@@ -71,20 +71,21 @@
         /*
          * Controls
          */
-        var callback = function(dataLookup) {
+        var callback = function(infoLookup) {
             var msg = "";
-            if (dataLookup) {
-                var data;
-                for (var idx in dataLookup) {
+            if (infoLookup) {
+                var info;
+                for (var idx in infoLookup) {
                     // idx can be used to retrieve layer from map.layers[idx]
-                    data = dataLookup[idx];
-                    if (data) {
-                        msg += "<strong>In 2005, " + data.NAME + " had a population of " +
-                            data.POP2005 + " people.</strong> ";
+                    info = infoLookup[idx];
+                    if (info && info.data) {
+                        msg += "[" + info.id + "] <strong>In 2005, " + 
+                            info.data.NAME + " had a population of " +
+                            info.data.POP2005 + " people.</strong> ";
                     }
                 }
             }
-            document.getElementById("attrsdiv").innerHTML = msg;
+            document.getElementById("attrs").innerHTML = msg;
         };
             
         var controls = {
diff --git a/examples/utfgrid_twogrids.html b/examples/utfgrid_twogrids.html
index 67c1cab660..c0e496bba5 100644
--- a/examples/utfgrid_twogrids.html
+++ b/examples/utfgrid_twogrids.html
@@ -58,17 +58,18 @@
         );
         map.addLayers([bio_utfgrid,world_utfgrid]);
 
-        var callback = function(dataLookup) {
+        var callback = function(infoLookup) {
             var msg = "";
-            if (dataLookup) {
-                var layer, data;
-                for (var idx in dataLookup) {
+            if (infoLookup) {
+                var layer, info;
+                for (var idx in infoLookup) {
                     layer = map.layers[idx];
-                    data = dataLookup[idx];
-                    if (data) {
+                    info = infoLookup[idx];
+                    if (info && info.data) {
                         msg += "<strong>" + layer.name + "</strong><br>";
-                        for (var key in data) {
-                            msg += key + ": " + data[key] + "<br>";
+                        msg += "feature id: " + info.id + "<br>";
+                        for (var key in info.data) {
+                            msg += key + ": " + info.data[key] + "<br>";
                         }
                     }
                 }
diff --git a/lib/OpenLayers/Control/UTFGrid.js b/lib/OpenLayers/Control/UTFGrid.js
index 142b8389f0..f407b1d511 100644
--- a/lib/OpenLayers/Control/UTFGrid.js
+++ b/lib/OpenLayers/Control/UTFGrid.js
@@ -33,7 +33,7 @@
  * var control = new OpenLayers.Control.UTFGrid({
  *     layers: [world_utfgrid],
  *     handlerMode: 'move',
- *     callback: function(dataLookup) {
+ *     callback: function(infoLookup) {
  *         // do something with returned data
  *
  *     }
@@ -175,14 +175,14 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
         
         var layers = this.findLayers();
         if (layers.length > 0) {
-            var dataLookup = {};
+            var infoLookup = {};
             var layer, idx;
             for (var i=0, len=layers.length; i<len; i++) {
                 layer = layers[i];
                 idx = this.map.layers.indexOf(layer);
-                dataLookup[idx] = layer.getFeatureData(lonLat);
+                infoLookup[idx] = layer.getFeatureInfo(lonLat);
             }
-            this.callback(dataLookup); // perhaps pass tile, lonLat?
+            this.callback(infoLookup); // perhaps pass tile, lonLat?
         }
     },
 
@@ -192,12 +192,12 @@ OpenLayers.Control.UTFGrid = OpenLayers.Class(OpenLayers.Control, {
      *     includes data in one of the configured UTFGrid layers.
      *
      * Parameters:
-     * dataLookup - {Object} Keys of this object are layer indexes and can be
+     * infoLookup - {Object} Keys of this object are layer indexes and can be
      *     used to resolve a layer in the map.layers array.  The structure of
      *     the property values depend on the data included in the underlying
      *     UTFGrid and may be any valid JSON type.  
      */
-    callback: function(dataLookup) {
+    callback: function(infoLookup) {
         // to be provided in the constructor
     },
 
diff --git a/lib/OpenLayers/Layer/UTFGrid.js b/lib/OpenLayers/Layer/UTFGrid.js
index 09b4116d49..c37d9b5db6 100644
--- a/lib/OpenLayers/Layer/UTFGrid.js
+++ b/lib/OpenLayers/Layer/UTFGrid.js
@@ -237,22 +237,26 @@ OpenLayers.Layer.UTFGrid = OpenLayers.Class(OpenLayers.Layer.Grid, {
     },
     
     /**
-     * APIProperty: getFeatureData
-     * Get feature data from UTFGrid associated with a map location.
+     * APIProperty: getFeatureInfo
+     * Get details about a feature associated with a map location.  The object
+     *     returned will have id and data properties.  If the given location
+     *     doesn't correspond to a feature, null will be returned.
      *
      * Parameters:
      * location - {<OpenLayers.LonLat>} map location
      *
      * Returns:
-     * {Object} The UTFGrid data corresponding to the given map location.
+     * {Object} Object representing the feature id and UTFGrid data 
+     *     corresponding to the given map location.  Returns null if the given
+     *     location doesn't hit a feature.
      */
-    getFeatureData: function(location) {
-        var data;
-        var info = this.getTileInfo(location);
-        if (info.tile) {
-            data = info.tile.getFeatureData(info.i, info.j);
+    getFeatureInfo: function(location) {
+        var info = null;
+        var tileInfo = this.getTileInfo(location);
+        if (tileInfo.tile) {
+            info = tileInfo.tile.getFeatureInfo(tileInfo.i, tileInfo.j);
         }
-        return data;
+        return info;
     },
 
     /**
@@ -263,10 +267,11 @@ OpenLayers.Layer.UTFGrid = OpenLayers.Class(OpenLayers.Layer.Grid, {
      * location - {<OpenLayers.LonLat>} map location
      *
      * Returns:
-     * {Object} The feature identifier corresponding to the given map location.
+     * {String} The feature identifier corresponding to the given map location.
+     *     Returns null if the location doesn't hit a feature.
      */
     getFeatureId: function(location) {
-        var id;
+        var id = null;
         var info = this.getTileInfo(location);
         if (info.tile) {
             id = info.tile.getFeatureId(info.i, info.j);
diff --git a/lib/OpenLayers/Tile/UTFGrid.js b/lib/OpenLayers/Tile/UTFGrid.js
index 652ee829bd..add5ae392e 100644
--- a/lib/OpenLayers/Tile/UTFGrid.js
+++ b/lib/OpenLayers/Tile/UTFGrid.js
@@ -146,22 +146,29 @@ OpenLayers.Tile.UTFGrid = OpenLayers.Class(OpenLayers.Tile, {
     },
     
     /**
-     * Method: getFeatureData
-     * Get feature data associated with a pixel offset.
+     * Method: getFeatureInfo
+     * Get feature information associated with a pixel offset.  If the pixel
+     *     offset corresponds to a feature, the returned object will have id
+     *     and data properties.  Otherwise, null will be returned.
+     *     
      *
      * Parameters:
      * i - {Number} X-axis pixel offset (from top left of tile)
      * j - {Number} Y-axis pixel offset (from top left of tile)
      *
      * Returns:
-     * {Object} The UTFGrid data corresponding to the given pixel offset.
+     * {Object} Object with feature id and data properties corresponding to the 
+     *     given pixel offset.
      */
-    getFeatureData: function(i, j) {
-        var data;
+    getFeatureInfo: function(i, j) {
+        var info = null;
         if (this.json) {
-            data = this.json.data[this.getFeatureId(i, j)];
+            var id = this.getFeatureId(i, j);
+            if (id !== null) {
+                info = {id: id, data: this.json.data[id]};
+            }
         }
-        return data;
+        return info;
     },
     
     /**
@@ -174,16 +181,20 @@ OpenLayers.Tile.UTFGrid = OpenLayers.Class(OpenLayers.Tile, {
      *
      * Returns:
      * {Object} The feature identifier corresponding to the given pixel offset.
+     *     Returns null if pixel doesn't correspond to a feature.
      */
     getFeatureId: function(i, j) {
-        var id;
+        var id = null;
         if (this.json) {
             var resolution = this.utfgridResolution;
             var row = Math.floor(j / resolution);
             var col = Math.floor(i / resolution);
             var charCode = this.json.grid[row].charCodeAt(col);
             var index = this.indexFromCharCode(charCode);
-            id = this.json.keys[index];
+            var keys = this.json.keys;
+            if (!isNaN(index) && (index in keys)) {
+                id = keys[index];
+            }
         }
         return id;
     },
diff --git a/tests/Tile/UTFGrid.html b/tests/Tile/UTFGrid.html
index 669289b79f..a44ad35634 100644
--- a/tests/Tile/UTFGrid.html
+++ b/tests/Tile/UTFGrid.html
@@ -171,27 +171,30 @@
             t.eq(id, "238", "feature 238 at 16, 60");
             t.eq(tile.getFeatureId(18, 63), id, "same feature at 18, 63");
             
-            t.eq(tile.getFeatureId(300, 10), undefined, "undefined id outside tile");
+            t.eq(tile.getFeatureId(300, 10), null, "null id outside tile");
             
             tearDown();
         });
     }
 
-    function test_getFeatureData(t) {
+    function test_getFeatureInfo(t) {
         t.plan(3);
         setUp();
         
         var tile = layer.grid[1][1];
         t.delay_call(0.5, function() {
-            var data = tile.getFeatureData(16, 60);
+            var info = tile.getFeatureInfo(16, 60);
             var exp = {
-                NAME: "Svalbard",
-                POP2005: 0
+                id: "238",
+                data: {
+                    NAME: "Svalbard",
+                    POP2005: 0
+                }
             };
-            t.eq(data, exp, "feature data at 16, 60");
-            t.eq(tile.getFeatureData(17, 62), exp, "same feature at 17, 62");
+            t.eq(info, exp, "feature info at 16, 60");
+            t.eq(tile.getFeatureInfo(17, 62), exp, "same feature at 17, 62");
 
-            t.eq(tile.getFeatureData(300, 10), undefined, "undefined data outside tile");
+            t.eq(tile.getFeatureInfo(300, 10), null, "undefined outside tile");
 
             tearDown();
         });