Mapbook Reference Guide

The mapbook document is an XML file that is used as the configuration file for a GeoMOOSE application. It configures things such as map sources, layers, services and tools in the application. For an example of a mapbook, please refer to the GeoMOOSE demo and the mapbook.xml file in the conf folder.

This reference guide explains the structure, elements, and attributes of the Mapbook XML tags, and how they effect the user interface. GeoMOOSE version 2.0 looks to extend the capabilities and ease of configuration from GeoMOOSE 1.x series and therefore a new version of the mapbook format was required to support all of those features.

<mapbook>

All version 2.0 mapbooks should express themselves by using the ‘version’ tag. GeoMOOSE will check the version attribute at startup and if the minimum version requirement is not met, GeoMOOSE will alert the user with an error. This makes the version attribute required.

The <mapbook> tag contains 6 child elements. Each of these child elements can have their own child elements and are described below.

  • <configuration> : The <configuration> tag is used to specify user interface startup settings.
  • <map-source> : The <map-source> tag is used to specify a single or collection of layers in GeoMOOSE.
  • <layer-controls> : The <layer-control> tag is used to link a layer control to a service. As of GM2 the only layer control available are popups.
  • <service> : The <service> tag is used to define a service such as select, printing and identify.
  • <catalog> : The <catalog> tag is the layers listing found in the information panel.
  • <toolbar> : The <toolbar> tag is the tools that are displayed on the user interface toolbar.

<configuration>

The configuration tag is used to specify user interface startup settings and other application settings. The configuration tag has <param> children. <param> elements have a simple format, a “name” attribute which specifies the interface setting to change and then CDATA that specifie the values. Here is an example from the GeoMOOSE Demo:

<configuration>
        <param name="mapserver_url">/cgi-bin/mapserv.exe</param>
        <param name="mapfile_root">/ms4w/apps/geomoose2/maps</param>
        <param name="projection">EPSG:26915</param>
        <param name="zoomto['Jump To:']"><![CDATA[
        {
                'Dakota County' : [521238.614537864,4924218.86673578,473921.947801381,4974430.36885032],
                'Parcel Data' : [497205.409367,4923984.423582,477595.805945,4941970.52988],
                'Full State of MN' : [189783.560000,4816309.330000,761653.524114,5472346.500000]
        }
        ]]></param>
        <param name="max_extent">189783.560000,4816309.330000,761653.524114,5472346.500000</param>
        <param name="initial_extent">497205.409367,4923984.423582,477595.805945,4941970.52988</param>
        <param name="layer_controls.up.on">false</param>
        <param name="layer_controls.down.on">false</param>
        <param name="layer_controls.legend.on">false</param>
</configuration>

<map-source>

The map-source tag is used to specify a single or collection of layers in GeoMOOSE. All map-sources have two required attributes: type – The type attribute determines what other children are required and tells GeoMOOSE what type of mapping service with which to communicate. Valid types are:

  • mapserver – This type of layer is meant to communicate with the default mapserver as specified in config.js.

    • <file> - Layers of type ‘mapserver’ require a value <file> child specifying the location of the mapfile on disk. Mapfiles can be specified with relative paths in <file> tags.
  • wms – This type of layer is meant to communicate with Web Mapping Service servers. This is the OGC standard for serving raster images over the web. Many sites deliver WMS services that can be consumed by a GeoMOOSE application. If the type is a WMS data source an optional attribute can also be specified to request the images as tiles. This attribute is tiled=true.

    • <url> - Layers of type ‘wms’ require a <url> child specifying the URL of the WMS.
    • name – This is the name used internally, by GeoMOOSE to refer to the layer. Unlike GeoMOOSE 1.0, the title of the layer displayed in the Catalog is not a one-to-one relationship with the entry in the mapbook. This allows greater flexibility in divorcing the display-order of layers in the map and display order in the catalog.
    • queryable – This is an optional attribute the tells GeoMoose whether a WMS map-source type is queryable. This attribute is only need for WMS map-source types. Valid options are queryable=’true/false’.

All map-source types support two children:

  • <param> – The ‘param’ child will add or change parameters sent over the URL to a <map-source>. This can be necessary to change mime-types for WMS services or pass various miscellaneous settings to a mapserver mapfile. All ‘param’ children have two required attributes:
    • name – This is the name that will be used in the URL.
    • value – This is the value the name will be set to in the URL.
    • <layer> (required) – At least one layer child is required for each map-source. Even if a mapserver-type layer is used where all the layers are set to ‘default’ in the mapfile, it is necessary to create a layer child representing all of the layers. Layer elements have one required attribute, name. For a WMS map-source, this refers to a layer as specified in the GetCapabilities document. For a Mapserver map-source, this refers to the name of a layer in the Mapfile. If a Mapfile has all of the layers set to default or all of the layers should be on or off as a whole, then the ‘name’ should be set to ‘all.’

Examples (more can be found in the GeoMOOSE demo mapbook):

<map-source path="county" type="mapserver">
          <file>./countydata/feedlots.map</file>
          <layer name="all"/>
</map-source>

<map-source name="basemap" type="mapserver">
        <file>./basemap/basemap.map</file>
        <layer name="cities"/>
        <layer name="counties"/>
        <layer name="roads"/>
        <layer name="lakes"/>
        <layer name="streams"/>
        <layer name="ditches"/>
        <layer name="TLGAreaLandmarks"/>
        <layer name="TLGLandmarkPoints"/>
</map-source>

<map-source path="metro" type="wms">
        <url>http://www.datafinder.org:80/wmsconnector/com.esri.wms.Esrimap/MN_MetroGIS_DataFinder_WMS_Water_Resources</url>
        <layer name="stream_net_l"/>
        <param name="TRANSPARENT" value="TRUE"/>
        <param name="FORMAT" value="image/png"/>
</map-source>

<service>

<layer-controls>

<catalog>

The GeoMOOSE Catalog, or Catalog, is the layers listing found in the table of contents on the user interface. The catalog is represented by the <catalog> child inside of the mapbook. The catalog has two types of children:

  • layer – The layer child creates an entry in the catalog for the user to turn on and off layers. The layer child has two required attributes:

  • src – This is attribute tells GeoMOOSE where to find the source for the layer. The source of the layer is the ‘name’ attribute specified in the <map-source> plus a ‘/’ combined with the name attribute of the layer as specified in the <map-source>’s <layer> child. In the examples above, there are two complete paths:

    county/all
    metro/stream_net_1
    

Multiple paths can also be specified to turn on/off multiple layers with a single control. To do this, the paths need to be divided with colons. If both layers in the example above were to be turned on simultaneously the ‘path’ attribute would be specified as follows:

county/all:metro/stream_net_1
  • title – This is the text that will be shown in the Catalog to represent the layers specified in the path attribute.

Layers also have an optional attribute:

  • status – Layers can be turned on by default by setting ‘status’ to ‘on’. This defaults to ‘off’.
  • group – The ‘group’ child creates folders in the catalog. Groups contain layer children and can also contain other groups. Groups have two attributes, both of which are optional:
  • expand – A group can be started as ‘open’ where the contents of the group are listed. The ‘expand’ attribute can either be ‘true’ or ‘false’. This defaults to ‘false’.
  • multiple – While most layers are stacked, there may be a set of layers that should not be stacked on top of each other. The most common example is background layers. In the case of background layers, only one should be selected at a time. To do this in GeoMOOSE, set the group’s ‘multiple’ attribute to ‘false’. This defaults to ‘true’.

<toolbar>

GeoMOOSE now has a better defined toolbar. Just as the catalog and layer definitions have become more separated, so too has the toolbar and service definitions. The toolbar is specified using the <toolbar> child. The <toolbar> child has no attributes and only one kind of child, the <tool> child. <Tool> children has a number of attributes:

  • name – The name is the name for the tool.

  • title - This is the title displayed in the tool bar if the text is shown and in the mouseover popup.

  • type – This attribute determines whether the tool calls an internal function or a service as defined in a ‘service’ child. There are two valid types, ‘internal’ and ‘service.’
    • type = ‘service’ adds an additional required attribute, ‘service’ which is the name of the service specified in the <service> tag.

    • type = ‘internal’ adds an additional required attribute, ‘action’ which is the type of action to be taken current valid values are:
      • zoomin – start the zoomin tool
      • zoomout – start the zoom-out tool
      • pan – start the pan tool
      • previous – step back to the previous extent
      • next – step forward to the next extent if jumped back using the ‘previous’ tool.
      • measure – start the measure length tool.
      • measurearea – start the measure area tool.
      • fullextent – zoom to the predefined initial extent of the map.
      • selectable – This attribute determines whether the tool changes/becomes selected or whether a service is simply called/started.

Specifying Icons for a Tool in the Toolbar

Every tool in the toolbar is given a unique ID that allows it to be referenced in CSS. The icons are all specified as backgrounds in the htdocs/css/user_tools.css file. Editing that will show examples of how to specify the icons for a new tool. This change was made to support the use of CSS sprites to increase the load time of GeoMOOSE.

Here is an example featuring the “Print” tool:

#tool-print {
        width: auto;
        background-position: 2 2;
        background-image: url('../images/toolbar/printer.png');
}

#tool-print .ToolContent {
        display: -moz-inline-box;
        display: inline-block;
        width: auto;
}

#tool-print .ToolText {
        display: block;
        padding-top: 3px;
        padding-right: 3px;

        display: -moz-inline-box;
        display: inline-block;
}