The “Hello, World” of Map4app

The easiest way to start learning about the Map4app API is to see a simple example. The following web page displays a map centered on Milan, Italy:

<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="initial-scale=1.0, user-scalable=no" />
<style type="text/css">
  html { height: 100%; overflow: auto; }
  body { height: 100%; margin: 0px; padding: 0px }
  #map_canvas { height: 100%; }
</style>
<script type="text/javascript" src="http://maps.ubiest.com/map4app/api?client=YOUR-KEY">
</script>
<script type="text/javascript">
  function initialize() {
    var ubiestKey = "YOUR-KEY"; //This key will be provided by UbiEst on purchase
    var latlng = new ubiest.maps.LatLng(45.468940, 9.181030);
    var myOptions = {
      zoom: 8,
      center: latlng,
      mapTypeId: ubiest.maps.MapTypeId.ROADMAP
    };
    var map = new ubiest.maps.Map(document.getElementById("map_canvas"),
        myOptions);
  }

</script>
</head>
<body onload="initialize()">
  <div id="map_canvas" style="width:100%; height:100%"></div>
</body>
</html>

View example (map-simple.htm)

Even in this simple example, there are a few things to note:

  1. We declare the application as HTML5 using the <!DOCTYPE html> declaration.
  2. We include the Maps API JavaScript using a script tag.
  3. We create a div element named “map_canvas” to hold the Map.
  4. We create a JavaScript object literal to hold a number of map properties.
  5. We write a JavaScript function to create a “map” object.
  6. We initialize the map object from the body tag’s onload event.

The main steps are explained below.

Map Options

var myLatlng = new ubiest.maps.LatLng(45.468940, 9.181030);
var myOptions = {
zoom: 8,
center: myLatlng,
mapTypeId: ubiest.maps.MapTypeId.ROADMAP
};

To initialize a Map, we first create a Map options object to contain map initialization variables. This object is not constructed; instead it is created as an object literal. Because we want to center the map on a specific point, we also create a latlng value to hold this location and pass this into the map’s options. For more information on specifiying locations see Latitudes and Longitudes below.

We also set the initial zoom level and mapTypeId to ubiest.maps.MapTypeId.ROADMAP. The following types are supported:

  • ROADMAP displays the normal, default 2D tiles of TeleAtlas.
  • SATELLITE displays photographic tiles.
  • HYBRID displays a mix of photographic tiles and a tile layer for prominent features (mostly city names).

ubiest.maps.Map – the Elementary Object

var map = new ubiest.maps.Map(document.getElementById("map_canvas"), myOptions);

The JavaScript class that represents a map is the Map class. Objects of this class define a single map on a page. (You may create more than one instance of this class – each object will define a separate map on the page.) We create a new instance of this class using the JavaScript new operator.

When you create a new map instance, you specify a <div> HTML element in the page as a container for the map. HTML nodes are children of the JavaScript document object, and we obtain a reference to this element via the document.getElementById() method.

This code defines a variable (named map) and assigns that variable to a new Map object, also passing in options defined within the myOptions object literal. These options will be used to initialize the map’s properties. The function Map() is known as a constructor and its definition is shown below:

Constructor Description
ubiest.maps.Map(mapDiv:Node, opts?:MapOptions) Creates a new map using the passed optional parameters in the opts parameter.

Loading the Map

<body onload="initialize()">

While an HTML page renders, the document object model (DOM) is built out, and any external images and scripts are received and incorporated into the documentobject. To ensure that our map is placed on the page after the page has fully loaded, we only execute the function which constructs the Map object once the <body>element of the HTML page receives an onload event. Doing so avoids unpredictable behavior and gives us more control on how and when the map draws.

The body tag’s onload attribute is an example of an event handler. The Map4app API also provides a set of events that you can handle to determine state changes.

View example (map-simple.htm)

Latitudes and Longitudes

We need a way to refer to locations on the map. The ubiest.maps.LatLng object provides such a mechanism within the Map4app. You construct a LatLng object, passing its parameters in the order { latitude, longitude }

var myLatlng = new ubiest.maps.LatLng(myLatitude, myLongitude)

Note: the process of turning an address into a geographic point is known as geocoding. Geocoding is supported in this release of the Map4app API.

LatLng objects have many uses within the Map4app API. The ubiest.maps.Marker object uses a LatLng in its constructor, for example, and places a marker overlay on the map at the given geographic location.

Zoom Levels

Offering a map of the entire Earth as a single image would either require an immense map, or a small map with very low resolution. As a result, map images within the Map4app API are broken up into map “tiles” and “zoom levels.” At low zoom levels, a small set of map tiles covers a wide area; at higher zoom levels, the tiles are of higher resolution and cover a smaller area.

Markers

Markers identify locations on the map. By default, they use a standard icon, though you can set a custom icon within the marker’s constructor or by calling setIcon() on the marker. The ubiest.maps.Marker constructor takes a single Marker options object literal specifying the initial properties of the marker. The following fields are particularly important and commonly set when constructing your marker:

  • position (required) specifies a LatLng identifying the initial location of the marker.
  • map (optional) specifies the Map object on which to place the marker.

Note that within the Marker constructor, you should specify the map on which to add the marker. If you do not specify this argument, the marker is created but is not attached (or displayed) on the map. You may add the marker later by calling the marker’s setMap() method. To remove a marker, call the setMap() method passing null as the argument.
Markers are designed to be interactive. By default, they receive ‘click’ events, for example, and are often used within event listeners to bring up info windows.
The following example adds a simple marker to a map at Rome, in the center of Italy:

  var myLatlng = new ubiest.maps.LatLng(41.8955, 12.4825);
  var myOptions = {
    zoom: 7,
    center: myLatlng,
    mapTypeId: ubiest.maps.MapTypeId.ROADMAP
  }
  var map = new ubiest.maps.Map(document.getElementById("map_canvas"), myOptions);

  var marker = new ubiest.maps.Marker({
      position: myLatlng,
      map: map,
      title:"Hello World!"
  });

This Marker title will show up as a tooltip.
If you do not wish to pass any Marker options in the marker’s constructor, instead pass an empty object {} in the last argument of the constructor.

View example (marker-simple.htm)

.

 
 
 
This website uses cookies to enhance your experience. This website uses cookies, also third parties cookies, to deliver contents and advertising more relevant to you and your interests.
For more information, or to change your cookie settings, click here.
By closing this banner, scrolling this page or selecting any elements on this page, you agree to their use. OK