Tutorial. Part 1. Hello World
Please follow the installation instructions here. All tutorial samples are located in the djeo-tutorial directory. Alternatively they can be found in the djeo-tutorial repo.
Let's start from a simple code sample to explain the basic djeo concepts.
The sample code is located in the file helloworld.html.
<html>
<head>
<meta http-equiv="Content-type" content="text/html;charset=UTF-8">
<link rel="stylesheet" href="../dijit/themes/claro/claro.css"/>
<!--
Supported mapping engines (replace the value for the djeoEngine parameter):
Leaflet - djeoEngine: 'leaflet'
Google Maps API - djeoEngine: 'gmaps'
Google Earth API - djeoEngine: 'ge'
ArcGIS API for JavaScript - djeoEngine: 'esri'
Yandex Maps API - djeoEngine: 'ymaps'
-->
<script src="../dojo/dojo.js" data-dojo-config="
djeoEngine: 'leaflet'
"></script>
<script>
var features = [
{
name: "Bermuda triangle",
type: "Polygon",
coords: [ [ [-64.89,32.24], [-80.15,25.7], [-66.07,18.46], [-64.89,32.24] ] ],
style: {
fill: "lime",
fillOpacity: 0.6,
stroke: "green",
strokeWidth: 3
}
},
{
name: "Paris-London railway",
type: "LineString",
coords: [ [2.36,48.88], [3.08,50.64], [1.81,50.90], [0.87,51.14], [-0.13,51.53] ],
style: {
stroke: "red",
strokeWidth: 2
}
},
{
name: "Hello world!",
type: "Point",
coords: [-30, 30],
style: {
size: [49, 60],
img: "http://vvoovv.github.com/ship.png"
}
}
];
require([
"djeo/Map",
"djeo/control/Navigation",
"djeo/control/Highlight",
"djeo/control/Tooltip",
"dojo/domReady!"
],
function(Map, Navigation, Highlight, Tooltip){
var map = new Map("map", {
features: features,
layers: "roadmap"
//layers: "webtiles:http://[a,b,c].tile.cloudmade.com/8ee2a50541944fb9bcedded5165f09d9/1/256"
});
map.ready(function(){
new Navigation(map);
new Highlight(map);
new Tooltip(map);
});
});
</script>
</head>
<body class="claro">
<div id="map" style="width:800px;height:400px;"></div>
</body>
</html>
Open our file helloworld.html in a web browser. You should see something like this:
Try to drag the map, zoom in and zoom out with the mouse wheel. Hover the mouse over Bermuda triangle, Paris-London railway and the image with a boat. You should see highlighting effect and a tooltip.
Our "Hello World!" application employs Leaflet library under the hood. A particular geographical API to be employed is specified in the lines
<script src="../dojo/dojo.js" data-dojo-config="
djeoEngine: 'leaflet'
"></script>
It is the right moment now to demonstrate the key feature of djeo library - the same application code works for different mapping engines. Let's try Google Maps API. Simply set
djeoEngine: 'gmaps'
to utilize Google Maps API and reload the file helloworld.html in the browser. You should see something similar to the screenshot:
Again, test map navigation with dragging and zooming, hover the mouse over Bermuda triangle, Paris-London railway and the image with a boat. You should see the same kind of highlighting effect you have just experienced with the Leaflet engine.
Now let's see how our "Hello World" application works under Google Earth Javascript API. You need to install Google Earth desktop program to enjoy Google Earth in your browser. Simply set
djeoEngine: 'ge'
and reload the file helloworld.html in the browser and see Earth with our map features like in the screenshot:
Test that navigation, highlighting effect and tooltip work the same way as for the Leaflet and Google Maps API engines.
You can try the other supported mapping engines. Just set djeoEngine to 'esri' (ArcGIS API for JavaScript) or 'ymaps' (Yandex Maps API).
We have just seen that the same application code runs under Leaflet, Google Maps API, Google Earth Javascript API, ArcGIS API for JavaScript and Yandex Maps API. Now is the time to study our application code itself. It is worth mentioning that djeo library is based on Dojo Toolkit. So you will often encounter the words dojo and dijit in function calls or file names. Dijit means "dojo widget"; it refers to GUI part of the Dojo Toolkit.
In the line
<link rel="stylesheet" href="../dijit/themes/claro/claro.css"/>
we load css styles used by the tooltip and other dojo GUI components. Dijit contains a number of css themes that define consistent "look and feel" for different GUI components. claro is the name of the most popular dijit theme. If you don't use the djeo tooltip, you may omit that line.
Now let's pay more attention to the lines
<script src="../dojo/dojo.js" data-dojo-config="
djeoEngine: 'leaflet'
"></script>
In the case of the built version of djeo, the file dojo/dojo.js contains basic functionality needed for a typical djeo application. If the path to your application is changed, you need to update the path to dojo/dojo.js accordingly. Here you may pose a question: why is the file called dojo/dojo.js instead of something like djeo/djeo.js. This was done to make the life a bit easier if you become one day an advanced djeo developer. Read a special article about advanced development with djeo.
Then we specify which mapping engine we are going to use in the application by setting the value for djeoEngine attribute. At the moment the possible values for it are: 'leaflet' for the Leaflet library, 'gmaps' for Google Maps API, 'ge' for Google Earth Javascript API, 'esri' for ArcGIS API for JavaScript, 'ymaps' for Yandex Maps API and 'djeo' (the default) for djeo native engine.
Now we are ready to dive into our actual application code.
First, we define map features (Bermuda triangle, Paris-London railway and a point object visualized with a boat image) in the javascript array features:
var features = [
{
name: "Bermuda triangle",
type: "Polygon",
..........
},
{
name: "Paris-London railway",
type: "LineString",
..........
},
{
name: "Hello world!",
type: "Point",
..........
}
];
Unlike other geographical javascript libraries, djeo uses JSON objects to define map features.
To define a polygon it is enough to specify type: "Polygon" and to set its coordinates via coords attribute. Here we would like to emphasize a couple of important points. First, the format for polygon coordinates is
[external_ring, optional_internal_ring, optional_internal_ring, ...],
where each ring is defined as an array of point coordinates:
[[lon1, lat1], [lon2, lat2], ...]
Note that the horizontal coordinate (longitude) precedes the vertical coordinate (latitude). The first and the last points in a ring must be the same.
We specify the name and style attributes for each map feature. The value of the name attribute is used as tooltip content. Style is set inline in our application. It is often desirable to separate feature and style definitions. That separation is considered in the next tutorial. We set the color of the triangle (fill), opacity of the triangle (fillOpacity), the color of the triangle border (stroke) and its width in pixels (strokeWidth).
To define a line string it is enough to specify _type: "LineString" and to set its coordinates via coords attribute. The format for line string coordinates is
[[lon1, lat1], [lon2, lat2], ...]
Note that the horizontal coordinate (longitude) precedes the vertical coordinate (latitude).
We set the color of the line string (stroke) and its width in pixels (strokeWidth).
To define a point map object it is enough to specify type: "Point" and to set its coordinates via coords attribute:
coords: [lon, lat]
Note that the horizontal coordinate (longitude) precedes the vertical coordinate (latitude).
We set the image for the boat (img) and its size in pixels (size). The size attribute is obligatory if you specify an image for a point map object.
If your application code gets large it makes sense to split the code into a number of files (or modules). Each module is responsible for some functionality and can be reused in other applications. The function dojo.require enables you to request a specific module that is actually needed in your application. If do not request the module via dojo.require call its code is not loaded. This is important to remember when you develop applications with djeo library. You always have to request djeo.Map module via the call:
dojo.require("djeo.Map");
It is easy to guess that module djeo.control.Navigation is responsible for map navigation, djeo.control.Highlight is responsible for highlighting effect when you hover the mouse over a map feature, djeo.control.Tooltip is for the tooltip that displays a hint about the map feature.