Open Source GIS Conference 2004 & Second Annual MapServer User Meeting
Enhancing the MapServer User Interface with jBox and dBox Workshop
June 10, 2004 1:00 - 2:30 PM
Steve Lime and Rich Greenwood

1. Why use jBox or dBox
   1. jBox and dBox are user interface enhancement components.
   2. What they can do:
      1. Rubberband box for zooming and queries e.g. mode=nquery
      2. Panning - dragging the map image
      3. Coordinate display
      4. Distance measuring
      5. Image swapping
      6. Multiple components on a single page (even mix and match Java/DHTML),
         most other implementations will nott allow that.
      7. Specifically designed for use with MapServer (but not limited to)
   3. Why not to use enhanced interface
      1. Additional complexity of the web page.
      2. Additional requirements on the client computer.
      3. More detailed discussion in "Compatibility Issues" section below.
   4. Other interface enhancements:
      1. Rosa www.maptools.org/rosa/
      2. Jan Hartman's MapClient mapserver.gis.umn.edu/contributed.html
      3. Flash www2.dmsolutions.ca/mapserver/dl/FlashMapserverUserDoc.html
      4. Chameleon www.maptools.org/chameleon
      5. Mapbuilder - A web mapping Javascript library
      6. MapSurfer mapserver.gis.umn.edu/contributed.html
      7. Internet Mapping Framework www.moximedia.com
      8. SVG
         
         
2. About jBox and dBox
   1. Steve Lime wrote both jBox and dBox, both are Open Source.
   2. Where to get:

      jBox	mapserver.gis.umn.edu/contributed.html
      dBox	maps.dnr.state.mn.us/javascript/dbox.js
      jBox HOWTO	mapserver.gis.umn.edu/doc.html

      
      
3. Java, Javascript, and LiveConnect - terminology soup
   1. Java - compiled bytecode, requires that a Virtual Machine (VM) is installed on the client computer.
   2. Javascript - interpreted by browser.
   3. LiveConnect - allows Java and Javascript to call each other's functions. Browser dependent.
   4. dBox only requires Javascript (and DHTML).
      
      
4. Functional Diagram
   
   
5. First hands-on exercises - Standalone jBox, without calls to mapserv CGI
   1. Setting initial parameters basic0.html Source: basic0-src.html
      An absolute minimum static HTML page that loads the applet with a static jpeg image . Initial parameters:
      1. box = on
      2. drag = on
      3. thickness = 5
      4. color = green
         
         
   2. Controlling jBox with Javascript basic1.html Source: basic1-src.html
      Change mode with onClick() Javascript calls. (Optional: change with additional Javascript call, see 2 commented lines)
      
      
   3. Getting information back from jBox basic2.html Source: basic2-src.html
      Get return values from jBox with callback functions.
      1. Mouse screen coordinates (verbose=true)
      2. setbox_handler() - displays returned coordinates in an alert() box.
      
      
6. Second hands-on exercise - Based on Itasca demo, Calls mapserv CGI
   
   
   1. Replace the img tag with the applet demo1.html
      1. Give the Form a name:
             <form name="mapserv" method=GET action="[program]">
      2. Add the imgbox form variable:
             <input type="hidden" name="imgbox" value="-1 -1 -1 -1">
      3. Add Javascript functions to document Head section:
             function setbox_handler(name, minx, miny, maxx, maxy)
             function seterror_handler(message)
      4. Replace the output map image tag with the jBox applet.
         
         
   2. Control the applet's state with onClick events demo2.html
      1. Add the onClick events (bold text below) to the mode radio group.
         <input type="radio" name="mode" value="browse" checked> <b>Browse map</b><br>
         <input type="radio" name="mode" value="query" onClick="document.jBox.boxoff();" > <b>Query feature</b><br>
         <input type="radio" name="mode" value="nquery" onClick="document.jBox.boxon();" > <b>Query multiple features</b>
         
      2. Add the onClick events (bold text below) to the zoomdir radio group.
         <input type=radio name=zoomdir value=1 onClick="document.jBox.boxon();" [zoomdir_1_check]> Zoom In<BR>
         <input type=radio name=zoomdir value=0 onClick="document.jBox.dragon();" [zoomdir_0_check]> Pan<BR>
         <input type=radio name=zoomdir value=-1 onClick="document.jBox.boxoff();" [zoomdir_-1_check]> Zoom Out<BR>
         
         
   3. demo3.html - restoring the mode demo3-edits.html
      
      
7. How to switch to dBox http://maps.dnr.state.mn.us/deli source : demo dBox-src.html
   
   
8. Compatibility issues
   1. Java VM is required, but not always provided with Windows.
   2. Both Java and Javascript must be enabled on client browser (not always the default).
   3. LiveConnect support on Mac is only available on Safari.
   4. PNG support depends on the VM, not the browser. jBoxPNG uses sixlegs (www.sixlegs.com) to provide PNG support for older (Microsoft) VM's.
   5. dBox DHTML requirements:
      1. The dBox.js library
      2. The X cross-browser library from www.cross-browser.com
   6. dBox is known to work on:
      1. Windows: IE 5+, Mozilla, Netscape 6+
      2. Macintosh: Mozilla, IE 5, Safari (v1.2.2 only version tested)
      3. Linux: Mozilla
   7. dBox does not yet support image dragging (panning) or line drawing (measure).
      
      
9. More advanced application examples.
   1. mapserv.js - maps.dnr.state.mn.us/deli
   2. www2.tetonwyo.org/mapserver/