To see a map on your page, users must have Flash Player 9.0.115 (or later) installed, and they must use the browsers described below:

  • Opera 9 or later
  • FireFox 2 or later
  • Internet Explorer 6 or later
  • Safari 3 or later
  • Google Chrome

Installation

To use Mapia API, just plug the script to the document:

<script src="http://mapia.com.ua/api/0.9.0/mapiaapi.js"></script>

The simplest example of API use

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" style="height:100%;width:100%;margin:0;padding:0;">
    <head>

        <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
        <title>Mapia API</title>
        <script src="/api/0.9.0/mapiaapi.js" type="text/javascript"></script>
        <script>
          var mapia = new Mapia("map");
        </script>

    </head>

    <body style="margin:0;padding:0;height:100%;width:100%;overflow:hidden;">
      <span id="map"></span>
    </body>
</html>

Constructor

Mapia(elementId, options)

elementId is DomID of an element, which will be replaced by a Flash object. A flash object will be given with and height, which means that the size and position of a map are set with the size and position of container, where elementId is placed. Example

options are an Object type parameter with the following attributes:
  • zoom is the initial level of the map zooming in. The value is from 6 (out) to 18 (in)
  • center is a point where a map will be centered. It may be either lat and lon attributes object, where lat is latitude and lon is a longitude, or a line with an address.
  • lang is the language of names to be represented on a map (Ru, Ua)
  • wmode is a parameter to be installed to a Flash object by the putting into a document

Example 1.

var map = new Mapia('mapia', {center:'площадь Победы 1', zoom:15})

Example 2.

var map = new Mapia('mapia', {center:{lat:50.45759, lon:30.38898}, zoom:15})

Methods

getCenter

It returns the coordinates of a map center in object {lat:... , lon:...}. This method will return the null if a map has not been initialized yet

setCenter(latlonOrString)

It sets a map coordinates. It may be latlon object or an address line.

setCity(cityTitle)

It sets a city, on the context of which, the search of the addresses for a marker installation or map centering will be implemented

getZoom

It returns the zoom of a map

setZoom(number)

It sets the zoom of a map. The possible numbers are from 6 to 18.

addMarker(markerId, latlonOrString, popupData)

It sets the marker with markerId identifier to the place pointed by coordinates and an address in a second parameter. If this identifier was used by another marker, the marker will not be added. popupData object contains the data, which should be represented by pop-up, may contain the following attributes:

  • title is represented in a prompt by pointing to the marker (required field)
  • icon_url is the URL of a marker icon. If an icon is not placed in mapia.ua, an address should be pointed in full, and on the server there should be a /crossdomain.xml file, which allows the access to mapia.ua domain (required field)
  • nopopuptrue|false. Set true if you do not want the pop-up to be represented by clicking on a marker.
  • custom_content is url *.swf of the file that is a Flex module, which will be installed and represented in pop-up. If it is not pointed, a standard module will be used. More details about the making of the modules of the pop-up content are described below.

All other fields will be passed to a module that represents the pop-up content. For a standard module it is possible to pass the following fields:

  • title is represented with capital letters.
  • category_name is represented in a pop-up above the title.
  • logo is the URL of a logo, 100x100 picture.
  • address is an address.
  • phone is a telephone.
  • url is the addres of a website. The URL should be pointed by all means. For example: http://example.com
  • note is a text represented in a pop-up under an address, telephone and email.
  • description is a text within the pop-up.

Warning!

There are three common mistakes by adding the marker:

  1. icon_url is not pointed or a relative URL is pointed, which is interpreted relative to http://mapia.com.ua/, but not to the URL of a page, in which a map was included;
  2. The unique identifier of a marker is not pointed;
  3. There is no crossdomain.xml file on a server, from which the icon for marker is being downloaded.

    The possible decision of the problem is to place the icons for the markers on own server, and
    to put crossdomain.xml file to the root. For example:

    <?xml version="1.0"?>
    <cross-domain-policy>
    
      <site-control permitted-cross-domain-policies="master-only"/>
      <allow-access-from domain="*" />
    </cross-domain-policy>
      

    The example can always be viewed at: http://mapia.ua/crossdomain.xml

    This only refers to the icons of the markers, and does not refer to logos.

removeMarker(markerId)

It deletes the marker with pointed identifier.

Events

One may subscribe for events on the Mapia class specimen. The processor of events will receive the event argument, in which the target field is the Mapia class specimen, and the type is the event that has occurred. Other fields depend on evens that has occurred.

Example of fields use

var i = 0;
var mapia = new Mapia('mapia');
mapia.addEventListener('mapClick', function(event){
  event.target.addMarker((i++).toString(), event.loc, {title:i.toString(), icon_url:'http://example.com/icons/'+i.toString()+'.png'})
});

initialized

It occurs when the Flash object of Mapia is created, installed and ready to execute commands of Mapia API. All the methods of the Mapia class specimen, which were called before this event, are formed in a queue, and implemented just before this event

zoomChanged

It occurs when zoom has been changed. The event parameter contains the additional zoom

field

centerChanged

It occurs when the center of the map has been changed. The event parameter contains the additional center

field

mapClick

It occurs when the center of a map has been changed. The event parameter contains the additional loc field (The point, which was clicked by a user)

markerClick

It occurs when a user clicks on a marker. The event parameter contains the additional fields:

  • markerId is the identifier of a marker
  • loc are the longtitude and latitude of a marker (lat, lon)
  • popupData is data for the marker pop-up

geocodeSuccess-geocodeFailure

When a line instead the LatLon object is used in setCenter and addMarker methods, a search query will be sent to a server for this line. If the address is found, geocodeSuccess will occur, in other case geocodeFailure will occur.

Creation of the module that represents the content of pop-up

The module should implement com.mapia.IPopupContent interface. IPopupContent.swc

Here it is:

public interface IPopupContent
{
  function get popupData():Object;
  function set popupData(value:Object):void;
}

The example of a simple module, by means of which it is possible to point the background color and text:

<?xml version="1.0" encoding="utf-8"?>
<mx:Module xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" implements="ua.mapia.IPopupContent">
    <mx:Script>

        <![CDATA[
            private var _popupData:Object

            [Bindable]
            public function get popupData():Object
            {
                return _popupData;
            }

            public function set popupData(value:Object):void
            {
                _popupData = value;
            }
        ]]>
    </mx:Script>
    <mx:Box backgroundColor="{popupData.bgColor}">
        <mx:Label text="{popupData.title}" color="{popupData.color}" />
    </mx:Box>
</mx:Module>

More detailed information on making and compiling the Flex modules can be read here.

You may optimize your module for using it only in Mapia application, having cut from it all the components, which are presented in Mapia.swf (the size of module may diminish to 30k). To make it, you should use load-externs arguments with our report.xml by compiling.