SMap

Introduction
The sMap component is used to display cartographic information related to a record. The cartographic information comes from a GIS shape file. This shape file is compressed by the ClearMaps Builder Air application. The generated map file is then loaded by this component.

A record that is related to such a GIS map file is normally represented by a feature within the map. Multiple features can belong to that map, and each feature can represent different records. Each feature can be selectable and clickable.

Generating GIS Maps
GIS ShapeFiles can be generated from any GIS software. A good opensource GIS software is Quantum GIS. Once the GIS file is created with all the features, it can be converted into a ".map" file that is then used by the sMap component. This map is created by ClearMaps Builder Air application.

Finally, to trigger the use of the sMap, a record has to be described using the predicate/attribute of the input schema that is described as &lt;displayControl&gt;sMap&lt;/displayControl&gt;, and that has the URL of the file of the map representation as its record value.

Each shapefile that is converted should have a EXTURI column in its related dBase data file. The value of this attribute is the "extension" part of the URI of a record (what get appended to the base URI when building the URIs of the records of a OSF Web Service instance). When this EXTURI is appended to the recordBaseUri setting of the sMap component, this creates the full URI of the record. Since all features of a map should be a record in a dataset, it is why we re-create a URI reference for each feature. However, some times there will not be a record description for some feature. In those cases, you should leave an empty value for that feature row in the dBase file of the map.

Each shapefile should have a PREFLABEL column, this is the value that the sMap control uses to display tooltips when the mouse is moved above any feature.

Features
The GIS file is normally related to a row/column data structure where each row is a feature, and each column an attribute describing a feature. This data model is embedded in the GIS shape file, and converted (and manipulable) by the ClearMaps Builder Air application. This simple data structure is then converted into Flex objects, and each column/value is accessible from the "data" property of a Feature object.

Take a look at how the Portable Control Application implements the events. Use that data structure as guidance to perform different actions when a user interacts with the map.

Important Predicates
Some predicates/attributes describing a record are important for this map component. This is a list of those important predicates and their usage in the context of the sMap component.

Interacting with the sMap Control
There are two ways to interact with a sMap control: when a feature is selected in the layout, and when the mouse moves over or away from a feature. These events are represented by:


 * FeatureEvent.FEATURE_SELECTED
 * FeatureEvent.FEATURE_OVER
 * FeatureEvent.FEATURE_OUT

These events are bubbling, so the parent component(s) can attach to these events to do something particular depending what the user does.

MXML Usage Examples
In this example, we assume that the  variable is a , where the record description is defined, accessible at the creation time of the sMap. We also consider that the  variable is an array of at least one attribute that is defined to be a   "sMap" in the schema used by the application.

Related Libraries
This tool is based on the ClearMaps Flex mapping project. It has been enhanced for some special purposes of the OSF Widget, but the basis of this component is based on the ClearMap application.

It also uses the ClearMap Air application that creates the map files used by this component.