add support for datum transformations

[jgravois]

this patch uses the shorthand 'transform' as both a setter and constructor option to allow developers to pass the argument through without internal manipulation to ArcGIS Server 10.5+ layers and tasks that support the parameter.

// simple syntax
query.transform(15851);

// JSON syntax
transform({"wkid" : 15851 });

// Well-known text
transform({"wkt" : "GEOGTRAN[\..."});

// composite transformations
var fancy = {
  "geoTransforms": [
    {
      "wkid": "1241",
      "transformForward": false
    },
    {
      "wkid": "15851",
      "transformForward": true
    }
  ]
}
transform(fancy);

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

resolves #973

edit: updated samples to consistently refer to L.esri.Query

[jgravois]

ugh. this service seems to indicate that the parameter name is actually datumTransformation (without an 's')

[jgravois]

i dug (a lot) deeper into this and discovered that we have exposed inconsistent parameter naming and argument syntax between different operations in 10.5.

In the 10.5 services below we use datumTransformations and expect developers to pass transformations in array form, no matter how many are present (ie: [1234]). This is a departure from the syntax we’ve been using in Geometry Service/Project since 10.1.

http://resources.arcgis.com/en/help/arcgis-rest-api/index.html#/Export_Map/02r3000000v7000000/
http://resources.arcgis.com/en/help/arcgis-rest-api/index.html#/Find/02r3000000zm000000/
http://resources.arcgis.com/en/help/arcgis-rest-api/index.html#/Identify_Map_Service/02r300000113000000/

Query (Map Service\Layer) on the other hand is consistent with Geometry Service/Project (available since 10.1) with regard to argument syntax (no array expected, JSON object literal syntax for composite transformations) but lands on datumTransformation (without the ‘s’) instead of just transformation as the honored parameter name.

valid transformed query request / valid transformed find request

i've submitted feedback to the core development team regarding the frustration caused by the inconsistency along with a few suggestions to fix immediate problems in the doc.

because this is just a pet feature of mine anyway, for the time being i'm only going to implement L.esri.query.transform() only and forgo the urge to either:

1. expose the inconsistency above in this API publicly
2. use a kludge internally to avoid it.

[jgravois]

the dev team finally helped me get to the bottom of this. the inconsistency is a result of the fact that Export/Find/Identify all support interacting with multiple input layers published in a single map.

even though Project (and now Query in 10.5) already supported the ability to chain individual transformations together as a composite transformation, the three operations above expect an array so that multiple disparate transformations (either simple or composite) can be passed simultaneously in a request and incorporated into the re-projection of each individual layer!

use case: user publishes a map service which includes one NAD27 layer and one NAD83 layer
and needs to apply two totally different transformations while exporting an image in WGS84 web mercator.