Feature find task

Gruntfile.js

@@ -119,6 +119,7 @@ module.exports = function(grunt) {
           'src/Services/MapService.js',
           'src/Tasks/Identify.js',
           'src/Tasks/Query.js',
+          'src/Tasks/Find.js',
           'src/Layers/DynamicMapLayer',
           'src/Layers/TiledMapLayer'
         ],

karma.conf.js

@@ -34,6 +34,7 @@ module.exports = function(config) {
       'src/Services/MapService.js',
       'src/Tasks/Query.js',
       'src/Tasks/Identify.js',
+      'src/Tasks/Find.js'
     ],
 
     // list of files to exclude

site/source/pages/api-reference/index.hbs

@@ -30,4 +30,5 @@ Wrappers for commonly used API methods on ArcGIS services. Commonly used paramet
 
 * [`L.esri.Tasks.Query`]({{assets}}api-reference/tasks/query.html)
 * [`L.esri.Tasks.Identify`]({{assets}}api-reference/tasks/identify.html)
+* [`L.esri.Tasks.Find`]({{assets}}api-reference/tasks/find.html)
 

site/source/pages/api-reference/layers/dynamic-map-layer.md

@@ -137,7 +137,7 @@ Option | Type | Default | Description
             <td><code>this</code></td>
             <td>
                 Requests metadata about this Feature Layer. Callback will be called with `error` and `metadata`.
-<pre class="js"><code>featureLayer.metadata(function(error, metadata){
+<pre class="js"><code>dynamicMapLayer.metadata(function(error, metadata){
   console.log(metadata);
 });</code></pre>
             </td>
@@ -151,14 +151,27 @@ Option | Type | Default | Description
             <td><code>identify()</code></td>
             <td><code>this</code></td>
             <td>
-                Returns a new <a href=""><code>L.esri.services.Identify</code></a> object that can be used to identify features on this layer. Your callback function will be passed a <a href="http://geojson.org/geojson-spec.html#feature-collection-objects">GeoJSON FeatureCollection</a> with the results or an error.
-<pre class="js"><code>featureLayer.identify()
+                Returns a new <a href="/api-reference/tasks/identify.html"><code>L.esri.services.Identify</code></a> object that can be used to identify features on this layer. Your callback function will be passed a <a href="http://geojson.org/geojson-spec.html#feature-collection-objects">GeoJSON FeatureCollection</a> with the results or an error.
+<pre class="js"><code>dynamicMapLayer.identify()
             .at(latlng, latlngbounds, 5)
             .run(function(error, featureCollection){
               console.log(featureCollection);
             });</code></pre>
             </td>
         </tr>
+        <tr>
+            <td><code>find()</code></td>
+            <td><code>this</code></td>
+            <td>
+                Returns a new <a href="/api-reference/tasks/find.html"><code>L.esri.services.Find</code></a> object that can be used to find features. Your callback function will be passed a <a href="http://geojson.org/geojson-spec.html#feature-collection-objects">GeoJSON FeatureCollection</a> with the results or an error.
+<pre class="js"><code>dynamicMapLayer.find()
+            .layers('18')
+            .searchText('Colorado')
+            .run(function(error, featureCollection){
+              console.log(featureCollection);
+            });</code></pre>
+            </td>
+        </tr>
     </tbody>
 </table>
 

site/source/pages/api-reference/services/map-service.md

@@ -39,13 +39,15 @@ Inherits from [`L.esri.Service`]({{assets}}api-reference/services/service.html)
 | Method | Returns | Description |
 | --- | --- | --- |
 | `identify()` | `this` | Returns a new [`L.esri.Tasks.Identify()`]({{assets}}api-reference/tasks/query.html) object bound to this service. |
+| `find()` | `this` | Returns a new [`L.esri.Tasks.Find()`]({{assets}}api-reference/tasks/find.html) object bound to this service. |
 
 ### Example
 
+#### Identify task
 ```js
 var map = new L.Map('map').setView([ 45.543, -122.621 ], 5);
 
-var service = L.esri.Services.MapService('http://sampleserver6.arcgisonline.com/arcgis/rest/services/WorldTimeZones/MapServer');
+var service = L.esri.Services.mapService('http://sampleserver6.arcgisonline.com/arcgis/rest/services/WorldTimeZones/MapServer');
 
 service.identify()
     .on(map)
@@ -55,3 +57,17 @@ service.identify()
         console.log("UTC Offset: " + featureCollection.features[0].properties.ZONE);
     });
 ```
+
+#### Find task
+
+```js
+var service = L.esri.Services.mapService('http://services.nationalmap.gov/arcgis/rest/services/govunits/MapServer');
+
+service.find()
+    .layers('18')
+    .searchText('Colorado')
+    .searchFields('GNIS_NAME')
+    .run(function(error, featureCollection, response){
+        console.log('Found GNIS ID: ' + featureCollection.features[0].properties.GNIS_ID + ' for the state of ' + featureCollection.features[0].properties.STATE_NAME);
+    });
+```

site/source/pages/api-reference/services/service.md

@@ -73,4 +73,4 @@ A generic class representing a hosted resource on ArcGIS Online or ArcGIS Server
             <td>Authenticates this service with a new token and runs any pending requests that required a token.</td>
         </tr>
     </tbody>
-</table>
+</table>

site/source/pages/api-reference/tasks/find.md

@@ -0,0 +1,149 @@
+---
+title: L.esri.Tasks.Find
+layout: documentation.hbs
+---
+
+# {{page.data.title}}
+
+`L.esri.Tasks.Find` is an abstraction for the find API that exists on Map Services. It provides a chainable API for building request parameters and executing find tasks.
+
+### Constructor
+
+<table>
+    <thead>
+        <tr>
+            <th>Constructor</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>
+                <code class='nobr'>new L.esri.Tasks.Find({{{param 'MapService' 'endpoint' '../../api-reference/services/service.html'}}})</code><br><br>
+                <code>L.esri.Tasks.find({{{param 'MapService' 'endpoint' '../../api-reference/services/service.html'}}})</code><br><br>
+                <code>new L.esri.Tasks.Find({{{param 'String' 'endpoint'}}})</code><br><br>
+                <code>L.esri.Tasks.find({{{param 'String' 'endpoint'}}})</code>
+            </td>
+            <td>The `endpoint` parameter is the service that you want to find either an  ArcGIS Server or ArcGIS Online service. You can also pass the URL to a service directly as a string. See [service URLs](#service-urls) for more information on how to find these URLs.</td>
+        </tr>
+    </tbody>
+</table>
+
+### Methods
+
+<table>
+    <thead>
+        <tr>
+            <th>Method</th>
+            <th>Returns</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td><code>text({{{param 'String' 'text'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Text that is searched across the layers and fields the user specifies.</td>
+        </tr>
+        <tr>
+            <td><code>contains({{{param 'Boolean' 'contains'}}})</code></td>
+            <td><code>this</code></td>
+            <td>When `true` find task will search for a value that contains the `searchText`. When `false` it will do an exact match on the `searchText` string. Default is `true`.</td>
+        </tr>
+        <tr>
+            <td><code>fields({{{param 'Array' 'fields'}}} or {{{param 'String' 'fields'}}})</code></td>
+            <td><code>this</code></td>
+            <td>An array or comma-separated list of field names to search. If not specified, all fields are searched.</td>
+        </tr>
+        <tr>
+            <td><code>spatialReference({{{param 'Integer' 'sr'}}})</code></td>
+            <td><code>this</code></td>
+            <td>The well known ID (ex. 4326) for the results.</td>
+        </tr>
+        <tr>
+            <td><code>layerDef({{{param 'Integer' 'id'}}}, {{{param 'String' 'where'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Add a layer definition to the find task.</td>
+        </tr>
+        <tr>
+            <td><code>layers({{{param 'Array' 'layers'}}} or {{{param 'String' 'layers'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Layers to perform find task on. Accepts an array of layer IDs or comma-separated list.</td>
+        </tr>
+        <tr>
+            <td><code>returnGeometry({{{param 'Boolean' 'returnGeometry'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Return geometry with results. Default is `true`.</td>
+        </tr>
+        <tr>
+            <td><code>maxAllowableOffset({{{param 'Integer' 'maxAllowableOffset'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Specifies the maximum allowable offset to be used for generalizing geometries returned by the `find` task.</td>
+        </tr>
+        <tr>
+            <td><code>precision({{{param 'Integer' 'precision'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Specifies the number of decimal places in returned geometries.</td>
+        </tr>
+        <tr>
+            <td><code>returnZ({{{param 'Boolean' 'returnZ'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Include Z values in the results. Default value is `true`. This parameter only applies if `returnGeometry=true`.</td>
+        </tr>
+        <tr>
+            <td><code>returnM({{{param 'Boolean' 'returnM'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Includes M values if the features have them. Default value is `false`. This parameter only applies if `returnGeometry=true`.</td>
+        </tr>
+        <tr>
+            <td><code>dynamicLayers({{{param 'Object' 'dynamicLayers'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Property used for adding new layers or modifying the data source of existing ones in the current map service.</td>
+        </tr>
+        <tr>
+            <td><code>simplify({{{param 'Map' 'map' 'http://leafletjs.com/reference.html#map'}}},  {{{param 'Integer' 'factor'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Simplify the geometries of the output features for the current map view. the <code>factor</code> parameter controls the amount of simplification between 0 (no simplification) and 1 (simplify to the most basic shape possible).</td>
+        </tr>
+        <tr>
+            <td><code>token({{{param 'String' 'token'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Adds a token to this request if the service requires authentication. Will be added automatically if used with a service.</td>
+        </tr>
+        <tr>
+            <td><code>run({{{param 'Function' 'callback'}}}, {{{param 'Object' 'context'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Exectues the find request with the current parameters, features will be passed to <code>callback</code> as a <a href="http://geojson.org/geojson-spec.html#feature-collection-objects">GeoJSON FeatureCollection</a>. Accepts an optional function context.</td>
+        </tr>
+    </tbody>
+</table>
+
+### Example
+
+##### Finding features
+
+```js
+var find = L.esri.Tasks.find('http://services.nationalmap.gov/arcgis/rest/services/govunits/MapServer');
+
+find.layers('18')
+    .searchText('Colorado');
+
+find.run(function(error, featureCollection, response){
+    console.log('GNIS Name: ' + featureCollection.features[0].properties.GNIS_NAME);
+});
+```
+
+##### Finding features by specified search field name
+
+```js
+var find = L.esri.Tasks.find('http://services.nationalmap.gov/arcgis/rest/services/govunits/MapServer');
+
+find.layers('13')
+    .searchText('198133')
+    .searchFields('GNIS_ID');
+
+find.run(function(error, featureCollection, response){
+    console.log('Found ' + featureCollection.features.length + ' feature(s)');
+    console.log('Found ' + featureCollection.features[0].properties.GNIS_NAME + ' in ' + featureCollection.features[0].properties.STATE_NAME);
+});
+```

site/source/pages/api-reference/tasks/identify.md

@@ -73,6 +73,11 @@ layout: documentation.hbs
             <td><code>this</code></td>
             <td>Buffer the identify area by a given number of screen pixels.</td>
         </tr>
+        <tr>
+            <td><code>returnGeometry({{{param 'Boolean' 'returnGeometry'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Return geometry with results. Default is `true`.</td>
+        </tr>
         <tr>
             <td><code>simplify({{{param 'Map' 'map' 'http://leafletjs.com/reference.html#map'}}},  {{{param 'Integer' 'factor'}}})</code></td>
             <td><code>this</code></td>

site/source/pages/api-reference/tasks/index.md

@@ -8,4 +8,5 @@ layout: documentation.hbs
 Wrappers for commonly used API methods on ArcGIS services. Commonly used parameters to make them more accessible to Leaflet.
 
 * [`L.esri.Tasks.Query`]({{assets}}api-reference/tasks/query.html)
-* [`L.esri.Tasks.Identify`]({{assets}}api-reference/tasks/identify.html)
+* [`L.esri.Tasks.Identify`]({{assets}}api-reference/tasks/identify.html)
+* [`L.esri.Tasks.Find`]({{assets}}api-reference/tasks/find.html)

site/source/pages/api-reference/tasks/query.md

@@ -69,10 +69,15 @@ layout: documentation.hbs
             <td>Queries features within a given time range.</td>
         </tr>
         <tr>
-            <td><code>fields({{{param 'Array' 'fields'}}})</code></td>
+            <td><code>fields({{{param 'Array' 'fields'}}} or {{{param 'String' 'fields'}}})</code></td>
             <td><code>this</code></td>
             <td>An array of associated fields to request for each feature.</td>
         </tr>
+        <tr>
+            <td><code>returnGeometry({{{param 'Boolean' 'returnGeometry'}}})</code></td>
+            <td><code>this</code></td>
+            <td>Return geometry with results. Default is `true`.</td>
+        </tr>
         <tr>
             <td><code>simplify({{{param 'Map' 'map' 'http://leafletjs.com/reference.html#map'}}},  {{{param 'Integer' 'factor'}}})</code></td>
             <td><code>this</code></td>

site/source/pages/api-reference/utils.md

@@ -39,7 +39,7 @@ Utility methods used internally by Esri Leaflet. These methods are useful for co
         <tr>
             <td>responseToFeatureCollection({{{param 'Object' 'response'}}}, {{{param 'String' 'idAttribute'}}})</td>
             <td><code><a href="http://geojson.org/geojson-spec.html#feature-collection-objects">FeatureCollection</a></code></td>
-            <td>Converts an API response (returned by identify and query API methods) to a <a href="http://geojson.org/geojson-spec.html#feature-collection-objects">GeoJSON FeatureCollection</a>. This is used internally by <code><a href="{{assets}}api-reference/tasks/query.html">L.esri.Service.Query</a></code> and <code><a href="{{assets}}api-reference/tasks/identify.html">L.esri.Services.Identify</a></code> to convert responses.</td>
+            <td>Converts an API response (returned by identify, query or find API methods) to a <a href="http://geojson.org/geojson-spec.html#feature-collection-objects">GeoJSON FeatureCollection</a>. This is used internally by <code><a href="{{assets}}api-reference/tasks/query.html">L.esri.Tasks.Query</a></code>, <code><a href="{{assets}}api-reference/tasks/identify.html">L.esri.Tasks.Identify</a></code> and <code><a href="{{assets}}api-reference/tasks/find.html">L.esri.Tasks.Find</a></code> to convert responses.</td>
         </tr>
         <tr>
             <td>cleanUrl({{{param 'String' 'url'}}})</td>

site/source/pages/download/index.md

@@ -55,15 +55,16 @@ A summary of what features exist in which builds.
 
 | Feature | Standard | Core | MapService | FeatureLayer | Basemaps | ClusteredFeatureLayer | HeatmapFeatureLayer |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| Size    | 37.5kb | 7.7kb | 11.8kb | 23kb | 8.3kb | 3.2kb | 1.5kb |
-| Gzipped | 6.38kb | 1.6kb | 2.23kb | 4.3kb | 1.5kb | 0.6kb | 0.3kb |
+| Size    | 38.36kb | 7.56kb | 13.20kb | 23kb | 8.3kb | 3.2kb | 1.5kb |
+| Gzipped | 6.38kb | 1.63kb | 2.33kb | 4.3kb | 1.5kb | 0.6kb | 0.3kb |
 | `L.esri.Request` | ✓ | ✓ | ✓ | ✓ | ✓ | | |
 | `L.esri.Util` | ✓ | ✓ | ✓ | ✓ | | | |
 | `L.esri.Services.Service` | ✓ | ✓ | ✓ | ✓ | | | |
 | `L.esri.Services.MapService` | ✓ | | ✓ | | | | |
 | `L.esri.Services.FeatureLayer` | ✓ | | | ✓ | | | |
 | `L.esri.Tasks.Query` | ✓ | | | ✓ | | | |
 | `L.esri.Tasks.Identify` | ✓ | | ✓ | | | | |
+| `L.esri.Tasks.Find` | ✓ | | ✓ | | | | |
 | `L.esri.Layers.FeatureLayer` | ✓ | | | ✓ | | | |
 | `L.esri.Layers.DynamicMapLayer` | ✓ | | ✓ | | | | |
 | `L.esri.Layers.TiledMapLayer` | ✓ | | ✓ | | | | |

site/source/pages/examples/finding-features.hbs

@@ -0,0 +1,51 @@
+---
+title: Find Features
+description: Find features on a Dynamic Map Layer. More information about Map Services can be found in the <a href="/esri-leaflet/api-reference/layers/dynamic-map-layer.html">L.esri.Layers.DynamicMapLayer</a> documentation.
+layout: example.hbs
+---
+
+<style>
+    #find {
+        position: absolute;
+        top: 10px;
+        right: 10px;
+        z-index: 10;
+        background: white;
+        padding: 1em;
+    }
+</style>
+
+<div id="map"></div>
+
+<div id="find" class="leaflet-bar">
+    <label>
+        Find:
+        <input id="searchText" class="leaflet-bar" />
+    </label>
+    <button id="goBtn" onClick="goBtn()" class="leaflet-bar">Go</button>
+</div>
+<script>
+    var map = L.map('map').setView([39.025, -95.203], 4);
+
+    L.esri.basemapLayer('Gray').addTo(map);
+
+    var govUnits = L.esri.dynamicMapLayer('http://services.nationalmap.gov/arcgis/rest/services/govunits/MapServer', {
+        opacity: 0.9
+    }).addTo(map);
+
+    var searchText = document.getElementById('searchText');
+
+    function goBtn() {
+        govUnits.find().layers('18').text(searchText.value).fields('GNIS_NAME')
+                .run(function(error, featureCollection, response){
+                    L.geoJson(featureCollection, {
+                        style: function () {
+                            return {color: 'blue'};
+                        },
+                        onEachFeature: function (feature, layer) {
+                            layer.bindPopup(feature.properties.GNIS_NAME);
+                        }
+                    }).addTo(map);
+                });
+    }
+</script>