Fusion MapServer Tutorial

Introduction

This tutorial describe how build a web-based mapping application using the Fusion and MapServer. It assumes you are familiar with MapServer and it PHP extension.

Essential Concepts

It is very important that you understand how MapServer works. If you are not familiar with MapServer and creating MapFile, please review the MapServer documentation (​http://mapserver.gis.umn.edu/docs).

Fusion is all about creating a web application. You will need some familiarity with HTML, JavaScript and CSS.

The primary development language for building Fusion applications is JavaScript, but if you need to add server-side functionality using the PHP/MapScript extension of MapServer, then a knowledge of PHP is also required.

Fusion makes extensive use of static and dynamically generated HTML. You need to be familiar with the Document Object Model (DOM) implemented by various browsers, and the subtle differences between the browsers in how scripting with the DOM works. Although it is possible to use Fusion without any DOM scripting, it is likely that most applications will need to use some scripting to achieve their desired functionality.

Fusion makes extensive use of CSS to achieve its look and feel in a minimally intrusive way. The design principle behind much of the structure of the user interface components of Fusion is to let the browser do as much of the work as possible with its native layout engine. This is the most efficient and natural design for web pages, and reduces the amount of javascript code that needs to be executed by the client's browser. You will need to thoroughly understand CSS design and implementation concepts in order to fully customize the Fusion interface, but to use the default look and feel of Fusion with moderate customization does not require advanced CSS knowledge.

Tutorial Prerequisites

• Fusion: http://trac.osgeo.org/fusion/wiki/GetIt
• MapServer gmap-ms46 sample data: ​http://dl.maptools.org/dl/
• Icons

Installation

Installing Fusion is very simple. Off course, i assume you have a functionnal web server with MapServer installed. Once you have downloaded Fusion and gmap-ms46, next step is to extract them. In my example, /opt/fgs/www/htdocs/ is my web folder.

$ unzip fusion-1.0.4.zip -d /opt/fgs/www/htdocs/
$ unzip gmap-ms46.zip -d /opt/fgs/www/htdocs/ 

Fusion and MapServer data are installed for the demo.

Configuration

We will now configure Fusion. There is only one file for the general configuration of Fusion: config.json. In this file, you can modify the script language use by Fusion (only PHP is supported at the moment) and some web paths will depend on the server configuration. For this tutorial, i did not modify because those default was correct. However, you should verify if the web paths for MapServer and the temporary directory are correct. The default directory for temporary files is set to "/tmp". Be sure that your php configuration have the same path. (php5.ini should have a line like: session.save_path = "/tmp")

...
 "mapserver": {
	    /* The URL of the mapserver CGI that you want to use.  */
	    "cgi": "/cgi-bin/mapserv",

Fusion Application

The simplest way to demonstrate the core concepts of Fusion is to build a small, working application. For this demo, we will use the gmap-ms46 sample data. Here is the list of functionality (widgets) used by the application.

• a Map widget
• a Zoom In widget
• a Zoom Out widget
• a Pan widget
• a Legend widget

These widgets must be described in a xml file named ApplicationDefinition. This file describe the configuration of a Fusion application: mapfile, ressource, widgets. This file will contain a MapFile tag for MapServer and all desired widgets (Widget tag) inside the tag WidgetSet (see the ApplicationDefinition page for a more complete description).

First, create a directory for the application and extract the icons downloaded inside this directory. These icons will be used by the widgets.

$ mkdir /opt/fgs/www/htdocs/demo
$ unzip icons-demo.zip -d /opt/fgs/www/htdocs/demo 

Still in this directory, create a new file named ApplicationDefinition.xml and copy the following content inside:

<?xml version="1.0" encoding="UTF-8"?>
<ApplicationDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xsi:noNamespaceSchemaLocation="ApplicationDefinition-1.0.0.xsd">
  <MapSet xsi:type="MapSetType">x
    <MapGroup id="mapserver" xsi:type="MapType">    
      
      <Map xsi:type="MapLayerType">
        <Type>MapServer</Type>
        <SingleTile>true</SingleTile>
        <Extension>
          <MapFile>/opt/fgs/www/htdocs/gmap-ms46/htdocs/gmap75.map</MapFile>
        </Extension>
      </Map>
    
    </MapGroup>
  </MapSet>

  <WidgetSet xsi:type="WidgetSetType">
 
     <MapWidget xsi:type="WidgetType">
      <Name>Map</Name>
      <Type>Map</Type>
      <StatusItem>The map.</StatusItem>
      <MapId>mapserver</MapId>
    </MapWidget>

  <Widget xsi:type="UiWidgetType">
      <Name>Pan</Name>
      <Type>Pan</Type>
      <Description>Drag the map to view areas out of range.</Description>
      <ImageUrl>icons/pan.png</ImageUrl>
      <ImageClass/>
      <Tooltip>Pan mode</Tooltip>
      <Label/>
      <Disabled/>
  </Widget>
  
  <Widget xsi:type="UiWidgetType">
    <Name>ZoomIn</Name>
    <Type>Zoom</Type>
    <Description>Zoom</Description>
    <ImageUrl>icons/zoom-in.png</ImageUrl>
    <ImageClass/>
    <Tooltip>ZoomIn Mode</Tooltip>
    <Label/>
    <Disabled/>
    <Extension xsi:type="CustomContentType">
        <Tolerance>5</Tolerance>
        <Factor>2</Factor>
	</Extension>
  </Widget>

 <Widget xsi:type="UiWidgetType">
    <Name>ZoomOut</Name>
    <Type>Zoom</Type>
    <Description>Zoom</Description>
    <ImageUrl>icons/zoom-out.png</ImageUrl>
    <ImageClass/>
    <Tooltip>ZoomOut Mode</Tooltip>
    <Label/>
    <Disabled/>
    <Extension xsi:type="CustomContentType">
        <Tolerance>5</Tolerance>
        <Factor>2</Factor>
        <Direction>out</Direction>
      </Extension>
  </Widget>
 
  <Widget xsi:type="WidgetType">
    <Name>Legend</Name>
    <Type>Legend</Type>
    <StatusItem/>
  </Widget>
  
  </WidgetSet> 
  <Extension/>
</ApplicationDefinition>

Don't forget to modify the path of the mapfile (MapFile tag). If you check the file, you will notice there is a Widget tag for all functionality with its options. Most of which are not required for this tutorial. Create now a HTML template page named index.html for Fusion.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Fusion MapServer Tutorial</title>
    <script type="text/javascript" src="../fusion/lib/fusion.js"></script>
    <style type="text/css">
      @import url(../fusion/jx/css/jxskin-graphic.css);
      #bodyContent { position:relative; background-color:#dfe9f5; border: thin solid #000000; height:411px; width:760px; margin-top:25px;}
      #Map { position:absolute; top:35px; right:5px; width:439px; height:349px; border: thin solid #000000; float: right; visibility: visible; display:block; }
      #Legend { position:absolute; top:35px; left:5px; width:300px; height:349px; background-color:#ffffff; border: thin solid #000000; overflow-y: auto; overflow-x:hidden; }
      #toolbar { position:absolute; left: 310px; }
    </style>
    <script type="text/javascript">
      window.onload = function() {
         Fusion.initialize();
      }
    </script>
  </head>
  <body>
    <center>
      <div id="bodyContent">
        <div id="toolbar">
          <div id="Pan" ></div>
          <div id="ZoomIn"></div>
          <div id="ZoomOut"></div>
        </div>
        <div id="Legend" align="left"></div>
        <div id="Map"></div> 
      </div>
    </center>
  </body>
</html>

You should now be able to test the application via the web address. In my case: ​http://localhost:8080/demo/index.html