[[PageOutline]]
= Fusion MapServer Tutorial =

== Introduction ==

This tutorial describes 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 map files, 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/]
 * [http://trac.osgeo.org/fusion/attachment/wiki/MapServerTutorialFr/icons-demo.zip?format=raw Icons]

== Installation ==

Installing Fusion is very simple. Of course, this assumes you have a functionnal web server with !MapServer installed. Once you have downloaded Fusion and gmap-ms46, next step is to extract them. In this example, '''/opt/fgs/www/htdocs/''' is the web server's document root.
{{{
$ unzip fusion-1.0.4.zip -d /opt/fgs/www/htdocs/
$ unzip gmap-ms46.zip -d /opt/fgs/www/htdocs/ 
}}} 

Now Fusion and the !MapServer data are installed for the tutorial.

== 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,we will not modify them because the default are 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",
}}}

'''Note: on windows, you need to specify the {{{.exe}}} extension on mapserv, i.e. {{{/cgi-bin/mapserv.exe}}}'''

== 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 [wiki:Widgets/Zoom Zoom In] widget
 * a [wiki:Widgets/Zoom Zoom out] widget
 * a [wiki:Widgets/Pan Pan] widget
 * a [wiki:Widgets/Legend Legend] widget

These widgets must be described in a xml file named ApplicationDefinition. This file describe the configuration of a Fusion application: map file, resources, and [wiki:Widgets widgets]. This file will contain a !MapFile tag for !MapServer and all desired widgets (Widget tag) inside the tag [wiki:ApplicationDefinition/WidgetSet WidgetSet].

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