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:

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");