support support for datum transformations

ArcGIS Server 10.5 introduced support for passing datum transformations to a variety of operations. this patch uses the shorthand 'transform' as both a setter and constructor option to allow developers to pass the argument through without internal manipulation.

Map service:
  *   [/export](http://resources.arcgis.com/en/help/arcgis-rest-api/index.html#/Export_Map/02r3000000v7000000/)
  *   /find
  *   /identify

Map service layers
  * /query

valid syntax
// simple syntax
15851

// JSON syntax
{"wkid" : 15851 }

// Well-known text
{"wkt" : "GEOGTRAN[\..."}

// composite transformations
{
  "geoTransforms": [
    {
      "wkid": "1241",
      "transformForward": false
    },
    {
      "wkid": "15851",
      "transformForward": true
    }
  ]
}

additional doc: http://resources.arcgis.com/en/help/arcgis-rest-api/index.html#/Project/02r3000000pv000000/

spec/Tasks/FindSpec.js

@@ -169,6 +169,30 @@ describe('L.esri.Find', function () {
     server.respond();
   });
 
+  it('should pass through a simple datum transformation when finding features', function (done) {
+    server.respondWith('GET', mapServiceUrl + 'find?sr=4326&contains=true&returnGeometry=false&returnZ=true&returnM=false&layers=0&searchText=Site&datumTransformations=1234&f=json', JSON.stringify(sampleResponseWithoutGeometry));
+
+    task.layers('0').text('Site').returnGeometry(false).transform(1234).run(function (error, featureCollection, raw) {
+      expect(featureCollection).to.deep.equal(sampleFeatureCollectionWithoutGeometry);
+      expect(raw).to.deep.equal(sampleResponseWithoutGeometry);
+      done();
+    });
+
+    server.respond();
+  });
+
+  it('should pass through a JSON datum transformation when finding features', function (done) {
+    server.respondWith('GET', mapServiceUrl + 'find?sr=4326&contains=true&returnGeometry=false&returnZ=true&returnM=false&layers=0&searchText=Site&datumTransformations=%7B%22wkid%22%3A1234%7D&f=json', JSON.stringify(sampleResponseWithoutGeometry));
+
+    task.layers('0').text('Site').returnGeometry(false).transform({'wkid': 1234}).run(function (error, featureCollection, raw) {
+      expect(featureCollection).to.deep.equal(sampleFeatureCollectionWithoutGeometry);
+      expect(raw).to.deep.equal(sampleResponseWithoutGeometry);
+      done();
+    });
+
+    server.respond();
+  });
+
   it('should identify features with a token', function (done) {
     server.respondWith('GET', mapServiceUrl + 'find?sr=4326&contains=true&returnGeometry=true&returnZ=true&returnM=false&layers=0&searchText=Site&token=foo&f=json', JSON.stringify(sampleResponse));
 

spec/Tasks/IdentifyFeaturesSpec.js

@@ -191,6 +191,30 @@ describe('L.esri.IdentifyFeatures', function () {
     request.respond(200, { 'Content-Type': 'text/plain; charset=utf-8' }, JSON.stringify(sampleResponse));
   });
 
+  it('should pass through a simple datum transformation when identifying features', function (done) {
+    var request = task.transform(1234).run(function (error, featureCollection, raw) {
+      expect(featureCollection).to.deep.equal(sampleFeatureCollection);
+      expect(raw).to.deep.equal(sampleResponse);
+      done();
+    });
+
+    expect(request.url).to.contain('datumTransformations=1234');
+
+    request.respond(200, { 'Content-Type': 'text/plain; charset=utf-8' }, JSON.stringify(sampleResponse));
+  });
+
+  it('should pass through a JSON datum transformation when identifying features', function (done) {
+    var request = task.transform({'wkid': 1234}).run(function (error, featureCollection, raw) {
+      expect(featureCollection).to.deep.equal(sampleFeatureCollection);
+      expect(raw).to.deep.equal(sampleResponse);
+      done();
+    });
+
+    expect(request.url).to.contain('datumTransformations=%7B%22wkid%22%3A1234%7D');
+
+    request.respond(200, { 'Content-Type': 'text/plain; charset=utf-8' }, JSON.stringify(sampleResponse));
+  });
+
   it('should identify features within a certain pixel tolerance', function (done) {
     var request = task.tolerance(4).run(function (error, featureCollection, raw) {
       expect(featureCollection).to.deep.equal(sampleFeatureCollection);

spec/Tasks/QuerySpec.js

@@ -716,6 +716,34 @@ describe('L.esri.Query', function () {
     server.respond();
   });
 
+  it('should pass through a simple datum transformation when making a query', function (done) {
+    server.respondWith('GET', mapServiceUrl + '0/query?returnGeometry=true&where=1%3D1&outSr=4326&outFields=*&datumTransformations=1234&f=json', JSON.stringify(sampleMapServiceQueryResponse));
+
+    var service = new L.esri.MapService({url: mapServiceUrl});
+
+    service.query().layer(0).transform(1234).run(function (error, featureCollection, raw) {
+      expect(featureCollection).to.deep.equal(sampleMapServiceCollection);
+      expect(raw).to.deep.equal(sampleMapServiceQueryResponse);
+      done();
+    });
+
+    server.respond();
+  });
+
+  it('should pass through a JSON datum transformation when making a query', function (done) {
+    server.respondWith('GET', mapServiceUrl + '0/query?returnGeometry=true&where=1%3D1&outSr=4326&outFields=*&datumTransformations=%7B%22wkid%22%3A1234%7D&f=json', JSON.stringify(sampleMapServiceQueryResponse));
+
+    var service = new L.esri.MapService({url: mapServiceUrl});
+
+    service.query().layer(0).transform({'wkid': 1234}).run(function (error, featureCollection, raw) {
+      expect(featureCollection).to.deep.equal(sampleMapServiceCollection);
+      expect(raw).to.deep.equal(sampleMapServiceQueryResponse);
+      done();
+    });
+
+    server.respond();
+  });
+
   it('should use a image service to query features', function (done) {
     server.respondWith('GET', imageServiceUrl + 'query?returnGeometry=true&where=1%3D1&outSr=4326&outFields=*&pixelSize=1%2C1&f=json', JSON.stringify(sampleImageServiceQueryResponse));
 

src/Layers/DynamicMapLayer.js

@@ -67,6 +67,11 @@ export var DynamicMapLayer = RasterLayer.extend({
     return this;
   },
 
+  setTransform: function (datumTransformations) {
+    this.options.transform = datumTransformations;
+    return this;
+  },
+
   query: function () {
     return this.service.query();
   },
@@ -138,6 +143,10 @@ export var DynamicMapLayer = RasterLayer.extend({
       params.time = this.options.from.valueOf() + ',' + this.options.to.valueOf();
     }
 
+    if (this.options.transform) {
+      params.datumTransformations = typeof this.options.transform === 'string' ? this.options.transform : JSON.stringify(this.options.transform);
+    }
+
     if (this.service.options.token) {
       params.token = this.service.options.token;
     }

src/Tasks/Find.js

@@ -17,6 +17,7 @@ export var Find = Task.extend({
     'returnZ': 'returnZ',
     'returnM': 'returnM',
     'gdbVersion': 'gdbVersion',
+    'transform': 'datumTransformations',
     'token': 'token'
   },
 

src/Tasks/IdentifyFeatures.js

@@ -10,7 +10,8 @@ export var IdentifyFeatures = Identify.extend({
     'layers': 'layers',
     'precision': 'geometryPrecision',
     'tolerance': 'tolerance',
-    'returnGeometry': 'returnGeometry'
+    'returnGeometry': 'returnGeometry',
+    'transform': 'datumTransformations'
   },
 
   params: {

src/Tasks/Query.js

@@ -16,6 +16,7 @@ export var Query = Task.extend({
     'precision': 'geometryPrecision',
     'featureIds': 'objectIds',
     'returnGeometry': 'returnGeometry',
+    'transform': 'datumTransformations',
     'token': 'token'
   },