maps.xml

Map Configuration: XML tag one-by-one

The maps.xml file contains definitions for all the maps you wish to use in your application's pages. It is important to realize that everything in the XML configurations is case-sensitive, and that the order cannot be changed! We will start by explaining all the tags in the correct order, and then continue by showing an example configuration, taken from the tutorial application of geomajas 1.3.1.

Let us now explain what all the tags mean:

backgroundColor : HTML color code that determines what background color the map has. ie. "#FFFFFF" or "white".
lineSelectStyle : Style to be used when a line geometry is selected on the map. This is needed to make sure that selection is actually seen by the user. It allows for the same elements you would use in defining the styledefinitions for a vector layer. You don't have to use all of the tags below, but it is important to leave empty tags out. In the example above you'll find that only 3 tags are used, the others are left out.
In short, the following tags are allowed:
- fillColor : HTML color code used in filling the geometry. Not very usefull for lines, but often necessary for polygons.
- fillOpacity : Value between 0 and 1 determining the opacity for the geometry's body. For lines, it is recommended to set this to 0.
- strokeColor : HTML color code used in the strokes.
- strokeOpacity : Value between 0 and 1 determining the opacity for the linestrokes.
- strokeWidth : The width in pixels of the linestrokes.
- dashArray : Comma seperated list of numbers used for creating dashes. (ie: 10,5)
pointSelectStyle : See lineSelectStyle. It uses the same sub-tags as the lineSelectStyle.
polygonSelectStyle : See lineSelectStyle. It uses the same sub-tags as the lineSelectStyle.
crs : The coordinate reference system. Expects an EPSG string. i.e. "EPSG:4326" for lon-lat, or "EPSG:900913" for Mercator.
scaleBarEnabled : Enable the scalebar on this map or not: true or false.
panButtonsEnabled : Enable panning buttons on the sides of the map or not: true or false.
overview : If the map you are configuring is an overview map for another map, then fill in the ID of the other map here. Leave empty otherwise.
maximumScale : The maximum allowed scale. It is impossible to zoom in further then this maximum allowed scale. It is expressed in pixels per units. Units are the units of the previously chose CRS. When using Mercator for example these units are meters.
initialBounds : The bounding box used when the map is drawn for the first time. Expressed in units of the chosen CRS. Needs the following 4 attributes: x, y, width, height.
resolutions (optional) : It is possible to insert a fixed number of zooming steps here. These come in the form of the "resolution" tag, in which one fills in a scaling value. This scale is expressed in pixels per unit, like the maximumScale descibed above.
layerConfig : Last but not least, a map needs a series of layers. These layer are defined in separate XML files, but included here. See next paragraph for more details.

The layerConfig

First of all, the layerConfig needs a list of layer definitions to be included. The example above includes 2 layer definitions:

<xi:include href="maps/raster/osm.xml"    />
<xi:include href="maps/belgium/provinces.xml"    />

Those XML files can be found in directories relative to the maps.xml directory. After the layers are included, we still need to declare a viewing order in the map and in the LayerTree (even if you are not using a LayerTree widget in the HTML).

The map order is declared as follows:

<mapOrder>
	<layerRef>osm</layerRef>
	<layerRef>provinces</layerRef>
</mapOrder>

The layerRef tags contain the ID's of the layer definitions that have been previously included. To find out what the ID's are, you have to look in the layer definition's XML files. The order is bottom-up: the first layer will be lowest on the map. The last layer, will be on top.

Then there is the tree structure in the LayerTree. The example shows a very simple structure like this:

<layerTree>
	<label>Layers</label>
	<layerRef>osm</layerRef>
	<layerRef>provinces</layerRef>
</layerTree>

The only difference with the maporder, is that there is an extra label, which is used in the LayerTree widget.

If you wish, it is also possible to add extra nodes in the LayerTree, to group certain layers together. This can be done as follows:

<layerTree>
	<label>Top-level layers</label>
	<layerTreeNode expanded="true">
		<label>Subnode 1</label>
		<layerRef>provinces</layerRef>
	</layerTreeNode>
	<layerTreeNode expanded="false">
		<label>Subnode 2</label>
		<layerRef>osm</layerRef>
	</layerTreeNode>
</layerTree>

This configuration will create a LayerTree with 2 subnodes, each containing 1 layer. The first node will be automatically expanded on startup, while the second will not. Notice that each subnode needs a label again.

Usage in HTML

First of all, the map configuration has an ID ("sampleMap", case-sensitive)! This id is used in the HTML pages, so that geomajas knows which configuration belongs to which MapWidget. So, to include a map with the above configuration in a HTML page, you would use something like this:

<div id="sampleMap" dojoType="geomajas.widget.MapWidget"
         style="width:100%; height:100%;"></div>

Example

Now comes the example configuration, taken from the tutorial application from version 1.3.1.

<map id="sampleMap">
	<backgroundColor>#FFFFFF</backgroundColor>

	<lineSelectStyle>
		<fillOpacity>0</fillOpacity>
		<strokeColor>#FF6600</strokeColor>
		<strokeOpacity>1</strokeOpacity>
	</lineSelectStyle>

	<pointSelectStyle>
	</pointSelectStyle>

	<polygonSelectStyle>
		<fillColor>#FFFF00</fillColor>
		<fillOpacity>0.5</fillOpacity>
	</polygonSelectStyle>

	<crs>EPSG:31300</crs>
	<scaleBarEnabled>false</scaleBarEnabled>
	<panButtonsEnabled>false</panButtonsEnabled>
	<overview    />
	<maximumScale>9.5</maximumScale>
	<initialBounds x="20000" y="35000" width="300000" height="230000"    />

	<layerConfig>
		<xi:include href="maps/raster/osm.xml"    />
		<xi:include href="maps/belgium/provinces.xml"    />

		<mapOrder>
			<layerRef>osm</layerRef>
			<layerRef>provinces</layerRef>
		</mapOrder>

		<layerTree>
			<label>Layers</label>
			<layerRef>osm</layerRef>
			<layerRef>provinces</layerRef>
		</layerTree>

	</layerConfig>

</map>