dbox demo Setup

Author: Ken Boss
Contact: mapserver-users@lists.gis.umn.edu (mailing list)
Revision: 0.10
Last Updated:2006/05/05

Table of Contents

Requirements

The demo requires a functioning mapserver installation (version 4.x or higher), with the ability to run either Perl or Python mapscripts via cgi (for dlegend support).

Installation

The MS4W Distribution

MS4W version 1.5.x or higher is recommended, owing to the inclusion of pre-built support files for python mapscript (requiring Python 2.4.x). Though the necessary files are provided (in /ms4w/Apache/cgi-bin/mapscript/python/mapscript*win32.zip), configuration for your local environment is required. That subject is beyond the scope of this document.

  • Unpack dbox_demo_ms4w.zip in your ms4w installation directory
  • The dlegend component of the demo is configured out-of-the-box to use the Python mapscripts (but depends on your system being properly configured as well).
  • Point your browser to http://localhost/dbox_demo/index.html.
  • See the troubleshooting section below if things don't work as expected.

The *nix Distribution

  • Unpack dbox_demo.tgz somewhere in your web document tree
  • configure the dlegend component (see below)
  • Edit example.html and change settings in the config object toward the top of the file as necessary to reflect your local environment.
  • Edit dbox_demo/itasca.map and change the IMAGEPATH and IMAGEURL values as needed.
  • Point your browser to dbox_demo/index.html.
  • See the troubleshooting section below if things don't work as expected.

dlegend configuration

The dlegend component of the demo consists of three components:

make_dlegend_xml*:
 mapscript that parses the mapfile and constructs an XML legend object
dlegend.js:constructs a legend tree from the XML legend object
get_content():method in utils.js that uses AJAX technologies to request XML output from make_dlegend_xml*

Both Perl and Python versions of the make_dlegend_xml script are provided. Your web server must be preconfigured to run one of these mapscript flavors through CGI.

The itasca.map file used in the demo contains a number of elements in the WEB METADATA section that are referenced by make_dlegend_xml to construct the legend XML data required by dlegend.js. Other applications using dlegend functionality will require such elements as well.

Additional configuration may be required as detailed below:

Perl version

The perl version of the script uses the IO::String module. The module may be pre-installed with your Perl distribution; otherwise you will need to get/install it from CPAN.

  • copy mapscript/make_dlegend_xml.pl to your cgi-bin
  • change the shebang line at the top of the script as necessary (eg., #!/usr/bin/perl)
  • ensure that the config.dlegend_xml_executable setting toward the top of example.html points to the correct name/location.

Note that the script can be run/tested from a command line, like:

perl make_dlegend_xml.pl map=/ms4w/apps/dbox_demo/itasca.map server=localhost

Python version

  • copy both mapscript/make_dlegend_xml.py and mapscript/make_dlegend_xml_cgi.py to your cgi-bin
  • change the shebang line at the top of the script as necessary (eg., #!/usr/bin/python -u)
  • ensure that the config.dlegend_xml_executable setting toward the top of example.html points to make_dlegend_xml_cgi.py in the correct location.

Note that make_dlegend_xml.py can be run/tested from a command line, like:

python make_dlegend_xml.py --map=/ms4w/apps/dbox_demo/itasca.map --server=localhost

Troubleshooting

General tips

  1. dbox interfaces have a tendency to swallow error messages that would be output to the browser window in a more traditional mapserver cgi environment. Map/scalebar/reference map errors can be retrieved in the Mozilla family of browsers as follows:

    • right-click in the page and select View Page Info from the popup menu
    • select the Media tab
    • find an appropriate URL and copy it to the browser address bar
    • load the page and view errors
  2. Watch a javascript console for errors as well.

  3. For demo problems, ensure that settings in the config object toward the top of example.html are correct for the local environment.

dlegend-related javascript errors

  1. Error: uncaught exception: Permission denied to call method XMLHttpRequest.open

    A dlegend initialization error; indicates a problem in the setting for config.dlegend_xml_executable, which must reside on the same server as example.html.

  2. Error: objDomTree has no properties

    Another dlegend initialization error. Implies that dlegend.js has not received the expected XML data from make_dlegend_xml*.

  3. Error: objDomTree.getElements("server")[0] has no properties

    Yet another dlegend initialization error. Implies that dlegend.js has received some data, but not in the expected form.

Bypassing CGI calls to make_dlegend_xml*

If you have configured your environment to run one of the required mapscript flavors, but are having difficulting configuring your web server to run the script via CGI, you can:

  • run the script from a command line
  • redirect the XML output to a file
  • pass that file directly to dlegend.js

In that case, edit example.html, and replace this line:

var legend_xml = get_content(config.dlegend_xml_executable + "?map=" + config.main_mapfile + "&server=" + config.legend_server);

with one like:

var legend_xml = get_content("/path/to/my/output.xml");