Documentation


Tutorials

How to handle multiple layers

In this tutorial we will build a simple application based on a map with two selectable layers (from either shapefiles, PostGIS tables, or both), with buttons to control the visibility of each.

After having performed the basic installation steps described in the Basic Setup section, the next step is to create a mapfile to encapsulate the two layers (please consult the MapServer Mapfile reference for more information, or if this is entirely new to you):

MAP
    EXTENT <minx> <miny> <maxx> <maxy> 
    
    LAYER
        TEMPLATE tmpl
        NAME "region1"
        STATUS off
        TYPE polygon
        DATA "<region1_shapefile>"
        CLASSITEM "<region1_id>"
        TRANSPARENCY 75
        CLASS STYLE OUTLINECOLOR 34 139 34 END END
        CLASS STYLE COLOR 50 150 255 OUTLINECOLOR 34 139 34 END END
    END
    
    LAYER
        TEMPLATE tmpl
        NAME "region2"
        STATUS off
        TYPE polygon
        DATA "<geom_field>; FROM <region2_table> USING UNIQUE <region2_id>"
        CONNECTIONTYPE postgis
        CONNECTION "dbname=<db> host=localhost user=<user>"
        PROCESSING "CLOSE_CONNECTION=DEFER"
        CLASSITEM "<region2_id>"
        TRANSPARENCY 75
        CLASS STYLE OUTLINECOLOR 255 69 0 END END
        CLASS STYLE COLOR 50 150 255 OUTLINECOLOR 255 69 0 END END
    END
END

In this example, the first layer is defined from a shapefile, while the second is built using a PostGIS layer. As it is the case for MapServer itself, this is completely transparent to Dracones, they both work exactly the same. The TEMPLATE attribute is mandatory, while the presence of the CLASSITEM, which must be a valid ID field, implicitly defines these layers as being selectable. The second CLASS attribute specifies the style of the selected regions (in this case, only the COLOR of the selected regions will change, while their OUTLINECOLOR will stay constant).

Finally, the HTML and JavaScript must be modified as well:

<html>
  <head>
    <script type="text/javascript" 
               src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>
    <script type="text/javascript" src="/dracones_core/javascript/jquery.ajaxq-0.0.1.js"></script>
    <script type="text/javascript" src="/dracones_core/javascript/jquery.mousewheel.min.js"></script>
    <script type="text/javascript" src="/dracones_core/javascript/dracones.js"></script>
  </head>
  <body>
    <div id="anchor_div" style="border: 1px solid black; width: 500px; height: 400px"></div>
    <button id="btn1">Toggle Region1 Layer</button>
    <button id="btn2">Toggle Region2 Layer</button>
  </body>
  <script type="text/javascript">
    jQuery(document).ready(function() {

      var map_widget = new dracones.MapWidget({
        anchor_elem: 'anchor_div', 
        app_name: '<app_name>', 
        mid: 'instance1', 
        map: '<mapfile>', 
        init_dlayers: ['<region1>', '<region2>'],
        point_action: 'select',
        point_action_dlayers: ['<region1>', '<region2>'],
        box_action: 'select',
        box_action_dlayers: ['<region1>', '<region2>'] 
      });

      jQuery('#btn1').click(function() { 
        map_widget.toggleDLayers({dlayers: ['region1']});
      });

      jQuery('#btn2').click(function() { 
        map_widget.toggleDLayers({dlayers: ['region2']});
      });

    });
  </script>
</html>

Select Box/Point Actions

The map widget is instantiated as in the previous tutorial, but this time it's initialized with our two region layers (with the init_dlayers parameter). One important addition are the point and box actions. An action is whatever happens when you use the left mouse button while holding CTRL: the point action for CTRL + single click, the box action for CTRL + left drag. For this example, both are set to "select", meaning that corresponding regions from the layers specified by both the point_action_dlayers and box_action_dlayers parameters will be selected, whenever the user performs an "action" with the mouse (i.e. hold CTRL and click or drag). All the visible target layers are thus affected by the selection, meaning that the selected regions from many layers will actually be superimposed.. (hence the use of transparent layers). This is actually better understood "visually", by trying it on the example below!

The action mode and targets can be changed after the widget is initialized, with the dracones.MapWidget.setModeActions method. This is useful if you need to adjust the mouse behavior with external menu or button controls, for instance.

There are only two predefined actions: select and draw. We will see in another tutorial how to create new action types.

We also attach click listeners to two buttons, to enable the toggling of the corresponding layers, through the dracones.MapWidget.toggleDLayers method. When a layer is switched off, it can no longer be selected. Here is an example of the resulting map widget (remember to select regions by holding CTRL):