In this page you'll find sort of a tutorial to learn how to use MapFish client widgets and integrate them into a simple HTML document or into a more complex layout using ExtJs

Before You Start

This turorial assumes that you have already installed MapFish. If it isn't the case, go to the installation page and follow the instructions. Once done, you can read on.

Simple HTML Document

Let's start with this file with minimum content. Let's call it simple.html 

<html>
<head>
  <title>MapFish Tutorial - How To Use Widgets</title>
  <link rel="stylesheet" type="text/css" href="/path/to/mfbase/ext/resources/css/ext-all.css" />
   
  <script type="text/javascript" src="/path/to/mfbase/openlayers/lib/OpenLayers.js"></script>
  <script type="text/javascript" src="/path/to/mfbase/ext/adapter/ext/ext-base.js"></script>
  <script type="text/javascript" src="/path/to/mfbase/ext/ext-all-debug.js"></script>

  <script type="text/javascript">
    // Because of a bug in Firefox 2 we need to specify the MapFish base path.
    // See https://bugzilla.mozilla.org/show_bug.cgi?id=351282
    var gMfLocation = "/path/to/mfbase/";
  </script>
  <script type="text/javascript" src="/path/to/mfbase/mapfish/MapFish.js"></script>
  
  <script type="text/javascript">
    Ext.onReady(function() {alert ('ready to continue');});
  </script>
</head>
<body>
  <span></span>
  <div id="myDiv"></div>
  <div id="olmap" style="width: 450px; height: 300px; background-color: #999;"></div>
 </body>
</html>

The first two lines specify the document type.

After the start of html and head comes the includes of Ext styles, OpenLayers javascript API, Ext adapter and ExtJS itself. Then MapFish.js is loaded. In development environnement, it automaticaly loads MapFish widgets and core javascript files. Note that ext-all-debug.js can be replaced by ext-all.js for faster load. Also note that in prodution profile, the administrator of the application will prefer to use the MapFish build script and get one single light file for all javascript code.

Tip : You may have to replace "/path/to/mfbase/" to the appropriate value depending on your installation.

Now we're ready to install an event handler that initializes (runs) our application after the document is fully loaded.

Line 

Ext.onReady(function() {alert ('ready to continue');});

says: When the document is fully loaded, the fonction given in argument will be called. This is the standard Ext way ExtJs.

We'll put our application code there.

In the body tag of the document, we already put two div elements. The one with "olmap" id is where the map will stand.

For those who didn't test the page yet, launching it in a browser should show you a grey box, and an alert message saying "ready to continue".

Adding a map

The next step involves adding a simple OpenLayers map in the page. This will done in the Ext.onReady section so that we are sure that the document is fully loaded. 

    Ext.onReady(function() {
        var map = new OpenLayers.Map($('olmap'));

        var wms = new OpenLayers.Layer.WMS("OpenLayers WMS", 
            "http://labs.metacarta.com/wms/vmap0", {layers: 'basic'}, {buffer: 0});

        map.addLayers([wms]);
        map.addControl(new OpenLayers.Control.LayerSwitcher());
        map.zoomToMaxExtent();
    });

This is a typical usage of OpenLayers. For more information on how to use and manipulate OpenLayers objects, methods and events please refer to the OpenLayers documentation. You'll find also many different ways to use it in MapFish.

Refreshing the page in your browser, you should see a world map with navigation tools in the previous grey box.

Adding a widget

Now that we have a map in our page, we want to add a widget. We propose you to integrate the "shortcuts" widget in the page. This widget's goal is to let the user choose a location in a combobox list to get the map zoomed to this chosen location.

To do that you'll have to add the following code at the end of the onReady callback function, after the zoomToMaxExtent statement. 

        var store = new Ext.data.SimpleStore({
             fields: ['value', 'text', 'bbox'],
             data : [['OC', 'Oceana', new OpenLayers.Bounds(56.0234375, -72.53125, 214.2265625, 32.9375)],
                     ['NA', 'North America', new OpenLayers.Bounds(-186.37890625, -2.21875, -28.17578125, 103.25)],
                     ['SA', 'South America', new OpenLayers.Bounds(-146.828125, -71.828125, 11.375, 33.640625)],
                     ['AF', 'Africa', new OpenLayers.Bounds(-58.9375, -51.7890625, 99.265625, 53.6796875)],
                     ['EU', 'Europe', new OpenLayers.Bounds(-23.078125, 26.2578125, 56.0234375, 78.9921875)],
                     ['AS', 'Asia', new OpenLayers.Bounds(15.59375, -21.90625, 173.796875, 83.5625)]]
         });
     
         var shortcuts = new mapfish.widgets.Shortcuts({
             map: map,
             el: 'myDiv',
             store: store,
             templates: {
                 header: new Ext.Template("Choose a continent in the list"),
                 footer: new Ext.Template("The map will automatically center to this location")
             }
         });
         shortcuts.render();

In this code, we first create a new store to be used by the Ext Combobox. This store is to be understood as a associative array with the name of the location (here continent) and the corresponding geographical extent (given as an OpenLayers Bounds object).

Then, we create a new Shortcuts MapFish widget. We give it some config options so that :

  • it relies on the previously created OpenLayers map object,
  • it will be rendered in the DOM element with 'myDiv' id,
  • it uses the previously created store,
  • some more explanation are given to the user on top and under the combobox.

The last thing we do is calling the render method on the object.

Now as you refresh the page, a new element should show up with the list of continents to zoom to.

Complex layout

Let's continue with some basics on how to integrate those widgets into a more fancy layout. We'll start with a set of windows.

I first propose you copy the simple.html file and create a new window.html.

To begin, you'll have to add the following code in the script tag : 

        var mapcomponent = new mapfish.widgets.MapComponent({map: map});
       
        var window = new Ext.Window({
            title: 'Map',
            width: 500,
            height: 300,
            minWidth: 300,
            minHeight: 200,
            layout: 'fit',
            plain: true,
            bodyStyle: 'padding: 5px;',
            items: mapcomponent
        });
        window.show();

Three different things to notice in this code.

  • we create a new MapComponent widget. This widget is compulsory if you want to use the ext layout system with resizable blocks. Indeed, the MapComponent widget will correctly handle the resize events. The MapComponent should at least be given one "map" option property which value is the OpenLayers map.
  • the second part concerns a window object. This is one of the several types of elements that can be used to build a layout for a fancy application. Many options can be given to this object but the most important one is 'items'. For more information, please refer to the ext documentation.
  • then we call the show method on the window object.

If you refresh the page in your browser, you should now see the map in a draggable and resizable window.

Tip: there are many other ways to work with complex layouts. You'll find other examples in MapFishSample.

You can also get the shortcuts rendered in a window. To do that, you'll have to remove some lines in the existing code.

  • remove the "el" option in the ShortCuts constructor, (line 36)
  • remove the shortcuts.render() (line 43). In fact, the shortcuts templates and combobox will be lazy rendered by the window container.

Then add the following code : 

        var window = new Ext.Window({
            title: 'Shortcuts',
            width: 200,
            height: 100,
            minWidth: 200,
            minHeight: 100,
            layout: 'fit',
            plain: true,
            bodyStyle: 'padding: 5px;',
            items: shortcuts
        });
        window.setPagePosition(20, 40);

        window.show();

Try it in you browser.

Attachments