Skip to content

Latest commit

 

History

History
221 lines (189 loc) · 10.1 KB

README-JSAPI-3.md

File metadata and controls

221 lines (189 loc) · 10.1 KB
Raw

Canvas-Flowmap-Layer for Esri JSAPI v3

Table of Contents

Demos

Developer API

This extends the Esri JSAPI v3 esri/layers/GraphicsLayer. All properties, methods, and events provided by the GraphicsLayer are available in the CanvasFlowmapLayer, with customizations and extentions described below.

Constructor

// an example of constructing a new layer
var canvasFlowmapLayer = new CanvasFlowmapLayer({
  // 1. a required property
  // inform the layer of your unique origin/destination attributes and geometry fields
  originAndDestinationFieldIds: {
    // all kinds of important stuff here...see docs below
  },

  // 2. some optional properties
  pathDisplayMode: 'selection',
  animationStarted: true,
  animationDuration: 2000,
  animationEasingFamily: 'Cubic',
  animationEasingType: 'In'

  // 3. JSAPI GraphicsLayer constructor properties can also be used
  id: 'myCanvasFlowmapLayer',
  visible: true
});

// construct an array of esri/Graphic yourself and add them to the layer
canvasFlowmapLayer.addGraphics([pointGraphic1, pointGraphic2, ..., pointGraphic100]);

// add the layer to your JSAPI map
map.addLayer(canvasFlowmapLayer);

Convenience options available in constructor only:

Property Description
animationDuration See setAnimationDuration() method description below.
animationEasingFamily See setAnimationEasing() method description below.
animationEasingType See setAnimationEasing() method description below.

Properties

Property Description
originAndDestinationFieldIds Required. Object. This object informs the layer of your unique origin and destination attributes (fields). Both origins and destinations need to have their own unique ID attribute and geometry definition. See example below which includes minimum required object properties.
originCircleProperties Optional. Object. This object defines the symbol properties of the origin point as rendered on the canvas.
destinationCircleProperties Optional. Object. This object defines the symbol properties of the destination point as rendered on the canvas.
pathProperties Optional. Object. This object defines the symbol properties of the non-animated Bezier curve that is drawn on the canvas connecting an origin point to a destination point.
animatePathProperties Optional. Object. This defines the symbol properties of the animated Bezier curve that is drawn on the canvas directly on top of the non-animated Bezier curve. See Line Animation info above.
pathDisplayMode Optional. String. Valid values: 'selection' or 'all'. Defaults to 'all'.
wrapAroundCanvas Optional. Boolean. Defaults to true. Ensures that canvas features will be drawn beyond +/-180 longitude.
animationStarted Optional. Boolean. Defaults to false. This can be set during construction, but you should use the playAnimation and stopAnimation methods to control and change animations after layer construction.
originHighlightCircleProperties Optional. Object. This object defines the symbol properties of the origin point as rendered on the canvas when highlighted.
destinationHighlightCircleProperties Optional. Object. This object defines the symbol properties of the destination point as rendered on the canvas when highlighted.

originAndDestinationFieldIds example:

// you must fill in each of these values for these required properties,
// using the schema of your own data
{
  originUniqueIdField: 'start_id',
  originGeometry: {
    x: 'start_longitude',
    y: 'start_latitude',
    spatialReference: {
      wkid: 4326
    }
  },
  destinationUniqueIdField: 'end_id',
  destinationGeometry: {
    x: 'end_lon',
    y: 'end_lat',
    spatialReference: {
      wkid: 4326
    }
  }
}

custom symbology examples:

`destinationCircleProperties` example to set categorical (unique values) symbols for destination circle strokes and fills 
destinationCircleProperties: {
  type: 'uniqueValue',
  field: '<field / column / property name>',
  uniqueValueInfos: [{
    value: '<attribute value A>',
    symbol: {
      globalCompositeOperation: 'destination-over',
      radius: 10,
      fillStyle: 'rgba(87, 216, 255, 0.65)',
      lineWidth: 0.5,
      strokeStyle: 'rgb(61, 225, 255)',
      shadowBlur: 0
    }
  }, {
    value: '<attribute value B>',
    symbol: {
      globalCompositeOperation: 'destination-over',
      radius: 8,
      fillStyle: 'rgba(153, 98, 204, 0.70)',
      lineWidth: 0.5,
      strokeStyle: 'rgb(181, 131, 217)',
      shadowBlur: 0
    }
  }]
}
`pathProperties` example to set a simple (single) symbol for line width and color 
pathProperties: {
  type: 'simple',
  symbol: {
    strokeStyle: 'rgba(207, 241, 17, 0.8)',
    shadowBlur: 1.5,
    lineWidth: 0.5,
    shadowColor: 'rgb(207, 241, 17)',
    lineCap: 'round'
  }
}
`pathProperties` example to set class break symbols for line widths and colors 
pathProperties: {
  type: 'classBreaks',
  field: '<field / column / property name>',
  defaultSymbol: {
    strokeStyle: 'rgba(237, 248, 177, 1)',
    lineWidth: 0.5,
    lineCap: 'round'
  },
  classBreakInfos: [{
    classMinValue: 0,
    classMaxValue: 999999,
    symbol: {
      strokeStyle: 'rgba(237, 248, 177, 1)',
      lineWidth: 0.5,
      lineCap: 'round'
    }
  }, {
    classMinValue: 999999,
    classMaxValue: 4999999,
    symbol: {
      strokeStyle: 'rgba(127, 205, 187, 1)',
      lineWidth: 1.5,
      lineCap: 'round'
    }
  }, {
    classMinValue: 5000000,
    classMaxValue: 10000000,
    symbol: {
      strokeStyle: 'rgba(44, 127, 184, 1)',
      lineWidth: 3,
      lineCap: 'round'
    }
  }]
}

Methods

Method Arguments Description
addGraphics( inputGraphics ) inputGraphics: Array of Esri graphics. This method will prove to be one of your best friends. It is the main "entry point" for adding to the layer the origin-destination graphics you are responsible for creating from your own data source.
selectGraphicsForPathDisplay( selectionGraphics, selectionMode ) selectionGraphics: Array of Esri graphics that were already added to the layer.

selectionMode: String. Valid values: 'SELECTION_NEW', 'SELECTION_ADD', or 'SELECTION_SUBTRACT'.		 This informs the layer which Bezier curves should be drawn on the map.

For example, you can most easily use this in conjunction with a click or mouse-over event listener.
selectGraphicsForPathDisplayById( uniqueOriginOrDestinationIdField, idValue, originBoolean, selectionMode ) This is a convenience method if the unique origin or destination value is already known and you do not wish to rely on a click or mouse-over event listener.
clearAllPathSelections() This informs the layer to unselect (and thus hide) all Bezier curves.
playAnimation() This starts and shows Bezier curve animations.
stopAnimation() This stops and hides any Bezier curve animations.
setAnimationDuration( duration ) duration: Optional. Number in milliseconds. This changes the animation duration.
setAnimationEasing( easingFamily, easingType ) easingFamily: String.

easingType: String.

See getAnimationEasingOptions() method for info on valid values.		 This changes the animation easing function with the help of the tween.js library.
getAnimationEasingOptions() Returns information on valid easingFamily and easingType values based on the tween.js library.
selectGraphicsForHighlight( selectionGraphics, selectionMode ) selectionGraphics: Array of Esri graphics that were already added to the layer.

selectionMode: String. Valid values: 'SELECTION_NEW', 'SELECTION_ADD', or 'SELECTION_SUBTRACT'.		 This informs the layer which origin/destination points should be "highlighted" when drawn on the map, which just applies the highlight symbology instead of the default symbology to the points.

For example, you can most easily use this in conjunction with a click or mouse-over event listener.
clearAllHighlightSelections() This informs the layer to "un-highlight" (and thus remove highlight symbology) all Bezier curves.

Events

Event Description
click Extends GraphicsLayer click and adds the following properties to the event object:

isOriginGraphic: true if an origin graphic has been clicked, but false if a destination graphic has been clicked.

sharedOriginGraphics: Array of Esri graphics that share the same origin.

sharedDestinationGraphics: Array of Esri graphics that share the same destination.
mouse-over Extends GraphicsLayer mouse-over and adds the following properties to the event object:

isOriginGraphic: true when the mouse first entered an origin graphic, but false when the mouse first entered a destination graphic.

sharedOriginGraphics: Array of Esri graphics that share the same origin.

sharedDestinationGraphics: Array of Esri graphics that share the same destination.