Autocasting

Autocasting is a convenient way to set typed properties without referencing extra API modules via the require() function. Developers can pass constructor parameters directly to the desired property and the API will instantiate the object with the provided constructor parameters internally, making the process simpler for the developer.

Let's take a look at some typical code to create a renderer. Notice that five modules are needed to create a SimpleRenderer for a FeatureLayer containing point data.

require([
  "esri/Color",
  "esri/symbols/SimpleLineSymbol",
  "esri/symbols/SimpleMarkerSymbol",
  "esri/renderers/SimpleRenderer",
  "esri/layers/FeatureLayer",
], function (
  Color, SimpleLineSymbol, SimpleMarkerSymbol, SimpleRenderer, FeatureLayer
) {

  var diamondSymbol = new SimpleMarkerSymbol({
    style: "diamond",
    color: new Color([255, 128, 45]),  // You typically create the instance with the "new" keyword
    outline: new SimpleLineSymbol({    // also here
      style: "dash-dot",
      color: new Color([255, 128, 45]) // and here
    })
  });

  var layer = new FeatureLayer({
    url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/WorldCities/FeatureServer/0",
    renderer: new SimpleRenderer({
      symbol: diamondSymbol
    })
  });
});

From the documentation, we see that the color and outline properties of SimpleMarkerSymbol can be autocast. We also see the same autocast tag on the renderer property of the FeatureLayer and the symbol property of the SimpleRenderer.

Now let's bring autocasting into the picture. Remember, there's no need to require all the modules. We only need to pass constructor parameters directly to the autocast properties:

require([
  "esri/layers/FeatureLayer"
], function (
  FeatureLayer
) {

  var diamondSymbol = {
    type: "simple-marker",  // autocasts as new SimpleMarkerSymbol()
    style: "diamond",
    color: [ 255, 128, 45 ],  // autocasts as new Color()
    outline: {              // autocasts as new SimpleLineSymbol()
      style: "dash-dot",
      color: [ 255, 128, 45 ] // Again, no need for specifying new Color()
    }
  };

  var layer = new FeatureLayer({
    url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/WorldCities/FeatureServer/0",
    renderer: {
      type: "simple",  // autocasts as new SimpleRenderer()
      symbol: diamondSymbol
    }
  });
});

Notice the code is simpler and functionally does the same thing while requiring four fewer modules than the original snippet. The API will take the values you pass in these properties and instantiate the typed objects internally.

Keep in mind there is no need to specify the type on properties where the module type is known, or fixed. For example, look at the outline property in the SimpleMarkerSymbol in the snippet above. You'll notice that it doesn't have a type specified. The type property does not need to be included because only instances of SimpleLineSymbol apply to the outline property.

  var diamondSymbol = {
    type: "simple-marker",
    outline: {
      type: "simple-line",  // Specifying this type is not necessary since `simple-line` is already implied
      style: "dash-dot",
      color: [ 255, 128, 45 ]
    }
  };

In cases where the type is more generic, such as FeatureLayer.renderer, then type must always be specified for the autocasting to take effect.

var layer = new FeatureLayer({
  renderer: {
      // What kind of renderer is this? Simple? Class breaks? Unique value?
      // There's no way the API can tell without `type` specifying what it should be.
    defaultSymbol: diamondSymbol
  }
});

Supported properties

The value of any property with the following label in the API documentation may be set via autocasting.

Another example

Let's create a Viewpoint by autocasting its typed properties. The camera property of Viewpoint, position property of Camera, and spatialReference property of Point can all be set by autocasting.

require([
  "esri/Viewpoint"
], function(Viewpoint){

  // Viewpoint is the only module that needs to be required
  var viewpt = new Viewpoint({
    camera: {  // autocasts as new Camera()
      heading: 90,
      tilt: 30,
      position: {  // autocasts as new Point()
        x: -9177811,
        y: 4247784,
        z: 50000,
        spatialReference: { wkid: 3857 }  // autocasts as new SpatialReference()
      }
    }
  });
});

Autocasting is a convenience to you as a developer and is designed to simplify your experience with the API.