Marker Overlays are objects that are tacked to the map at a single point. As the map zooms in and out, marker overlays stay fixed in size. They are used to mark objects.

Marker Overlays are not instantiated from a class, yet they have the structure of an object. The following shows how a marker overlay is defined. First, a predefined marker provided by Micello:

var namedMarker = {
    "mx": 800,
    "my": 400,
    "lid": 90,
    "mt":micello.maps.markertype.NAMED, // specify marker type as NAMED
    "mr":"RedPin", // the predefiend RedPin
    "idat": "<div>This is custom HTML content!</div>"
}
var aid = namedMarker.aid; // the id assigned to this marker, read below

A pin defined with a custom image:

var tweetMarker = {
    "mx": 550,
    "my": 875,
    "lid": 90,
    "mt": micello.maps.markertype.IMAGE,
    "mr": {"src": "twitter_pin.png"},
    "anm": "tweets", // assign a group name
    "idat": "<div>Tweet Contents!</div>"
}

Location Parameters: The location of a marker can be specified in two ways. An explicit mx,my location and level id can be specified or a geometry ID can be specified over which the marker will be placed.

mx - "map x": This is the X coordinate in map coordinates for the marker overlay.
my - "map y": This is the Y coordinate in map coordinates for the marker overlay.
lid - "level ID": This is the ID of the level on which the marker should be placed.
id - "geometry ID": If the object is placed over a geometry rather than on an explicit coordinate, this value is the ID of the geometry on which the object is placed.
zi - "z index": This is used to give a drawing order for the object.

Marker Specification: The marker can be specified in two ways: NAMED and IMAGE. A named marker can be specified which uses a pin image predefined in the Micello API. Alternatively, an image marker uses a custom image as the marker.

mt - "marker type": This is the type of marker. NAMED or IMAGE.
mr - "marker reference": This is the data that specifies the marker. The format depends on the marker type. If a NAMED marker is being used, then this value should specify which to use. The available markers are:
"RedPin"
"BluePin"
"GreenPin"
"YellowPin"
"RouteStart" - The pin used as the end of a navigation path.
"RouteEnd" - The pin used as the end of a navigation path.
"TrackingDot" - A blue 'gps' style dot.
If the marker type IMAGE is used, the mr value should be an object which defines the image and its offset. Ex. {'src':'pin_image.png','ox':20,'oy':20}. See examples below.

Grouping / Labeling: Marker overlays are referenced either by ID or by group name. These labels can be used to remove markers individually, or by group.

anm - "annotation name": This is used to group a set of marker overlays.
aid - "annotation id": The unique id for this marker, assigned by the API
The .aid property of a marker will be available after the marker has been added to the map by the API. If the marker will need to be individually removed later, this value should be saved for reference.

HTML Data: Marker Overlays can have custom HTML inserted into their popup windows.

idat - The html content to be used inside the marker's popup window.

Adding Marker Overlays by Geometry ID

As a first example a marker overlay will be added to the map by a geometry ID. Finding a geometry ID is covered in the mapClick override example. This example will use community 45 ( The Block, Orange CA ), placing a twitter pin marker on the Dave & Buster's which has a geometry id of 7673.

function tweetMarker () {
    var twitter_pin = {"src": "twitter_pin.png"}; // define image
    var tweetMarker = {
        "id": 3217183, // the geometry id
        "mt": micello.maps.markertype.IMAGE,
        "mr": twitter_pin,
        "anm": "tweets", // part of the group 'tweets'
        "idat": "<div>HTML data!</div>"
    }
    mapDataObject.addMarkerOverlay(tweetMarker); // using a global mapDataObject
}

The result:


Adding marker overlays by geometry id is fairly simple, but using map coordinates is more accurate and flexible. This example won't demonstrate how to find the map coordinates, but a thorough explanation is available in the mapClick override example.

Adding Marker Overlays with Map Coordinates
Below is a marker overlay object whose location is specified by map coordinates. You'll notice that the properties 'lid' (level id), 'mx', and 'my' have been added to provide the marker position rather than a geometry id.

function placeMarker () {
    var thisLevel = mapDataObject.getCurrentLevel(); // get current level object
    var twitter_pin = {"src": "twitter_pin.png", "ox":13, "oy":40}; // define img
    var tweetMarker = {
        "mx": 537,
        "my": 647,
        "lid": thisLevel.id,
        "mt": micello.maps.markertype.IMAGE,
        "mr": twitter_pin,
        "anm": "tweets",
        "idat": "<div>HTML content.</div>"
    }
    mapDataObject.addMarkerOverlay(tweetMarker);
}

Two properties were also added to the object defining the marker image. "ox", the x-offset, and "oy", the y-offset, are used to adjust the position of the image so it indicates an accurate position. In this case the graphic is 40x40px. By viewing it in an image editing program it appears that the tip of the pin is 13px from the left edge.


Positive "ox" values shift the image left while positive "oy" values shift the image up. This image has an "ox" of 13 and an "oy" of 40 to position the tip of the pin at the actual coordinates. Without these values, the upper-left corner of the image would appear at the coordinates and it would appear to move as the zoom level changed.

Adding Markers with Geo Data!
The goal of this tutorial is to enable the developer to integrate real, 3rd-party positioning data with Micello maps. Latitude and Longitude values can easily be converted to map coordinates with the method latLngtoMxy(). Consider the following example that uses lat/lon coordinates to place a marker overlay:

function placeMarker () {
    var thisLevel = mapDataObject.getCurrentLevel(); // get current level object
    var twitter_pin = {"src": "twitter_pin.png", "ox":13, "oy":40}; // define the pin
    var geo_coords = [37.536758026516836, -122.29939760254706]; // lat, lon
    // convert the lat, lon using latLonToMxy()
    var map_coords = mapDataObject.latLonToMxy(geo_coords[0], geo_coords[1]);
    var tweetMarker = {
        "mx": map_coords[0],
        "my": map_coords[1],
        "lid": thisLevel.id,
        "mt": micello.maps.markertype.IMAGE,
        "mr": twitter_pin,
        "anm": "tweets",
        "idat": "<div>HTML data</div>"
    }
    mapDataObject.addMarkerOverlay(tweetMarker);
}

Remember, you'll need a pin image to run this example:

Click the map to see the map coordinates of that point. Click 'Mark It!' to add a marker to that point.