The Map Component

The Map component is the primary interface between the application and the spatial data represented by the map. Most components either display information about the map or allow the user to interact with the map in some way.

The Map component supports the following API:

• loadMap( mapDefinition ) – causes the Map component to load the specified MapDefinition.
• reloadMap() – causes the Map component to reload the current MapDefinition. This is necessary when the map state has changed in certain ways (adding or removing layers in the map, for instance) and is primarily an internal function.
• setExtents( minx, miny, maxx, maxy ) – used to set the map extents to a particular bounding box programmatically.
• drawMap() – used to render a map image and load it in the browser. Normally, this is called automatically as required, but occasionally it may be required to be called programmatically when the state of the map has changed on the server without the knowledge of the Map component.
• query( options ) – used to query the Map in some way and create (or modify) a selection. The options argument is a JavaScript object that can contain the following properties:
  • geometry – a WKT string containing a geometry that defines the spatial area to be queried. The default value is to not limit the query to a spatial extent.
  • maxFeatures – an integer value that determines the maximum number of features to be returned. A value of -1 means all features. The default value is -1.
  • persistent – a boolean value that determines whether the query results should be saved as a visual selection on the map, or not. The default value is true.
  • selectionType – a string value that determines how features are selected with relation to the geometry. The value can be:
    • INTERSECTS – the feature is selected if any part of the geometry and the feature intersect. This is the default value.
    • CONTAINS – the feature is selected if the geometry contains the feature
  • filter – a string value that represents a valid FDO SQL where clause that is used to select features based on attribute values. This may be combined with a geometry value. The default value is no filter.
  • layers – an array of layer names that are to be queried. If no layer names are provided, then all layers will be queried. The default is to query all layers.
  • extendSelection – a boolean value that controls whether the results of this query will be added to the current persistent selection or will replace the current persistent selection.
• getSessionId() – returns the current session ID.
• hasSelection() See Events.
• getSelection( callback ) See Events.
• clearSelection() See Events.

A Map component can have a default MapDefinition that is automatically loaded when the application is loaded. But it is not mandatory to specify a default map. When no default map is specified, the Map component is still initialized. The MapDefinition will then be loaded in response to another component (such as the MapMenu component) or some application-specific code. Regardless of how it happens, when a MapDefinition has been loaded, the Map component will trigger a MAP_LOADED event. Most components are not useful if there is no map loaded, so they use the MAP_LOADED event to determine when they should be enabled. This means that most components will appear initially disabled until the map has been loaded. There are some notable exceptions, including the Map Menu component which is used to provide a drop-down menu of MapDefinitions that the user can pick from.

Once the Map is loaded, the following events may be triggered:

• MAP_SESSION_CREATED. The Map component is responsible for creating and maintaining a session with the server. When the session has been created, this event is triggered. Nothing can happen until this event has been triggered.
• MAP_LOADING. The Map component triggers this event when it is starting to load a new Map. This is primarily used by components to prepare themselves for the new map by discarding their current state and temporarily disabling themselves.
• MAP_LOADED. The Map component triggers this event when a map has been loaded and is ready.
• MAP_EXTENTS_CHANGED. The Map component triggers this event for any navigation that changes the current extents.
• MAP_BUSY_CHANGED. The Map component maintains a reference count of asynchronous events as they start and finish. An application can use this event to display a processing image so that the user is aware that some asynchronous activity is happening.
• MAP_RESIZED. The Map component triggers this event when the size of the map is changed.
• MAP_SELECTION_ON. The Map component triggers this event when a new selection has been created.
• MAP_SELECTION_OFF. The Map component triggers this event when the current selection has been cleared.
• MAP_ACTIVE_LAYER_CHANGED. The Map component allows for a single layer to be marked as active by the application. This event is triggered when the active layer is changed.
• MAP_GENERIC_EVENT. Most components rely directly on their Map component for everything. In some cases, though, components need to be informed of changes in other components. In these cases, the Map component can act as a broker for events through the MAP_GENERIC_EVENT. Components that employ the MAP_GENERIC_EVENT normally do so for a specific internal purpose, and the application should not normally register for this event.