Autodesk 15606-011408-9330 - MAPGUIDE R6.3 SITE LIC-UPG R6, MapGuide LiteView Developer's Manual

Download

April 2004

Autodesk MapGuide® LiteView

Developer’s Guide

12345678910

This publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose.

AUTODESK, INC., MAKES NO WARRANTY, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS, AND MAKES SUCH MATERIALS AVAILABLE SOLELY ON AN “AS-IS” BASIS.

IN NO EVENT SHALL AUTODESK, INC., BE LIABLE TO ANYONE FOR SPECIAL, COLLATERAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH OR ARISING OUT OF PURCHASE OR USE OF THESE MATERIALS. THE SOLE AND EXCLUSIVE LIABILITY TO AUTODESK, INC., REGARDLESS OF THE FORM OF ACTION, SHALL NOT EXCEED THE PURCHASE PRICE OF THE MATERIALS DESCRIBED HEREIN.

Autodesk, Inc., reserves the right to revise and improve its products as it sees fit. This publication describes the state of this product at the time of its publication, and may not reflect the product at all times in the future.

AUTODESK TRADEMARKS

The following are registered trademarks of Autodesk, Inc., in the USA and/or other countries: 3D Props, 3D Studio, 3D Studio MAX, 3D Studio VIZ, 3DSurfer, ActiveShapes, ActiveShapes (logo), Actrix, ADI, AEC Authority (logo), AEC-X, Animator Pro, Animator Studio, ATC, AUGI, AutoCAD, AutoCAD LT, AutoCAD Map, Autodesk, Autodesk Inventor, Autodesk (logo), Autodesk MapGuide, Autodesk Streamline, Autodesk University (logo), Autodesk View, Autodesk WalkThrough, Autodesk World, AutoLISP, AutoSketch, Biped, bringing information down to earth, CAD Overlay, Character Studio, Cinepak, Cinepak (logo), Codec Central, Combustion, Design Your World, Design Your World (logo), Discreet, EditDV, Education by Design, gmax, Heidi, HOOPS, Hyperwire, i-drop, Inside Track, Kinetix, MaterialSpec, Mechanical Desktop, NAAUG, ObjectARX, PeopleTracker, Physique, Planix, Powered with Autodesk Technology (logo), ProjectPoint, RadioRay, Reactor, Revit, Softdesk, Texture Universe, The AEC Authority, The Auto Architect, VISION*, Visual, Visual Construction, Visual Drainage, Visual Hydro, Visual Landscape, Visual Roads, Visual Survey, Visual Toolbox, Visual TugBoat, Visual LISP, Volo, WHIP!, and WHIP! (logo).

The following are trademarks of Autodesk, Inc., in the USA and/or other countries: 3ds max, AutoCAD Architectural Desktop, AutoCAD Learning Assistance, AutoCAD LT Learning Assistance, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk Envision, Autodesk Map, AutoSnap, AutoTrack, Built with ObjectARX (logo), Burn, Buzzsaw, Buzzsaw.com, Cinestream, Cleaner, Cleaner Central, ClearScale, Colour Warper, Content Explorer, Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignProf, DesignServer, Design Web Format, DWF, DWG Linking, DXF, Extending the Design Team, GDX Driver, gmax (logo), gmax ready (logo),Heads-up Design, IntroDV, jobnet, ObjectDBX, onscreen onair online, Plans & Specs, Plasma, PolarSnap, Real-time Roto, Render Queue, Visual Bridge, Visual Syllabus, and Where Design Connects.

Autodesk Canada Inc. Trademarks

The following are registered trademarks of Autodesk Canada Inc. in the USA and/or Canada, and/or other countries: discreet, fire, flame, flint, flint RT, frost, glass, inferno, MountStone, riot, river, smoke, sparks, stone, stream, vapour, wire.

The following are trademarks of Autodesk Canada Inc., in the USA, Canada, and/or other countries: backburner, backdraft, MultiMaster Editing.

THIRD-PARTY TRADEMARKS

All other brand names, product names, or trademarks belong to their respective holders.

THIRD-PARTY COPYRIGHT NOTICES

GOVERNMENT USE

Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in FAR 12.212 (Commercial Computer Software-Restricted Rights) and DFAR 227.7202 (Rights in Technical Data and Computer Software), as applicable.

iii

Contents

Chapter 1 Introduction . . . . . . . . . . . . . . . . . 1

About This Document . . . . . . . . . . . . . . . . . 2

What You Need to Know . . . . . . . . . . . . . . 2

Conventions . . . . . . . . . . . . . . . . . . 3

Copying Text from This Document . . . . . . . . . . . 3

Overview of Autodesk MapGuide LiteView . . . . . . . . . . 4

Features . . . . . . . . . . . . . . . . . . . . 4

Creating an Autodesk MapGuide LiteView Application. . . . . . . 6

Understanding Application Architecture . . . . . . . . . . . 7

Chapter 2 Understanding Requests . . . . . . . . . . . . . 9

Overview of Requests and Responses . . . . . . . . . . . 10

OpenGIS WMS 1.1.1 Compliance . . . . . . . . . . 10

Non-WMS 1.1.1-Compliant Parameters . . . . . . . . . 10

Creating a map Request . . . . . . . . . . . . . . . 10

Formatting a map Request . . . . . . . . . . . . . 11

Example of a Minimal Map Request . . . . . . . . . . 12

Overview of map Request Parameters . . . . . . . . . 13

Understanding map Request Parameters . . . . . . . . 15

Tips for Creating Map Requests . . . . . . . . . . . 22

Creating a feature_info Request . . . . . . . . . . . . . 22

Example of a feature_info Request . . . . . . . . . . 23

Positioning Feature Information . . . . . . . . . . . 23

Understanding feature_info Request Parameters . . . . . . 24

Interpreting Responses to a feature_info Request. . . . . . . . 26

Sample Response . . . . . . . . . . . . . . . . 27

feature_info Response DTDs . . . . . . . . . . . . 28

Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests . 35

Overview . . . . . . . . . . . . . . . . . . . . 36

GetCapabilities Requests . . . . . . . . . . . . . . . 36

GetCapabilities Request Parameters . . . . . . . . . . 37

GetCapabilities Metadata Response . . . . . . . . . . 37

GetMap Requests. . . . . . . . . . . . . . . . . . 44

GetMap Request Parameters . . . . . . . . . . . . 45

GetFeatureInfo Requests . . . . . . . . . . . . . . . 47

iv | Contents

GetFeatureInfo Request Parameters . . . . . . . . . . 47

Chapter 4 Configuring and Using the Sample Applications . . . . . . 49

The Sample Applications . . . . . . . . . . . . . . . 50

The WMS Viewer Sample Application . . . . . . . . . . . 50

Starting WMS Viewer . . . . . . . . . . . . . . 50

Extending WMS Viewer . . . . . . . . . . . . . . 51

Configuring WMS Viewer . . . . . . . . . . . . . 55

The ColdFusion Sample Application. . . . . . . . . . . . 55

ColdFusion Sample Application Files . . . . . . . . . 56

ColdFusion Sample Application Requirements . . . . . . 57

ColdFusion Sample Application Client Platforms. . . . . . 57

Configuring the ColdFusion Sample Application . . . . . . 58

Starting the ColdFusion Sample Application . . . . . . . 63

Removing the ColdFusion Sample Application Files . . . . . 64

Using the ColdFusion Sample Application . . . . . . . . 64

Troubleshooting and Other Resources . . . . . . . . . . . 77

Displaying Data by Layer . . . . . . . . . . . . . 77

Designing the Recenter Feature . . . . . . . . . . . 78

Accessing the GML DTD While Offline . . . . . . . . . 80

SRS-to-WKT Mapping . . . . . . . . . . . . . . 81

Where to Get More Information . . . . . . . . . . . 82

Index . . . . . . . . . . . . . . . . . . . . . . . . 87

In this chapter

■ About this document

■ Overview of Autodesk

MapGuide LiteView

■ Creating an Autodesk

MapGuide LiteView application

■ Understanding application

architecture

Introduction

Autodesk MapGuide® LiteView is a platform-indepen-

dent viewing solution for Autodesk MapGuide

maps.

Deployed as a Java servlet, Autodesk MapGuide LiteView

serves interactive maps to most browsers—map users

don’t have to download or install a viewer. This chapter

includes general information about this guide and its

audience, an overview of Autodesk MapGuide LiteView

and its architecture, and the general steps you that take to

create an Autodesk MapGuide LiteView application.

2 | Chapter 1 Introduction

About This Document

This guide is written for developers of Web sites that provide access to Autodesk MapGuide maps. It describes Autodesk MapGuide LiteView, the HTTP requests that are the basis of an Autodesk MapGuide LiteView application, and the sample applications that you can use as models for creating your own applications.

For information about installing and configuring Autodesk MapGuide LiteView, see the Autodesk MapGuide LiteView Servlet Administrator’s Guide. To

open that guide from the Windows desktop, choose Start ➤ Programs ➤ Autodesk MapGuide Release 6.5 ➤ LiteView 6.5 ➤ Servlet Administrator’s

Guide.

In this document, Autodesk MapGuide LiteView is assumed to be installed in the default folder, C:\Program Files\Autodesk\MapGuideLiteView6.5\, sometimes abbreviated to <InstallFolder>.

What You Need to Know

To get the most benefit from this guide, and to develop a robust application, you must be proficient in one or more of the following technologies or languages:

■ Active Server Pages (ASP)

■ Java Server Pages (JSP)

■ JavaScript scripting

■ Perl scripting

■ Servlet technology

■ Web-application architecture

■ XML

You don’t need to know the Autodesk MapGuide Viewer API because you do not call its methods to create an Autodesk MapGuide LiteView application.

If you want to use the ColdFusion sample application that’s included with Autodesk MapGuide LiteView, you must be familiar with:

■ Macromedia ColdFusion

■ Apache XML projects such as Xerces XML parser and Xalan XSLT

stylesheet processor. For more information about these see http://www.apache.org.

About This Document | 3

This document assumes that you know how to create maps with Autodesk MapGuide Author and have read the Autodesk MapGuide User’s Guide and Autodesk MapGuide Help.

Conventions

The following syntax-diagram conventions are used in the of Web Map Service (WMS) requests:

Copying Text from This Document

You can copy text from this PDF file and paste it into another application. You may want to copy code samples for use in your own work, for example.

To copy text from a PDF file

1 Click the Text Select tool on the Acrobat Reader toolbar.

2 Drag to select the text you want to copy.

3 Right-click and choose Copy from the shortcut menu.

The text is copied to the Clipboard.

Notations Used in Request Syntax

Notation Description

[ ] The argument or value is optional.

{a|b|c} A list of possibilities.

( ) A grouping. Typically used before an asterisk (*) or a

plus sign (+) to indicate a full subexpression.

* Zero or more occurrences of the previous

subexpression.

+ One or more occurrences of the previous

subexpression.

< > A variable argument or value.

Other notation A literal.

4 | Chapter 1 Introduction

Overview of Autodesk MapGuide LiteView

Autodesk MapGuide LiteView extends the capabilities of Autodesk MapGuide to display maps quickly in a browser without the need for a special plug-in viewer. Autodesk MapGuide LiteView is a servlet—that is, a Java program that runs on a server—that provides lightweight (fast, efficient, and installation-free) viewing.

Autodesk MapGuide LiteView converts MWF files to PNG or JPEG files for display in Microsoft

Internet Explorer, Netscape Navigator, or any browser that supports the PNG or JPEG format. A Web application that sends a request to the Autodesk MapGuide LiteView servlet to convert an MWF file to a PNG or JPEG file receives the converted image in the response.

Autodesk MapGuide LiteView understands all the enhancements to the Autodesk MapGuide Release 6.5 MWF file format, and supports all coordinate systems in which an MWF file can be authored. Autodesk MapGuide LiteView supports GetCapabilities, GetMap, and GetFeatureInfo requests to comply with the OpenGIS Web Map Service (WMS) 1.1.1 implementation specification. You must register maps by using Autodesk MapGuide LiteView’s WMS Administrator before making WMS 1.1.1 requests.

Features

As a developer, the Autodesk MapGuide LiteView features of special interest to you are:

■ User-map interactivity—You can use the following URL parameters in

map requests to give users more opportunities to interact with a map:

❏ SRS (Spatial Reference System) parameter—Overrides the Map Coor-

dinate System (MCS).

❏ SELECT parameter—Supports selection of layer groups as well as the

selection of map features on layers.

❏ HLS (Highlighting Line Styles) parameter—Supports up to four user-

defined highlighting styles that are used to select map features.

❏ SYMBOLS parameter—Identifies one or more map locations by using

a user-defined symbol.

■ Simplified installation and configuration—The Autodesk MapGuide

LiteView installation program prompts you for the most important Autodesk MapGuide LiteView configuration parameters, configures Apache Tomcat, and sets up Autodesk MapGuide LiteView so it is ready to use. The ColdFusion and WMS Viewer sample application files are copied

Overview of Autodesk MapGuide LiteView | 5

to the SampleApp and WmsViewer subfolders in the Autodesk MapGuide LiteView installation folder on your hard drive.

■ Fast map viewing—For first-time users or occasional users, it’s faster to

use a Autodesk MapGuide LiteView application to download and display a raster image than it is to download and install a specialized viewer for image display.

■ Cross-platform deployment—Autodesk MapGuide LiteView responds to

HTTP requests for MWF files by returning images in PNG or JPEG format. Most Web browsers on most platforms support these formats natively.

■ Locked-down deployment—Many organizations prevent users from

downloading and installing viewers, such as ActiveX controls and Java plug-ins, on their desktops. Applications written for Autodesk MapGuide LiteView require no viewers.

6 | Chapter 1 Introduction

Creating an Autodesk MapGuide LiteView Application

You can use the sample applications provided with Autodesk MapGuide LiteView as starting points for creating your own Autodesk MapGuide LiteView applications. This section describes the general steps to create an Autodesk MapGuide LiteView application.

To create a Autodesk MapGuide LiteView application

1 Refer to the Autodesk MapGuide LiteView Servlet Administrator’s Guide to

install and configure Autodesk MapGuide LiteView and the sample applications, and then run a sample application to see how it works.

2 Learn the HTTP requests that the Autodesk MapGuide LiteView servlet

accepts. For information about requests, see Chapter 2, “Understanding Requests,” on page 9, and Chapter 3, “Making GetCapabilities, GetMap, and GetFeatureInfo Requests,” on page 35.

3 Open a sample-application source file and inspect its code. See Chapter 4,

“Configuring and Using the Sample Applications,” on page 49.

4 Read the sample-application source-code comments that explain how to

send get and post HTTP requests.

5 Think of how you might adapt the application to suit your needs.

Understanding Application Architecture | 7

Understanding Application Architecture

The following diagram shows how the Autodesk MapGuide LiteView servlet accepts HTTP requests for raster images through the Java Servlet API interface of a Web server:

The Autodesk MapGuide LiteView servlet requires a Web application server that functions as a Java servlet container.

To fulfill a request for a raster image. Autodesk MapGuide LiteView:

■ Accepts an HTTP request for a raster image of a portion of an MWF file

■ Loads the requested MWF file

■ Zooms to the correct location and scale, generating HTTP requests for

map-layer data to the Autodesk MapGuide Server

■ Returns a raster image in PNG or JPEG format as the HTTP response

Web Server

Autodesk MapGuide Server

Browser

Internet

Extranet

Intranet

Data Sources

MWF

Web

LiteView Servlet

Java Servlet API

Application

Servlet

Container

8 | Chapter 1 Introduction

In this chapter

■ Overview of requests and

responses

■ Creating a map request

■ Creating a feature_info

request

■ Interpreting responses to a

feature_info request

Understanding Requests

This chapter gives an overview of requests and responses

using Autodesk

MapGuide® LiteView, and describes how

to create requests for a map image and its feature informa-

tion, and describes how to interpret a response that con-

tains feature information.

10 | Chapter 2 Understanding Requests

Overview of Requests and Responses

This chapter describes how to construct the following HTTP requests in an Autodesk MapGuide LiteView application and how to work with the responses:

■ map request—Returns the map image to the application

■ feature_info request—Returns information about a map feature, located

at a specified point, to the application

The format of the responses to the map and feature_info requests are:

■ Response to a map request—A PNG or JPEG image

■ Response to a feature_info request—An XML document that describes

the selected feature

OpenGIS WMS 1.1.1 Compliance

Autodesk MapGuide LiteView’s map-request and map-interface features comply with the OpenGIS Web Map Service (WMS) 1.1.1 implementation specification, available at http://www.opengis.org/techno/specs/01068r3.pdf. As an active and Principal Member of the Open GIS Consortium (OGC) Autodesk works with OGC staff and members to create industry-standard mapping specifications for the Web. The OGC Web site is at www.opengis.org.

This chapter describes how to make requests that comply with the draft WMS specification (that is, map and feature_info requests). To make requests that comply with WMS 1.1.1 by using GetCapabilities, GetMap, and GetFeatureInfo operations, see Chapter 3, “Making GetCapabilities, GetMap, and GetFeatureInfo Requests,” on page 35.

Non-WMS 1.1.1-Compliant Parameters

In addition to the map-request parameters defined by WMS 1.1.1, Autodesk MapGuide LiteView also supports the Autodesk-specific parameters HLS, SYMBOLS, SELECT, and PPIY.

Creating a map Request

You use a map request in the HTTP get or post request of your application; see “Using Get and Post Requests,” on page 68. The map request parameters

Creating a map Request | 11

define the map’s extents, content, and image size. Autodesk MapGuide LiteView returns a PNG or JPEG image of the map in response.

Formatting a map Request

A map request consists of a URL, required parameters, variable and constant parameter values, and delimiters—ampersand (&), equal sign (=), and comma (,). You can use the comma delimiter with the SELECT and SYMBOLS parameters to imply values, so you don’t have to list them repeatedly in a single request. A map request also can include optional parameters.

The syntax of a map request is described by using the following conventional notation:

■ Parameter values—Enclosed in angle brackets, using the data type of the

variable, such as <float>, or a short description of the variable in angle brackets, such as <filename.mwf>.

■ Optional elements of the map request—Enclosed in square brackets ([ ]).

■ Repeated parameters—Indicated with an ellipsis (...).

■ Prefix—Represents the URL of the Autodesk MapGuide LiteView servlet:

http://<webserver_name>/<context_path>/servlet/MapGuideLiteView?

<webserver_name> is the name of the Web server under which Autodesk

MapGuide LiteView is running, followed by a colon (:) and a port number. <context_path> may or may not appear, depending on your applicationserver configuration. The question mark (?) at the end of the prefix separates the servlet address from the request parameters. For the default Autodesk MapGuide LiteView installation, which requests the MapGuideLiteView servlet from Apache Tomcat, the URL (for a local host) is:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView

This URL is used in many examples in this document. When making your own requests, change <webserver_name> and <context_path> to match your configuration.

Note If you’re using the JRun application server, omit <context_path>.

■ Other elements—Are literals.

Syntax of a Minimal map Request

The syntax of the following map request includes only required parameters:

<prefix>?

REQUEST=map &BBOX=<minX>,<minY>,<maxX>,<maxY>

12 | Chapter 2 Understanding Requests

&WIDTH=<integer> &HEIGHT=<integer> &LAYERS=<filename.mwf> &FORMAT=<PNG|JPEG|JPG>

Syntax of Optional Parameters

The map request can include the following optional parameters, each having its own syntax:

■ SELECT parameter syntax:

&SELECT=<MWFName>/[MWFLayerName|MWFLayerGroupName], featureID (,<MWFName>/[MWFLayerName|MWFlayerGroupName], [featureID])*

■ SRS parameter syntax:

&SRS=ADSK:LL84

■ HLS parameter syntax

&HLS=<n>

■ SYMBOLS Parameter Syntax

&SYMBOLS=<SymbolName>,<X>,<Y>,<Width>,<Height>,

[(rotationDegrees)],[<labelString>] (,[<SymbolName>],<X>,<Y>,[<Width>],[<Height>], [<rotationDegrees>],[<labelString>])*

Example of a Minimal Map Request

The following example shows a map request that uses only required parameters for the map named Sample_World.mwf:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView?

REQUEST=map &BBOX=26.117831,30.373481,49.340653,68.102723 &WIDTH=600 &HEIGHT=300 &LAYERS=Sample_World.mwf &FORMAT=PNG

The request specifies a bounding box with a lower-left coordinate of (26.117831, 30.373481) and an upper-right coordinate of (49.340653,

68.102723). This box is the area of the map to be displayed in the browser as a PNG image with dimensions of 600 x 300 pixels.

Creating a map Request | 13

Examples of Optional Parameters

The following example shows how to use the optional SELECT parameter to display US, CA, and UK features on the Countries layer of Sample_World.mwf:

Null values between comma delimiters imply the repeated use of Sample_World.mwf/Countries as the MWF and the layer that has CA and UK features.

The following example shows how to set the SYMBOLS parameter to specify insertion of a single symbol, TestSymbol, at point (32.5,45.2) that is 0.001 by

0.001 meters, not rotated, and displayed with the label test:

&SYMBOL=TestSymbol,32.5,45.2,0.001,0.001,,test

The following examples show how to set the SRS and HLS parameters:

&SRS=ADSK:LL84 &HLS=3

Overview of map Request Parameters

The following table briefly describes the map-request parameters that were introduced in “Formatting a map Request,” on page 11. For detailed information about these parameters, see “Understanding map Request Parameters,” on page 15.

Note You must include all the following parameters in a map request except SELECT, SRS, HLS, SYMBOLS, and PPIY.

Parameters for map Requests

Parameter Description Content

REQUEST Required. The type of request. “map”

BBOX Required. The bounding box of the

requested map image, specified by the MCS, unless overridden by the SRS parameter. The image’s bounding box should fall within the maximum extents of the authored map. The first pair of floats specifies the lower-left X-Y coordinate and the second pair specifies the upper-right X-Y coordinate.

minX,minY,maxX,maxY Floating-point numbers.

&SELECT=Sample_World.mwf/Countries,US,,CA,,UK

Repeated delimiters

14 | Chapter 2 Understanding Requests

WIDTH Required. The width of the requested

image, expressed in pixels.

An integer between 16 and 2048, inclusive.

HEIGHT Required. The height of the requested

image, expressed in pixels.

An integer between 16 and 2048, inclusive.

LAYERS Required. The name of a registered MWF file

found in the search path specified by the MWFSearchPath parameter in config.ini (see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk

MapGuide LiteView Servlet Administrator’s Guide). All layers of the map, visible at the

current scale and not password-protected, are included in the returned raster image. Locked layers cause map and feature_info requests to fail. For more information, see “LAYERS Parameter,” on page 15.

filename.mwf

A file name without drive, folder, or relative path.

FORMAT Required. The format of the requested

image.

“PNG”, “JPEG”, or “JPG”

SELECT Optional. A list of name-value pairs. The

name portion of the pair is a map layer or map group name. The value portion is the feature ID of the map feature that should be drawn in the selected state. The map-layer name is the MWF file name followed by a forward slash and the name of an Autodesk MapGuide layer within the MWF file. For more information, see “SELECT Parameter,” on page 17.

A list of comma-separated items to select or highlight.

SRS Optional. Specifies the type of coordi-

nates— latitude/longitude instead of MCS. Used by the BBOX and SYMBOL parameters. For more information, see “SRS Parameter,” on page 19.

“ADSK:LL84”

Parameters for map Requests (continued)

Parameter Description Content

Creating a map Request | 15

Understanding map Request Parameters

The following sections cover some of the map-request parameters in more detail than the table on page 13.

LAYERS Parameter

To locate an MWF file, Autodesk MapGuide LiteView concatenates the MWF name specified in the map request and the value of that MWFSearchPath parameter specified in config.ini. MWFSearchPath can contain multiple path names, each of which Autodesk MapGuide LiteView prefixes onto the LAYERS value and uses to search for the MWF file. Locked layers cause map and feature_info requests to fail. To specify the value of the LAYERS parameter in a request, use either the file name or the relative path and file names of an MWF. You can omit the .mwf extension.

HLS Optional. Specifies one of the highlighting

styles (line thickness, line style, and so on) that are defined by the config.ini file’s own HLS parameter(s). Autodesk MapGuide LiteView assigns a default style if this parameter is omitted. For more information about con- fig.ini’s HLS parameter, see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

An integer between 1 and 4, inclusive.

SYMBOLS Optional. User-defined symbols that identify

map locations. If SYMBOLS is omitted from the request, map symbols aren’t displayed. For more information, see “SYMBOLS Parameter,” on page 20.

A list of comma-separated items that designate map locations.

PPIY Optional. An integer that represents the cli-

ent browser’s vertical display resolution, expressed in pixels per inch. If PPIY is omitted from the request, Autodesk MapGuide LiteView uses the default value 72 (the standard resolution for onscreen Web images). For more information, see “PPIY Parameter,” on page 19.

An integer between 1 and 2147483647, inclusive.

Parameters for map Requests (continued)

Parameter Description Content

16 | Chapter 2 Understanding Requests

The following restrictions apply if you use a relative path to specify the LAYERS parameter value:

■ Absolute paths are not allowed

■ Use only paths relative to the directories specified by the MWFSearchPath

parameter in the config.ini file, with the following exceptions:

❏ Relative paths that move upward in the file structure (paths with ..\,

for example) are not allowed

❏ Relative path names starting with .\ or ./ are not allowed

Autodesk MapGuide Autodesk MapGuide LiteView assumes that MWF names are relative to the MWFSearchPath pathnames. Below are some examples of valid MWF names, assuming that MyMap.mwf exists in the appropriate folder:

■ MyMap.mwf

■ MyMap

■ reldir1/reldir2/MyMap

In Windows, you can’t use the following characters in file names:

\/:*?"<>|

Note You can use the backslash (\) as a path separator whether or not you enclose the MWF name in quotation marks. Names that contain restricted characters (covered next) must be enclosed in quotes.

Restricted Characters in the LAYERS Parameter

You can’t use the following characters in a LAYERS parameter value:

■ control characters

■ space

■ forward slash (/)

■ comma (,)

■ ampersand (&)

■ pound (#)

■ percent (%)

■ certain alphanumeric symbols

For more information about restricted characters, visit http://www.w3.org/ Addressing/rfc1738.txt

To use restricted characters in the LAYERS parameter, you must encode them in hexadecimal, and preface them with a percent symbol. After encoding restricted characters, enclose the coded file name in quotation marks.

Creating a map Request | 17

If the MWF file name that you want to use in a LAYERS parameter value is map5&6.mwf, for example, you would encode the ampersand (&) as hexadecimal %26, and specify the file name as LAYERS=”map5%266.mwf”.

SELECT Parameter

This section describes how to use the SELECT parameter to:

■ Select a feature from a layer

■ Select a feature from a group layer

■ Select multiple features

■ Set the SELECT parameter to a value that contains restricted characters

■ Highlight a selected map feature

You set the SELECT parameter to a list of layer-name, ID pairs. The layer-name portion of the pair is a map-layer or map-group name. The ID portion of the pair is the feature ID of a map feature to be drawn in the selected state.

You use the MWF file name followed by a forward slash (/) and the name of an Autodesk MapGuide layer or group within the MWF, followed by a comma and the feature ID, as follows:

■ <MwfName>/<LayerNameInMWF>, <feature ID>

■ <MwfName>/<LayerGroupNameInMWF>, <feature ID>

If all the features are on the same layer or in the same layer group, you don’t have to repeat the second and subsequent names—use a repeated comma delimiter instead of the names. The following example specifies a map with two features selected from the roads layer:

SELECT=USA.MWF/Roads,0002,,0005

Selecting Features from a Group Layer

The following SELECT example returns a map with two features selected from the roads group layer:

SELECT=USA.MWF/RoadsGroupLayer,0002,,0005

Keep the following rules in mind when selecting features from a group layer:

■ The layer name and layer group name must be unique.

■ The feature IDs within a layer group must be unique among layers; other-

wise, only one of the features is selected at random.

■ If the layer name and layer group name are the same, the layer group has

priority over the layer name, and the feature is selected from the layer group.

18 | Chapter 2 Understanding Requests

Selecting Multiple Features

To select multiple features from a layer or a layer group, use the following syntax:

SELECT=<MWFName>/[MWFLayerName|MWFLayerGroupName], featureID

(,<MWFName>/[MWFLayerName|MWFlayerGroupName], [featureID])*

Restricted Characters in the SELECT Parameter

You must enclose the layer-name portion of the SELECT parameter (MWFName/MWFLayerName) in quotation marks if the name contains a space, a forward slash, or a comma. The operating system doesn’t allow these characters in either the MWF name or a relative path. If the layer name already contains a quotation mark, add another quotation mark in front of it, as shown in the second and third examples in the following table:

The following example shows how you can enclose the layer name alone in quotation marks:

hudson_river.mwf/"Rye,NY",0044

If the MWF file name starts with a relative path, you must enclose the entire path and MWF name in quotation marks. The next example shows an MWF file name that includes a relative path. In this example, both the MWF file name and the layer name separately are in quotation marks:

"NYrivers\hudson_river.mwf"/"Rye,NY",0044

The SELECT parameter value in the following map request uses layer names (X Layer and Z Layer) that require quotation marks because they include spaces:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView?

REQUEST=map &BBOX=26.117831,30.373481,49.340653,68.102723 &WIDTH=600 &HEIGHT=300 &LAYERS=Sample_World.mwf &FORMAT=PNG

Layer Name Formatted Layer Name

roads, local "roads, local"

roads, "local" "roads, ""local"""

roads,"local "roads,""local"

Creating a map Request | 19

&SELECT="Sample_World.mwf"/"X Layer",0032,

"Sample_World.mwf"/"Z Layer",0004

Highlighting a Selected Map Feature

Use the following procedure to highlight a selected map feature.

To highlight a selected map feature

1 Get the feature ID of the object at the user-selected point.

The source code in the ColdFusion sample application file featureInfo.cfm shows you how to get the feature ID.

2 Retrieve the feature ID from the XML stream.

To see an example of how to retrieve the feature ID from the XML stream see the featureInfo.cfm page of the ColdFusion sample application. This application parses the featureInfo.cfm page in the feature_info frame, sends a feature_info request to Autodesk MapGuide LiteView, and captures the XML.

3 Create a map request by using the ID with the SELECT parameter to high-

light the feature, and then send the request. To see an example of how to create a map request, see the ColdFusion sample application’s map.cfm page.

For more information about using the SELECT parameter, see “Understanding the Select And Identify Implementation,” on page 75.

SRS Parameter

If the SRS parameter appears in the map request, Autodesk MapGuide LiteView interprets coordinates as latitude/longitude. If SRS is absent, Autodesk MapGuide LiteView interprets the BBOX and SYMBOLS parameters as coordinates of the Map Coordinate System (MCS). If SRS is specified, set it to ADSK:LL84 (the only SRS value supported in this release).

PPIY Parameter

Either the map request or the config.ini file specifies the PPIY value, which dynamically changes the display resolution of the client browser when Autodesk MapGuide LiteView responds to a map request. To determine the

20 | Chapter 2 Understanding Requests

resolution of the map, Autodesk MapGuide LiteView takes the following steps:

■ Autodesk MapGuide LiteView determines whether the application has

specified a client resolution through the PPIY parameter in the map request.

■ If PPIY is omitted from the request, Autodesk MapGuide LiteView uses the

PPIY parameter defined in config.ini. For information about the config.ini file, see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

You can use PPIY used to increase the vertical pixel resolution of the returned PNG or JPEG image. When you want to print a Autodesk MapGuide LiteView map in large scale, increase PPIY to prevent degradation of printed-image quality.

SYMBOLS Parameter

Your application can use the SYMBOLS parameter to designate one or more map locations by using user-defined symbols. These locations can mark places of interest or a route’s start or destination points, for example. Symbols, which can differ by location, have the following characteristics:

■ Symbol size is independent of map scale, so a symbol’s size is constant at

any zoom level.

■ The symbol can be rotated counterclockwise at an angle expressed in

degrees.

■ An application can label each symbol with a user-defined text string.

Autodesk MapGuide LiteView displays the label below (south of) the symbol; if that position would overwrite a feature label, Autodesk MapGuide LiteView displays the label beside the symbol.

To add symbols to a map, use the SYMBOLS parameter in the map request.

Setting the SYMBOLS Parameter

To add symbols to a map, use the following syntax:

SYMBOLS=<Name>,<X>,<Y>,<Width>,<Height>,[(Rotation)],

[<Label>](,[<Name>],<X>,<Y>,[<Width>],[<Height>], [<Rotation>],[<Label>])*

Creating a map Request | 21

The following table specifies the SYMBOLS parameter:

Examples of the SYMBOLS Parameter

The following example shows how to use SYMBOLS to insert a single symbol, TestSymbol, at point (2000, 2000) that is 0.001 x 0.001 meters, rotated 30 degrees, and displayed with the label test:

SYMBOLS=TestSymbol,2000,2000,0.001,0.001,30,test

The next example shows how to insert two instances of TestSymb ol at points (2000, 2000) and (2500, 2500), rotated 30 degrees, and labeled test1 and test2, respectively:

SYMBOL=

TestSymbol,2000,2000,0.001,0.001,30,test1,,2500,2500,,,,test2

Default Symbol Layer Styles

You can set the default symbol layer styles in the config.ini file by setting the SymbolXxx parameters; see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

Specification Description

Name The name of an Autodesk MapGuide API symbol. If a symbol

with the specified name is not found, the default symbol (a black square) is displayed.

X, Y The insertion point, usually the center, defined by the symbol.

By default, the insertion point is specified in the coordinate system used by the map MCS, unless it is overridden by the SRS parameter. If the X, Y elements fall outside the map range then the symbol is drawn outside the range. The symbol is clipped if it falls on the edge of the map.

Width, Height The size of the symbol, expressed in meters.

Rotation The angle of rotation for the symbol, expressed in degrees. The

default value is zero degrees. The angle of rotation is measured counterclockwise from East and is between -360 to +360, inclusive.

Label A string of up to 254 characters that labels the symbol’s loca-

tion. You must encode the label if it contains special characters such as $, & and ?; see “Restricted Characters in the LAYERS Parameter,” on page 16.

22 | Chapter 2 Understanding Requests

Tips for Creating Map Requests

Some important things to remember when creating a map request are:

■ Maps must reside on the same local area network (LAN) as the Autodesk

MapGuide LiteView servlet.

■ You must set the MWFSearchPath parameter in the config.ini file to list the

location of the MWF files. For information about setting this parameter, see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

■ If you use SELECT to specify multiple layers, designate layers from a single

map.

■ The BBOX parameter must specify an area of the map that falls within the

maximum extents of the authored map; otherwise, Autodesk MapGuide LiteView displays only the background color of the map.

■ Coordinates in the request must be in map coordinate system (MCS)

units, unless the SRS is set to ADSL:LL84, in which case the coordinates must be latitude/longitude.

■ All map-request parameter values are case-sensitive except the value of the

REQUEST parameter.

Creating a feature_info Request

You u se a feature_info request in the HTTP get or post request of your application to obtain feature information about the feature located at a specified point. The feature_info request has the following format:

<prefix>?

REQUEST=feature_info &BBOX=<minX>,<minY>,<maxX>,<maxY> &WIDTH=<integer> &HEIGHT=<integer> &LAYERS=<filename.mwf> &X=<integer> &Y=<integer> &PPIY=<integer>

<prefix> is the URL of the Autodesk MapGuide LiteView servlet: http://<webserver_name>/<context_path>/servlet/MapGuideLiteView

The prefix for the default Autodesk MapGuide LiteView installation is: http://localhost:8080/liteview6.5/servlet/MapGuideLiteView

For general information about request syntax, see “Formatting a map Request” on page 11.

Creating a feature_info Request | 23

Example of a feature_info Request

The following example requests feature information from the Sample_World.mwf file. The request specifies a bounding box with a lower-left coordinate of (26.117831, 30.373481) and upper-right coordinate of (49.340653, 68.102723), which identifies the area of interest on the map. The request also specifies the area’s width and height, expressed in pixels, and the feature’s XY location, expressed in pixels:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView? REQUEST=feature_info &BBOX=26.117831,30.373481,49.340653,68.102723 &WIDTH=600 &HEIGHT=400 &LAYERS=Sample_World.mwf &X=300 &Y=200

Positioning Feature Information

The XY pixel position of the feature information must correspond to the displayed map, so that your application displays feature information in an appropriate location. You match the LAYER, BBOX, WIDTH, and HEIGHT values of the map request and feature_info request to display feature information correctly. In the ColdFusion sample application map.cfm, for example, these values are set for Sample_World.mwf as follows:

The following excerpt from feature_info.cfm shows that when the ColdFusion sample application builds the feature_info request, it uses form variables passed from map.cfm to set LAYER, BBOX, WIDTH, and HEIGHT values to match those of the map request:

<cfset urlRequest =

"http://" & Form.server & "/servlet/MapGuideLiteView? REQUEST=feature_info &HEIGHT=" & Form.height & "&WIDTH=" & Form.width & "&LAYERS=" & Form.mapName & "&BBOX=" & Form.bbox & "&X=" & Form.MAP.X & "&Y=" & Form.MAP.Y>

Note The Form.server variable must include the web-server name and context path. For a default Autodesk MapGuide LiteView installation, Form.server is

24 | Chapter 2 Understanding Requests

“localhost:8080/liteview6.5”. For more information, see “Formatting a map Request” on page 11.

Understanding feature_info Request Parameters

The following table describes feature_info-request parameters.

Note You must include all the following parameters, except PPIY, in a feature_info request:

Feature_info Request Parameters

Parameter Description Content

REQUEST Required. Type of request. ”feature_info”

BBOX Required. The bounding box of the

minX,minY,maxX,maxY Floating-point numbers.

WIDTH Required. The width of the requested

image, expressed in pixels.

integer

HEIGHT Required. The height of the requested

image, expressed in pixels.

integer

LAYERS Required. The name of a registered MWF

found in the search path specified by the MWFSearchPath parameter in config.ini (see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk

MapGuide LiteView Servlet Administrator’s Guide). All layers of the map, visible at the

current scale and not password-protected, are included in the returned raster image. Locked layers cause map and feature_info requests to fail.

Sample_World.mwf

A file name without any leading drive, folder, or relative path information.

Creating a feature_info Request | 25

X Required. The pixel offset in the X direc-

tion that identifies the feature of interest. The upper-left corner of map image is at 0,0. Increase the value of X to move the right.

integer

Y Required. The pixel offset in the Y direc-

tion that identifies the feature of interest. The upper-left corner of map is at 0,0. Increase the value of Y to move down.

integer

PPIY Not used. The screen’s vertical resolution,

expressed in pixels per inch. This parameter is not used from the map request, but is taken from config.ini (or set to 72 by default).

An integer between 1 and 2147483647, inclusive.

Feature_info Request Parameters (continued)

Parameter Description Content

26 | Chapter 2 Understanding Requests

Interpreting Responses to a feature_info Request

The response to a feature_info request is an XML document that encodes the selected features by using gmlfeature.dtd and gmlgeometry.dtd taken from the OGC recommendation for GML.

“feature_info Response DTDs” on page 28 contains a portions of gmlfeature.dtd and gmlgeometry.dtd. Both DTDs (document type definitions) have been simplified for use in this document. Autodesk MapGuide LiteView formats its responses according to these DTDs.

The response to a feature_info request should be set to the MIME type text/xml. The following table describes the elements of a response:

Coordinate data is displayed only if the authored map references spatial data resources that are not password-protected.

Note Multipolygons are returned with each boundary marked as an outerBoundary, regardless of its relationship to other boundaries.

Response to a feature_info Request

Element Attribute Setting

<FeatureCollection> typeName “FeatureInfo”

<Feature> typeName The <MWFName>/<LayerNameInMWF>

or <GroupNameInMWF> that holds the identified feature

<Feature> identifier The Autodesk MapGuide feature key

<name> within <Feature> — The Autodesk MapGuide feature name

<property> typeName

type

The Autodesk MapGuide feature URL, encoded as <hyperlink>

The Autodesk MapGuide feature URL, encoded as <string>

<geometricProperty> typeName "geometry"

Interpreting Responses to a feature_info Request | 27

Sample Response

A Autodesk MapGuide LiteView sample response to a feature_info request is:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE FeatureCollection SYSTEM "gmlfeature.dtd">

</Box>

</boundedBy>

<name>Main Street</name> <property typeName="hyperlink" type="string">

http://www.mysite.com/scripts/info.cgi?fid=01 </property> <geometricProperty typeName="geometry">

0.0,0.0 0.5,0.5 0.5,1.0 1.0,1.0 1.5,1.0 1.6,1.8

</coordinates>

</LineString> </geometricProperty>

</Feature>

</featureMember>

</FeatureCollection>

28 | Chapter 2 Understanding Requests

feature_info Response DTDs

This section presents the DTDs that are used to format responses to feature_info requests. Use these DTDs to interpret XML responses returned by an Autodesk MapGuide LiteView application.

gmlfeature.dtd

<?xml version="1.0" encoding="UTF-8"?>

<!ENTITY % GMLGEOMETRYDTD SYSTEM "gmlgeometry.dtd"> %GMLGEOMETRYDTD;

<!ELEMENT Feature ( description?, name?, boundedBy?, property*, geometricProperty* )>

<!ATTLIST Feature typeName CDATA #REQUIRED identifier CDATA #IMPLIED >

<!ELEMENT FeatureCollection ( description?, name?, boundedBy, property*, geometricProperty*, featureMember* )>

Interpreting Responses to a feature_info Request | 29

<!ATTLIST FeatureCollection typeName CDATA #REQUIRED identifier CDATA #IMPLIED >

<!ELEMENT featureMember ( Feature | FeatureCollection )>

<!ATTLIST featureMember typeName CDATA #REQUIRED >

<!ELEMENT property (#PCDATA)> <!ATTLIST property typeName CDATA #REQUIRED type ( boolean | integer | real | string ) "string" >

<!ELEMENT geometricProperty (%GeometryClasses;)> <!ATTLIST geometricProperty typeName CDATA #REQUIRED >

gmlfeature.dtd (continued)

30 | Chapter 2 Understanding Requests

gmlgeometry.dtd

<!ELEMENT coordinates (#PCDATA) > <!ATTLIST coordinates decimal CDATA #IMPLIED cs CDATA #IMPLIED ts CDATA #IMPLIED >

<!ELEMENT Box (coordinates) > <!ATTLIST Box ID CDATA #IMPLIED srsName CDATA #REQUIRED >

<!ELEMENT Point (coordinates) > <!ATTLIST Point ID CDATA #IMPLIED srsName CDATA #IMPLIED >

<!ELEMENT LineString (coordinates) > <!ATTLIST LineString ID CDATA #IMPLIED srsName CDATA #IMPLIED >

Interpreting Responses to a feature_info Request | 31

<!-- a Polygon is defined by an outer boundary and zero or more inner boundaries. These boundaries are themselves defined by LinerRings.

--> <!ELEMENT Polygon (outerBoundaryIs, innerBoundaryIs*) > <!ATTLIST Polygon ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT outerBoundaryIs (LinearRing) > <!ELEMENT innerBoundaryIs (LinearRing) >

<!ELEMENT LinearRing (coordinates) > <!ATTLIST LinearRing ID CDATA #IMPLIED >

<!ELEMENT MultiPoint (pointMember+) > <!ATTLIST MultiPoint ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT pointMember (Point) >

<!ELEMENT MultiLineString (lineStringMember+) > <!ATTLIST MultiLineString ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT lineStringMember (LineString) >

<!-- a MultiPolygon is defined by zero or more Polygons, referenced through a polygonMember

element. --> <!ELEMENT MultiPolygon (polygonMember+) > <!ATTLIST MultiPolygon ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT polygonMember (Polygon) >

gmlgeometry.dtd (continued)

32 | Chapter 2 Understanding Requests

<!ELEMENT GeometryCollection (geometryMember+) > <!ATTLIST GeometryCollection ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT geometryMember %GeometryClasses; >

<!-- GML provides an 'endorsed' name to define the extent of a feature. The extent is defined

by a Box element, the name of the property is boundedBy. --> <!ELEMENT boundedBy (Box) >

<!ELEMENT geometryProperty (%GeometryClasses;) >

<!ELEMENT pointProperty (Point) > <!ELEMENT centerOf (Point) > <!ELEMENT location (Point) > <!ELEMENT position (Point) >

<!ELEMENT lineStringProperty (LineString) > <!ELEMENT centerLineOf (LineString)> <!ELEMENT edgeOf (LineString)>

<!ELEMENT polygonProperty (Polygon) > <!ELEMENT coverage (Polygon)> <!ELEMENT extentOf (Polygon)>

<!-- the multiPointProperty has three descriptive names: multiCenterOf, multiLocation and

multiPosition. --> <!ELEMENT multiPointProperty (MultiPoint) > <!ELEMENT multiCenterOf (MultiPoint) > <!ELEMENT multiLocation (MultiPoint) > <!ELEMENT multiPosition (MultiPoint) >

gmlgeometry.dtd (continued)

Interpreting Responses to a feature_info Request | 33

<!ELEMENT multiLineStringProperty (MultiLineString) > <!ELEMENT multiCenterLineOf (MultiLineString) > <!ELEMENT multiEdgeOf (MultiLineString) >

<!ELEMENT multiPolygonProperty (MultiPolygon) > <!ELEMENT multiCoverage (MultiPolygon) > <!ELEMENT multiExtentOf (MultiPolygon) >

<!ELEMENT geometryCollectionProperty (GeometryCollection) >

<!ELEMENT name (#PCDATA)> <!ELEMENT description (#PCDATA)>

gmlgeometry.dtd (continued)

34 | Chapter 2 Understanding Requests

Making GetCapabilities, GetMap, and GetFeatureInfo Requests

This chapter describes Autodesk MapGuide® LiteView’s

support for OpenGIS Web Map Service (WMS) 1.1.1

GetCapabilities, GetMap, and GetFeatureInfo operations.

WMS specifies a URL syntax for producing maps on the

Web from georeferenced data. Developed by the Open

GIS Consortium (OGC), WMS is a widely adopted, open

standard and is available at http://www.opengis.org/

techno/specs/01-068r3.pdf.

In this chapter

■ Overview

■ GetCapabilities requests

■ GetMap requests

■ GetFeatureInfo requests

36 | Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests

Overview

The OpenGIS WMS 1.1.1 specification requires that any WMS-compliant server support GetCapabilities, GetMap, and GetFeatureInfo requests.

A GetCapabilities request returns an XML document containing service and capabilities metadata. Service metadata provides information about the WMS and the host organization. Data can include the name of the service, an abstract describing the service, a list of online resources (URLS) that provide additional information about the organization or service, contact information, and fees and access constraints that apply to the service. Capabilities metadata provides information about the requests supported by the service and the HTTP protocols that can be used to access those requests, the format of exceptions returned by the service, vendor-specific capabilities, the level of support the service has for user-defined styles, and finally a hierarchical list of layers that the service supports.

A GetMap request returns a map image with well-defined geospatial and dimensional parameters.

A GetFeatureInfo request returns information about a particular feature on a map.

Autodesk MapGuide LiteView supports GetCapabilities, GetMap, and GetFeatureInfo requests by implementing a WMS server and a WMS Administrator tool. This chapter covers requests. For information about WMS Administrator, see Chapter 6, “Working with the WMS Administrator Tool” in the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

GetCapabilities Requests

The response to a GetCapabilities request is an XML metadata document that describes the maps (MWF files) available on the specified WMS server. Some of the information in the returned document comes from the MWF files and some from the administrator who registers MWF files by using WMS Administrator.

For the default Autodesk MapGuide LiteView installation, the following example shows the URL for a typical GetCapabilities request from a WMScompliant Web client:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView?

REQUEST=GetCapabilities &SERVICE=WMS

GetCapabilities Requests | 37

&VERSION=1.1.1

For general information about request syntax, see “Formatting a map Request” on page 11.

GetCapabilities Request Parameters

The following table describes GetCapabilities-request parameters:

GetCapabilities Metadata Response

The capabilities XML document generated in response to a GetCapabilities request contains service metadata and capabilities metadata. Some fields within the returned document are editable, whereas others are fixed. The following table shows each element in the capabilities metadata and identifies the source—MWF or CDT (capabilities document template)—from which Autodesk MapGuide LiteView takes the value. For those values that come from an MWF file, the table identifies the value’s location in the MWF.

Parameter Name Comments

VERSION Optional.

SERVICE Optional. Must be “WMS” if present

REQUEST Required. Must be “GetCapabilities” or “capabilities”

UPDATESEQUENCE Optional. Timestamp, formatted ccyy-mm-ddThh:mm:ss (2003-06-

02T04:44:58, for example), that can be used by clients to cache the capabilities response.

Element/Attribute Source Comments

Service

Name CDT Fixed value. Must be “OGC:WMS”.

Title CDT Editable value. “none” is the default.

Abstract CDT Editable value. “none” is the default.

KeywordList

38 | Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests

Keyword CDT Editable list of zero or more values.

/KeywordList

OnLineResource CDT Editable value. Must be a valid URL.

ContactInformation

ContactPersonPrimary

ContactPerson CDT Editable value.

ContactOrganization CDT Editable value.

/ContactPersonPrimary

ContactPosition CDT Editable value.

ContactAddress

AddressType CDT Fixed value. Must be “postal”.

Address CDT Editable value.

City CDT Editable value.

StateOrProvince CDT Editable value.

PostCode CDT Editable value.

Country CDT Editable value.

/ContactAddress

ContactVoiceTelephone CDT Editable value.

ContactFacsimileTelephone CDT Editable value.

ContactElectronicMailAddress CDT Editable value.

/ContactInformation

GetCapabilities Requests | 39

Fees CDT Editable value. “none” is the default.

AccessConstraints CDT Editable value. “none” is the default.

/Service

Capability

Request

GetCapabilities

Format CDT Fixed value. Must be “application/

vnd.ogc.wms_xml”.

DCPType CDT Fixed DCPType element content declaring

support for both HTTP GET and POST. For POST, the body must be the same URLencoded key-value pairs that can appear in GET requests.

/GetCapabilities

GetMap

Format CDT Image format: “image/png”, “image/jpeg”,

or “image/jpg”.

DCPType CDT Fixed DCPType element content declaring

support for both HTTP GET and POST. For POST, the body must be the same URLencoded key-value pairs that can appear in GET requests.

/GetMap

GetFeatureInfo

40 | Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests

Format CDT Must be “application/vnd.ogc.gml.1”, “text/

xml”, or “text/html“.

“application/vnd.ogc.gml.1” is appropriate only for viewers that support GML 1.0 parsing. MIME types XML and HTML are more widely supported by browsers (with HTML supported by all browsers).

DCPType CDT Fixed DCPType element content declaring

support for both HTTP GET and POST. For POST, the body must be the same URLencoded key-value pairs that can appear in GET requests.

/GetFeatureInfo

/Request

Exception

Format CDT Fixed value. Must be “application/

vnd.ogc.se_xml”.

/Exception

VendorSpecificCapabilities — Not supported or included in the capabilities

response.

UserDefinedSymbolization

SupportSLD (attribute) CDT Fixed value. Must be zero.

UserLayer (attribute) CDT Fixed value. Must be zero.

UserStyle (attribute) CDT Fixed value. Must be zero.

RemoteWFS (attribute) CDT Fixed value. Must be zero.

/UserDefinedSymbolization

Layer (this element is repeated for each MWF published via WMS Administrator)

GetCapabilities Requests | 41

Name MWF Name of an MWF file (“usa.mwf”, for

example). The name value will be encoded.

Title CDT Editable value. MapName is the default.

Abstract CDT Editable value.

KeywordList

Keyword CDT Editable list of (zero or more) values.

/KeywordList

SRS MWF or Ini ADSK:xxxx or EPSG:xxxx mapping from the

MWF or config.ini file. The SRS specified in MWF is selected by default, but an administrator can override this parameter. For more information, see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk MapGuide LiteView Servlet

Administrator’s Guide.

LatLonBoundingBox MWF Latitude/longitude bounding box calculated

from the map’s latitude/longitude center point and width/height, expressed in meters, specified in the MWF file. For arbitrary X-Y coordinate systems, this value can’t be calculated and will be blank initially, but should be entered by the administrator by using the WMS Administrator tool (see Chapter 6, “Working with the WMS Administrator Tool,” in the Autodesk

MapGuide LiteView Servlet Administrator’s Guide).

BoundingBox MWF Bounding box calculated from the map’s

center point and width/height specified in the MWF file.

Dimension — Not supported or included in the capabilities

response.

Extent — Not supported or included in the capabilities

response.

Attribution — Not supported or included in the capabilities

response.

42 | Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests

AuthorityURL — Not supported or included in the capabilities

response.

Identifier — Not supported or included in the capabilities

response.

MetadataURL CDT Editable value.

DataURL — Not supported or included in the capabilities

response.

FeatureListURL — Not supported or included in the capabilities

response for top-level layers (MWF files, for example).

Style — Not supported or included in the capabilities

response.

ScaleHint — Not supported or included in the capabilities

response for top-level layers (MWF files, for example).

Layer (this element is repeated for each layer in the MWF file, Layer Groups are excluded)

Name MWF Name of the MWF file, followed by a “\”,

followed by the name from the layer attributes in the MWF file; “usa.mwf\States”, for example. The Name value is encoded as

<Name>Sample_World.mwf%09World% 20Cities%09National%20Capitals</Name>.

Title MWF LegendLabel from the layer attributes in the

MWF file.

Abstract — If the layer can’t be accessed for any reason,

this field will contain an error message describing the problem.

KeywordList

Keyword — Not supported on nested layers.

/KeywordList

GetCapabilities Requests | 43

SRS — The spatial reference system of the individual

layer. This value usually is inherited from the parent layer (MWF).

The SRS parameter on a nested layer is supported only if the parent MWF can’t be published in EPSG:4326 but some of its vector layers can be published in EPSG:4326. An MWF defined in ADSK:IL-83 that has a visible raster layer, for example, won’t be available in EPSG:4326, but some of its non-raster layers will be available in EPSG:4326.

LatLonBoundingBox — Not supported on nested layers. This value is

inherited from the parent layer (MWF).

BoundingBox — Bounding box of the individual layer. This

value usually is inherited from the parent layer (MWF).

If an individual layer has its own SRS, it also will have its own bounding box.

Dimension — Not supported or included in the capabilities

response.

Extent — Not supported or included in the capabilities

response.

Attribution — Not supported or included in the capabilities

response.

AuthorityURL — Not supported or included in the capabilities

response.

Identifier — Not supported or included in the capabilities

response.

MetadataURL — Not supported or included in the capabilities

response.

DataURL — Not supported or included in the capabilities

response.

FeatureListURL — Not supported or included in the capabilities

response.

44 | Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests

Layer Element Attributes

Several attributes, defined for the Layer element, are included in the capabilities document as follows:

GetMap Requests

The response to a GetMap request is a map, which is either a pictorial image or a set of graphical elements.

Style — Not supported or included in the capabilities

response.

ScaleHint MWF Scale range at which the layer is visible (from

the layer attributes). An administrator can mention any gaps in the scale range in the Abstract field of the MWF file metadata section.

/Layer

/Capability

Layer Attribute Comments

cascaded Always set to zero.

fixedHeight Always set to zero.

fixedWidth Always set to zero.

noSubsets Always set to zero.

opaque Set to zero for a vector layer, set to one for a raster layer.

queryable Top-level layers (MWF files) have the queryable attribute set to one. For

nested layers, if the layer attributes in the MWF file have the selectable flag set, set the queryable attribute to one, otherwise set it to zero. For nested raster layers, set it to zero. (To make a layer selectable, refer to MapGuide Author documentation.)

GetMap Requests | 45

For the default Autodesk MapGuide LiteView installation, the following example shows the URL for a typical GetMap request from a WMS-compliant Web clien t:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView?

REQUEST=GetMap &VERSION=1.1.1 &BBOX=26.117831,30.373481,49.340653,68.102723 &WIDTH=600 &HEIGHT=450 &STYLES= &SRS=EPSG:4326 &LAYERS=Sample_World.mwf &FORMAT=image/png

For general information about request syntax, see “Formatting a map Request” on page 11.

GetMap Request Parameters

The following table describes GetMap-request parameters:

Parameter Name Comments

VERSION Must be “1.1.1”.

REQUEST Must be “GetMap”.

LAYERS List of comma-separated layer names. Layers in the list must be specified as

given in the GetCapabilities response. (If a layer name itself contains a comma, a request will fail.)

STYLES Must be empty. (STYLES also can be a comma-separated list with the same

number of elements as the LAYERS list. Autodesk MapGuide LiteView will validate this list but not apply the styles.)

SRS Identifier for the spatial reference system. This value must match one of the

values for the respective layer in the GetCapabilities response. If more than one layer is requested, this value must match all the SRS values for all the respective layers in the GetCapabilities response.

BBOX List of comma-separated floating-point values specifying the requested

map’s bounding box as “minX,minY,maxX,maxY”. These values must be specified in the coordinate system defined by the SRS parameter.

WIDTH Width of the desired image, expressed in pixels.

HEIGHT Height of the desired image, expressed in pixels.

46 | Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests

Handling Transparency

In Internet Explorer (but not Netscape Navigator), a transparent PNG image appears with a gray background color, so Autodesk MapGuide LiteViewgenerated transparent images can’t be overlaid unless the Web page loads the images by using an AlphaImageLoader filter. Therefore, on web pages that display Autodesk MapGuide LiteView maps, you should use browser-detection techniques and load images by using the AlphaImageLoader only when Internet Explorer is detected. For more information, see http:// msdn.microsoft.com/library/default.asp?url=/workshop/author/filter/reference/filters/AlphaImageLoader.asp

FORMAT Format of the desired image: “image/png”, “image/jpeg”, or “image/jpg”.

TRANSPARENT TRUE or FALSE. For more information, see “Handling Transparency” on

page 46.

BGCOLOR Background color 0xrrggbb, where rrggbb is the hexadecimal representation

of the desired RGB color.

EXCEPTIONS The default value is “application/vnd.ogc.se_xml”.

TIME Optional. Not supported in this release.

ELEVATION Optional. Not supported in this release.

SLD Optional. Not supported in this release.

WFS Optional. Not supported in this release.

SELECT Optional Autodesk MapGuide LiteView-specific optional parameter. SELECT

is applicable if only one layer is specified in the LAYERS parameter. If the user specifies more than one layer, SELECT will work for only the layer to which it applies.

HLS Optional Autodesk MapGuide LiteView-specific optional parameter.

SYMBOLS OptionalAutodesk MapGuide LiteView-specific optional parameter.

PPIY Optional Autodesk MapGuide LiteView-specific optional parameter.

GetFeatureInfo Requests | 47

GetFeatureInfo Requests

The response to a GetFeatureInfo request is an XML or HTML document that provides clients with information about a feature in the map image returned by a GetMap request. GetFeatureInfo is supported for only those layers for which the queryable attribute is one (true).

When a user sees the response (a map image) of a GetMap request and chooses (clicks) a point on that map, a WMS-compliant Web client sends a GetFeatureInfo request such as:

http://localhost:8080/liteview6.5/servlet/MapGuideLiteView?

REQUEST=GetFeatureInfo &VERSION=1.1.1 &BBOX=26.117831,30.373481,49.340653,68.102723 &WIDTH=600 &HEIGHT=450 &STYLES= &SRS=EPSG:4326 &LAYERS=Sample_World &FORMAT=image/png &X=45 &Y=189 &QUERY_LAYERS=Sample_World.mwf

For general information about request syntax, see “Formatting a map Request” on page 11.

GetFeatureInfo Request Parameters

The GetFeatureInfo request has the following URL parameters:

Parameter Name Comments

VERSION Must be “1.1.1”.

REQUEST Must be “GetFeatureInfo”.

<GetMap parameters> All the GetMap request parameters used to generate the map, except

VERSION and REQUEST. See “GetMap Request Parameters” on page 45.

48 | Chapter 3 Making GetCapabilities, GetMap, and GetFeatureInfo Requests

QUERY_LAYERS List of comma-separated layer names to be queried. Layers in the list

must be specified as given in the GetCapabilities response and must not include any layers for which the queryable attribute is zero (false). This list cannot include layers that were not specified in the GetMap LAYERS parameter. One feature is returned for each layer listed in the request. If an MWF file (not an individual layer) is queried, only one feature from the top-most selectable layer is returned.

INFO_FORMAT Must be “application/vnd.ogc.gml.1” (the default), “text/xml”, or

“text/html“.

FEATURE_COUNT Optional parameter that is not supported in this release. GetFeatureInfo

in Autodesk MapGuide LiteView always returns information about a single feature.

X X coordinate of the point of interest, measured in pixels from the top

left corner of the image.

Y Y coordinate of the point of interest, measured in pixels from the top

left corner of the image.

EXCEPTIONS The default value is “application/vnd.ogc.se_xml”.

In this chapter

■ The sample applications

■ The WMS Viewer sample

application

■ The ColdFusion sample

application

■ Troubleshooting and other

resources

Configuring and Using the Sample Applications

When you install Autodesk MapGuide® LiteView, the

Setup program places two sample applications on your

computer. This chapter explains how the sample applica-

tions are designed, describes how to configure and run

them, and describes how to use them as models for writ-

ing your own Autodesk MapGuide LiteView applications.

50 | Chapter 4 Configuring and Using the Sample Applications

The Sample Applications

Autodesk MapGuide LiteView comes with two sample applications:

■ A simple browser-based client, called WMS Viewer, displays maps pub-

lished by Autodesk MapGuide LiteView and by other servers that comply with the WMS 1.1.1 specification. This application supports WMS 1.1.1 GetCapabilities, GetMap, and GetFeatureInfo requests. For more information, see “The WMS Viewer Sample Application” below.

■ A more elaborate viewer application, called the ColdFusion sample applica-

tion, uses ColdFusion to download Autodesk MapGuide LiteView-gener-

ated map images to a browser. This application uses draft-specification map and feature_info requests. For more information, see “The ColdFusion Sample Application” on page 55.

The WMS Viewer Sample Application

WMS Viewer is a browser-based thin client that accesses and displays maps published by Autodesk MapGuide LiteView and by other servers that comply with the OpenGIS Web Map Service (WMS) 1.1.1 implementation specification. WMS Viewer supports conventional navigation operations (zoom, pan, recenter, and manual bounding-box adjustment) and WMS GetCapabilities, GetMap, and GetFeatureInfo requests.

Through WMS Viewer's graphical user interface, you can see which map layers are available (GetCapabilities), select those that interest you, and display and navigate the resulting map (GetMap). If you display multiple layers, WMS Viewer stacks them in the specified order, properly overlaying them geographically. For query-capable layers, you can click a map feature to get more information about it (GetFeatureInfo) in XML, HTML, or other formats.

Starting WMS Viewer

To start WMS Viewer

1 If the application server it isn’t running, start it.

If you let Autodesk MapGuide LiteView Setup install Apache Tomcat,

choose Start ➤ Programs ➤ Autodesk MapGuide Release 6.5 ➤ LiteView

6.5 ➤ Start Apache Tomcat.

2 Open a browser and go to http://localhost:8080/wmsviewer6.5.

The WMS Viewer Sample Application | 51

WMS Viewer appears and, after a few seconds, loads the Sample World Map automatically.

3 To get pop-up help, click the Help button in WMS Viewer’s upper-right

corner.

WMS Viewer

Extending WMS Viewer

You can use WMS Viewer as a model for writing your own Autodesk MapGuide LiteView applications. In general, it’s better to start with a copy of WMS Viewer and modify it to suit your needs. This section describes WMS Viewer’s architecture and gives an example of how to add a new feature to it. WMS Viewer’s default location is

C:\Program Files\Autodesk\MapGuideLiteView6.5\WmsViewer.

WMS Viewer is written in JavaScript, HTML, Java, and JSP (JavaServer Pages). JSP is a server-side process that creates an HTML page from a JSP source page. A Web container processes the JSP source and displays the resulting HTML in a browser. You can inspect the JSP source code in the file WmsViewer.jsp, located in WMS Viewer’s jsp subfolder. Part of WMS Viewer is written in Java. This code mainly is used to issue the GetCapabilities request to the WMS server, and parse the returned capabilities document. The Java source code is available in C:\Program Files\Autodesk\MapGuideLiteView6.5\WmsViewer\src. The Java

52 | Chapter 4 Configuring and Using the Sample Applications

code processes a capabilities document and the result is used by the JSP code to create JavaScript data structures dynamically in the resulting HTML page. These data structures are used to populate the WMS Viewer page’s SRS list, layer list, image-format list, and other elements. The HTML and JavaScript code is available via your browser’s View Source command.

Adding a contact-information retrieval feature

This example adds to the WMS Viewer page a small icon that, when clicked, retrieves contact information and displays it in a pop-up HTML page. The script retrieves contact information from the capabilities document.

To add a contact-information retrieval feature to WMS Viewer

1 Place an image file (contact.jpg, in this example) for the Contact icon in

WMS Viewer’s images subfolder.

2 Add an image link for contact.jpg to the JSP page WmsViewer.jsp, so that the

Contact icon appears to the right of the History icon. The new code is shown here relative to the history.jpg image:

The Contact icon (here, a cell-phone image) will appear next to the History icon, as shown here:

3 To make the Contact icon clickable, add a handler for the showContact-

Info() function:

</a>

4 In the declarations section, declare a variable that will reference the Con-

tact window:

var contactWindow

5 In the declarations section, declare variables to hold the contact informa-

tion, and initialize them with values parsed from the capabilities document. The JSP code (between the <%= and %> symbols) initializes the values and generates the necessary JavaScript code.

//contact information var contactName = '<%= svi != null?

svi.getContactName(): "" %>'

The WMS Viewer Sample Application | 53

var contactOrganization = '<%= svi != null?

svi.getContactOrganization(): "" %>'

var contactAddress = '<%= svi != null?

svi.getContactAddress(): "" %>'

var contactCity = '<%= svi != null?

svi.getContactCity(): "" %>'

var contactState = '<%= svi != null?

svi.getContactState(): "" %>'

var contactTelephone = '<%= svi != null?

svi.getContactTelephone(): "" %>'

var contactEmail = '<%= svi != null?

svi.getContactEmail(): "" %>'

6 Create the showContactInfo() function anywhere in the JavaScript section.

This function opens the pop-up HTML page, ContactInfo.html, that displays the contact information.

function showContactInfo()

{

contactWindow = openWindow("../html/ContactInfo.html",

contactWindow, "height=300, width=400, scrollbars, resizable")

}

7 Create the page ContactInfo.html and place it in WMS Viewer’s html sub-

folder. This page must have seven fields—one for each piece of contact information—belonging to a form named ContactInfo and named name, organization, address, city, state, telephone, and email. These fields are for dis- play purposes only, not user input.

8 On the ContactInfo.html page, add the JavaScript function initContactInfo()

to fill the fields when the page initializes. Use the opener property to access directly the contact-information variables declared in the main WMS Viewer page.

9 On the ContactInfo.html page, use the <body> element’s onload event to

call initContactInfo() when the page initializes.

The code for the completed ContactInfo.html page follows:

<html>

<head>

<title>Contact Information</title> <meta http-equiv="Content-Type" content="text/html;

charset=iso-8859-1">

54 | Chapter 4 Configuring and Using the Sample Applications

function initContactInfo() { //Get the information from the main Viewer script //by using the opener property of this pop-up window document.ContactInfo.name.value =

window.opener.contactName

document.ContactInfo.organization.value =

window.opener.contactOrganization

document.ContactInfo.address.value =

window.opener.contactAddress

document.ContactInfo.city.value =

window.opener.contactCity

document.ContactInfo.state.value =

window.opener.contactState

document.ContactInfo.telephone.value =

window.opener.contactTelephone

document.ContactInfo.email.value =

window.opener.contactEmail

}

</script>

</head>

<body bgcolor="#FFFFFF" text="#000000"

onload="initContactInfo()"> <form name="ContactInfo">

<p> Name: <input type="text" name="name"> <br> Organization: <input type="text" name="organization"> <br> Address: <input type="text" name="address"> <br> City: <input type="text" name="city"> <br> State: <input type="text" name="state"> <br> Tel: <input type="text" name="telephone"> <br>

The ColdFusion Sample Application | 55

Email: <input type="text" name="email"> </p>

</form>

</body>

</html>

10 To test the new feature, start WMS Viewer, specify a server, click Go, and

then click the Contact icon.

The page ContactInfo.html will appear with the contact information:

Configuring WMS Viewer

The Autodesk MapGuide LiteView installation comes with Apache Tomcat

3.3.1a and, at your option, Autodesk MapGuide LiteView Setup will install and configure Tomcat automatically to run with the WMS Viewer. To set up Tomcat or a different application server manually, see Chapter 5, “Configuring Application Servers,” in the Autodesk MapGuide LiteView Servlet Admin- istrator’s Guide.

The ColdFusion Sample Application

The ColdFusion sample application provided with Autodesk MapGuide LiteView is a lightweight viewer that downloads Autodesk MapGuide LiteView-

56 | Chapter 4 Configuring and Using the Sample Applications

generated images to a browser. The sample application implements these features:

■ Recentering the map

■ Getting feature information

■ Displaying online help

■ Zooming

The ColdFusion sample application demonstrates the minimal components and techniques that are needed to create an Autodesk MapGuide LiteView application. Although not implemented in this sample application, you can create an application that:

■ Displays symbols on the image by using the SYMBOLS parameter in a map

request to mark, say, points of interest or a route’s start and end points.

■ Controls the color, thickness, or style of lines in the image by using the

HLS parameter in the map request.

■ Uses latitude/longitude coordinates to specify map locations authored

using an arbitrary coordinate system. Use the SRS parameter in the map request to specify latitude/longitude coordinates regardless of the MCS.

ColdFusion Sample Application Files

The ColdFusion sample application comprises the following server- and client-side files, Java class, and JavaScript scripts, which make up a viewer and interface to Autodesk MapGuide LiteView:

■ ColdFusion templates—The CFM files are the source code for frames of

the sample application. The map.cfm template frame determines which request to send to Autodesk MapGuide LiteView.

■ XML parser—A Java class, parseXML.class, converts feature information

from XML to HTML.

■ Xerces Java Parser 1.0.3—A Java jar file, xerces.jar, adds XML parsing sup-

port to Autodesk MapGuide LiteView.

■ Xalan J Version 1.0.0—A Java jar file, xalan.jar, provides XSLT stylesheet

processing support to Autodesk MapGuide LiteView.

For more information about Xerces and Xalan, visit http://www.apache.org.

■ JavaScript scripts—Scripts, embedded in the CFM files, link the elements

of the application. The sample application also calls these scripts to reload the map frame.

■ Image files—Six image files contain icons for the toolbar buttons.

The ColdFusion Sample Application | 57

■ Help files—Help appears when a user runs the sample application, opens

Autodesk MapGuide LiteView Sample Application Help, and clicks the question mark.

ColdFusion Sample Application Requirements

This section describes the software that you need to support the ColdFusion sample application. The computer on which you run the ColdFusion sample application must be able to connect to Autodesk MapGuide Server Release

6.5. The following software must be installed on the server with the ColdFusion sample application:

■ Autodesk MapGuide LiteView

■ Macromedia ColdFusion Server 4.5.1 SP2 or ColdFusion Server 5

Either ColdFusion Server Profession Edition or ColdFusion Server Enterprise Edition is suitable. You can’t use ColdFusion Express Edition.

Autodesk MapGuide LiteView itself has additional software requirements; see the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

ColdFusion applications are scripted pages and components. When a client browser requests a page in a ColdFusion application, the ColdFusion Server processes the scripting in the page, establishes a connection with appropriate services, and returns the page to the browser.

ColdFusion Sample Application Client Platforms

User who want to view images created by an Autodesk MapGuide LiteView application must have a Web browser that can display PNG or JPEG images and supports the XML 1.0 specification. The browser also must support frames. To view sample-application Help, you must use Netscape Navigator or Microsoft

Internet Explorer. The following table lists the required browsers for

58 | Chapter 4 Configuring and Using the Sample Applications

viewing the ColdFusion sample application under some client operating systems.

Configuring the ColdFusion Sample Application

Note Before configuring the ColdFusion sample application, install and configure Autodesk MapGuide LiteView; see the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

To use the ColdFusion sample application, you first must configure it by performing the following tasks:

■ Set the Java Virtual Machine (JVM) path in the ColdFusion Administrator

■ Set the CFX Jar path in the ColdFusion Administrator

■ Register parseXml in the ColdFusion Administrator

■ Modify map.cfm and featureInfo.cfm for your environment

■ Check the MWFSearchPath in the Autodesk MapGuide LiteView servlet’s

config.ini file to ensure that it is set to find the Sample_World.mwf file.

■ Configure the ColdFusion Application Server to run ColdFusion under a

user account

■ Check that Autodesk MapGuide Server is running, and start it if necessary

Configuring the Java Settings

You set the JVM and CFX Jar paths for your installation of Java by using the ColdFusion Administrator.

Operating System Required Browser

Windows NT 4 with Service Pack 4

Internet Explorer 4.x (minimum) or Netscape Navigator

4.x (minimum)

Windows 2000 Internet Explorer 5.x (minimum) or Netscape Navigator

4.x (minimum)

Windows 98 Internet Explorer 4.x (minimum) or Netscape Navigator

4.x (minimum)

Mac OS 9.1 Java with VM MRJ 2.2.4

Internet Explorer 5.x (minimum) or Netscape Navigator

4.x (minimum)

The ColdFusion Sample Application | 59

To configure Java settings

1 Launch ColdFusion Administrator.

The ColdFusion Server Administrator screen is displayed.

JVM and Java Settings

60 | Chapter 4 Configuring and Using the Sample Applications

2 Under the Extensions category, click JVM and Java Settings.

The JVM and Java Settings page is displayed.

3 Set the Java Virtual Machine path to the jvm.dll pathname.

4 Set the Class Path variable. Include the pathnames for the parseXml class

and the Xalan and Xerces JAR files:

<InstallFolder>\SampleApp\classes <InstallFolder>\SampleApp\classes\parseXml.class <InstallFolder>\SampleApp\classes\xerces.jar <InstallFolder>\SampleApp\classes\xalan.jar

5 Check the location of the cfx.jar file.

ColdFusion puts the JAR file in the following folder by default:

<drive>:\CFUSION\Java\classes

6 If the CFX Jar Path variable is not already set to the path of cfx.jar file,

enter the path.

7 Click Submit Changes.

The ColdFusion Sample Application | 61

Registering parseXml

You use ColdFusion Administrator to register and manage ColdFusion custom tags. To use a CFX tag, you first must register it with ColdFusion, so ColdFusion can find the required DLL for processing the CFX tag in an application page.

To register parseXml

1 Using ColdFusion Administrator, Extensions category, click CFX Tags to

open the Registered CFX Tags page.

The CFX Tags screen is displayed.

2 Click Register Java CFX.

The Add/Edit Java CFX Tag screen is displayed.

3 Set the (case-sensitive) Tag Name to cfx_parseXml.

62 | Chapter 4 Configuring and Using the Sample Applications

4 Set the Class Name to parseXml.

5 Click Submit Changes.

The CFX_PARSEXML tag name is displayed, confirming that it is a registered tag.

6 Close ColdFusion Administrator.

Modifying CFM Files

You must enter the name of your server and path variable in the ColdFusion sample application’s ColdFusion application files.

To modify sample-application files

1 Using a text editor, open the following file:

<InstallFolder>\SampleApp\map.cfm

2 On line 9, replace the

<your-server-name> tag with the name of the server

on which Autodesk MapGuide LiteView is running, for example:

3 Save and close map.cfm.

4 Open the following file in a text editor:

<InstallFolder>\SampleApp\featureInfo.cfm

5 On line 20, replace

<your-SampleApp-path> with the path to the Sam-

pleApp directory, for example:

<cfset sampleAppPath = "C:\Program Files\Autodesk\

MapGuideLiteView6.5\SampleApp\">

Note Add a backslash to the end of the path, as shown here.

parseXML registration confirmation

The ColdFusion Sample Application | 63

6 Save and close featureInfo.cfm.

Starting the ColdFusion Sample Application

To start the ColdFusion sample application

1 Create a virtual directory named TestSample that maps to the

<InstallFolder>\SampleApp folder on your hard drive.

2 Set the access properties of the virtual directory to permit all access modes

except write access.

3 To start the ColdFusion sample application, go to the following URL in a

browser:

http://<webserver_name>/TestSample/index.htm

where webserver_name denotes the name of your Web server. (By default, IIS listens for connections on port 80.)

The browser displays the ColdFusion sample application form.

4 Click a feature on the map.

The feature information is displayed in the Feature Info frame.

64 | Chapter 4 Configuring and Using the Sample Applications

Removing the ColdFusion Sample Application Files

To remove the ColdFusion sample application

1 Stop your application server.

2 In ColdFusion Administrator, delete the Class Path and CFX Jar Path in

ColdFusion. Do not delete the Java Virtual Machine Path, because it isn’t related exclusively to the ColdFusion sample application.

3 Click Apply.

4 Delete the CFX_parseXml tag in ColdFusion.

5 Delete the virtual directory TestSample.

6 Delete Autodesk MapGuide LiteView’s SampleApp files and folders.

Using the ColdFusion Sample Application

This section describes how to use the ColdFusion sample application as a model for your own Autodesk MapGuide LiteView applications. The HTTP response to a request to start the sample application is an HTML form. The form has three frames that contain JavaScript functions and ColdFusion application pages. ColdFusion application pages are ColdFusion documents that are parsed into HTML by the ColdFusion Server. These files have a .cfm extension.

The ColdFusion Sample Application | 65

Organizing the Image into Frames

Organizing an Autodesk MapGuide LiteView application into frames, as the ColdFusion sample application demonstrates, simplifies development. The following diagram shows the frames contained by the ColdFusion sample application form.

■ Frame 1—The map image. The file map.cfm formulates the correct request

to Autodesk MapGuide LiteView:

map.cfm contains the image tag, and the variable src is set to the request to insert the map image:

<cfset maprequest=

"http://" & srvr & "/servlet/MapGuideLiteView? REQUEST = MAP & FORMAT = PNG & HEIGHT = " & height & "&WIDTH = " & width & "&LAYERS = " & mapName & "&BBOX = " & bbox>

src = <cfoutput>#maprequest#</cfoutput>

Note The variable srvr must include the web-server name and context path. For a default Autodesk MapGuide LiteView installation, srvr is “local-

Frame 1:

Frame 2:

Frame 3: Feature information

Toolbar

Map image

Branding message

66 | Chapter 4 Configuring and Using the Sample Applications

host:8080/liteview6.5”, for example. For general information about request syntax, see “Formatting a map Request” on page 11.

■ Frame 2—The toolbar. The file toolbar.cfm uses JavaScript to define the

toolbar. The ColdFusion sample application does not refresh this frame each time that it displays a new map. For more information about the toolbar, see “Understanding the Toolbar Implementation,” on page 74.

■ Frame 3—The feature information. The file featureInfo.cfm creates file vari-

ables for the parseXml ColdFusion custom tag that embeds HTML from the parseXml class into the frame:

Initially, the Feature Info frame is empty. For more information about the parseXml class, see “Understanding the XML Parser,” on page 73.

■ Branding message—A text string that you specify by using the

BrandTextMessage parameter in the config.ini file; see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk MapGuide LiteView Servlet Administrator’s Guide.

The initial view that appears in the browser is from the Sample_World data set.

Setting the Default Bounding Box

Autodesk MapGuide LiteView uses the default bounding box specified in map.cfm to frame returned images:

At start up, and when the user unzooms, the ColdFusion sample application sets the mode and bounding box to default values as follows:

In the initial view, Select And Identify (see “Understanding the Select And Identify Implementation,” on page 75) is the default mode and the button appears to be pressed. Every time the Unzoom method is called, the application returns to this initial state.

Adapting ColdFusion Templates to Your Application

The ColdFusion sample application builds Web pages that include special tags. When a Web browser requests one of these pages, ColdFusion interprets the tags, replaces them with the results of the specified calculations or database queries, and then sends the completed page to the Web server. The Web

The ColdFusion Sample Application | 67

server then sends the page to the browser for display. A ColdFusion script, or template, essentially is a standard HTML file that includes extra tags written in ColdFusion’s server-side markup language, CFML (ColdFusion Markup Language). CFML tags are case-insensitive, begin with the letters cf, and direct ColdFusion to process either a calculation or a query. The tags also can identify a data source and describe how to manipulate or display information in that data source.

Understanding ColdFusion Tags

The following table describes the ColdFusion tags and the actions that the ColdFusion Server takes on reading the tags in the sample application:

To build your own Autodesk MapGuide LiteView application, you can modify the ColdFusion templates that are part of the sample application. The templates encode the map and feature_info requests to Autodesk MapGuide LiteView. The following excerpt from map.cfm encodes the map request, for example:

<cfset maprequest =

"http://" & server & "/servlet/MapGuideLiteView? REQUEST = MAP & FORMAT = PNG & HEIGHT = " & height & "&WIDTH = " & width & "&LAYERS = " & mapName & "&BBOX = " & bbox>

Note The server variable must include the web-server name and context path. For a default Autodesk MapGuide LiteView installation, server is “localhost:8080/liteview6.5”, for example. For general information about request syntax, see “Formatting a map Request” on page 11.

The templates also control the appearance, toolbar functions, and other aspects of the application.

Tag ColdFusion Server Action

cf*** Processes the script that is embedded in the page into HTML.

cfoutput Inserts the value enclosed by the tag’s begin and end elements

in the map request. For example: <cfoutput>#variable#</cfoutput>

cfset Sets the bounding-box parameter of the map request.

68 | Chapter 4 Configuring and Using the Sample Applications

When you encode the map and feature_info requests, make sure that the requests contain the correct parameters; see “Creating a map Request” on page 10 and “Creating a feature_info Request” on page 22.

Using Get and Post Requests

A ColdFusion document accepts two request types: get and post. The ColdFusion sample application works by sending requests to the CFM page.

The get request sets the application’s mode and the MWF bounding-box default values. The get request is used when the sample application is initialized and when the user unzooms. The sample application executes a post request when the user clicks a map to request feature information, for example:

<cfset urlRequest =

"http://" & Form.server & "/servlet/MapGuideLiteView? REQUEST = feature_info & HEIGHT = " & Form.height & "&WIDTH = " & Form.width & "&LAYERS = " & Form.mapName & "&BBOX = " & Form.bbox & "&X = " & Form.MAP.X & "&Y = " & Form.MAP.Y>

Note The variable Form.server must include the web-server name and context path. For a default Autodesk MapGuide LiteView installation, Form.server is “localhost:8080/liteview6.5”. For general information about request syntax, see “Formatting a map Request” on page 11.

The post request of the ColdFusion sample application contains the parameters shown in the following table:

Key Parameter Description Content

BBOX Required. Bounding box of map image being

requested. Specified in terms of the coordinate system used by the map.

“minX, minY, maxX, maxY”

MAP.X Required. X coordinate, expressed in pixels, of

mouse click on the map image.

integer

The ColdFusion Sample Application | 69

A post request submits form data to the CFM. For more information about form data, see “Examining the Map Form in map.cfm,” on page 70. The file map.cfm defines the following variables to hold the post parameters:

The CFM might calculate a new bounding box for the MWF, depending on the user mode when the map was clicked.

Understanding the ColdFusion Sample Application Map Request

The following diagram shows the map-request process.

The process steps shown in the diagram are:

1 The browser opens a default application page.

MAP.Y Required. Y coordinate, expressed in pixels, of

mouse click on the map image.

integer

MODE Required. Current mode of the application as

determined by the toolbar button that the user clicks.

string

SELECT Optional. The key of the feature that you want

the user to perceive as being selected on the map.

string

Key Parameter Description Content

Web server

ColdFusion

server

LiteView

70 | Chapter 4 Configuring and Using the Sample Applications

2 The browser requests a CFM file.

3 The ColdFusion sample application returns an HTML form to the browser.

4 The browser processes the HTML.

5 The ColdFusion sample application reads the image tag and sends the

request to Autodesk MapGuide LiteView.

6 Autodesk MapGuide LiteView embeds a PNG or JPEG image in a Web page

and returns the page.

Examining the Map Form in map.cfm

The ColdFusion sample application starts in Identify mode. A user clicks the map image, causing the following form to be submitted to map.cfm or featureInfo.cfm. By default, the form is submitted to featureInfo.cfm by using the variable info.

<FORM name = "mapform" action="<cfoutput>#cfm#</cfoutput>"

method="POST" target="<cfoutput>#target#</cfoutput>"> <input type = "hidden" name = "SERVER" value =

"<cfoutput>#server#</cfoutput>">

<input type = "hidden" name = "MAPNAME" value =

"<cfoutput>#mapName#</cfoutput>">

<input type = "hidden" name = "WIDTH" value =

"<cfoutput>#width#</cfoutput>">

<input type = "hidden" name = "HEIGHT" value =

"<cfoutput>#height#</cfoutput>">

<input type = "hidden" name = "MODE" value=

"<cfoutput>#mode#</cfoutput>">

<input type = "hidden" name = "BBOX" value=

"<cfoutput>#bbox#</cfoutput>">

<input type = "hidden" name = "FEATURELAYER" value=

'<cfoutput>#featureLayerName#</cfoutput>'>

<input type = "hidden" name = "ID" value =

"<cfoutput>#featureId#</cfoutput>">

<input type = "image" src = <cfoutput>#maprequest#</cfoutput> name = "MAP" alt="LiteView"> </form>

Each time that the form is submitted to map.cfm, a new map request is sent to the Autodesk MapGuide LiteView servlet to redraw the map. Each time that the form is submitted to the featureInfo.cfm, the feature_info request determines the ID of the feature that the user clicked. A new map request is sent to select the feature.

Understanding the ColdFusion Sample Application feature_info Request

A user can get information about a feature by clicking the map; see “Highlighting a Selected Map Feature” on page 19.

The ColdFusion Sample Application | 71

The ColdFusion sample application sends a request to the page featureInfo.cfm in the Feature Info frame. As this page is parsed, the map is cleared, a feature_info request is sent to Autodesk MapGuide LiteView, and the XML result is captured.

featureInfo.cfm has a custom embedded Java tag that represents the parseXml Java class (not a Java servlet). The Java class uses the XML, a style-sheet variable, and Xerces and Xalan to parse XML and XSL to create an HTML stream. The custom tag embeds the HTML, which describes the feature information, directly in the page. After the ColdFusion page is loaded completely, the onload tag calls the JavaScript function, showMapSelected():

function showMapSelected(layer,id) {

var selectFeatureRequest = "map.cfm?FEATURELAYER=" + escape (layer) + "&ID=" + id + "&BBOX=<cfoutput>#Form.bbox# </cfoutput>&MODE=identify"; parent.map.document.location = selectFeatureRequest;

}

The function showMapSelected() sends a request to map.cfm, which formulates the correct request to show the selected feature on the map.

The custom Java tag, embedded in the page, handles XML received by the CFM in response to a feature_info request. When the ColdFusion server reads this tag, it executes a small Java class method that accepts XML and a style sheet as input and returns HTML to the ColdFusion page.

The following diagram shows the process of requesting feature information.

72 | Chapter 4 Configuring and Using the Sample Applications

A feature_info request’s steps are:

1 The user starts the ColdFusion sample application and activates Select and

Identify mode, which highlights user-selected features and displays fea-

ture information about them.

2 The user clicks the map.

3 The sample application sends a post request to featureInfo.cfm.

4 The sample application builds the feature_info request for Autodesk

MapGuide LiteView.

5 The sample application sends the request.

6 The sample application captures and stores XML.

7 The sample application passes the XML file and XSL template file to

parseXml, the embedded Java class:

<CFX_parseXml

XML=#xmlFile# XSL=#xslFile#>

8 The parseXml class uses the Xerces and Xalan APIs to convert the XML

into HTML.

9 The sample application returns feature information coded in HTML to the

browser.

10 The sample application empties the feature_info frame.

Autodesk MapGuide LiteView

parseXml

featureInfo

HTM

XML

XSL

Xerces

Xalan

CFM

ColdFusion 4.5

The ColdFusion Sample Application | 73

Understanding the XML Parser

The parseXml class uses Xerces and Xalan parsers to format the XML into a style sheet to return to the browser as HTML. The file parseXml.java contains the following class definition:

parseXml.java class

import com.allaire.cfx.*; import org.apache.xalan.*; import org.apache.xerces.*; import java.io.*; import java.net.*;

public class parseXml implements CustomTag { public void processRequest( Request request, Response response ) throws Exception,java.io.IOException, java.net.MalformedURLException, org.xml.sax.SAXException {

// validate that required attributes were passed if ( !request.attributeExists( "XML" ) ||

!request.attributeExists( "XSL" ) )

{

throw new Exception(

"<FONT SIZE=4 COLOR=Red>Error</FONT><br>" +

"<B>(XML and XSL must be specified)</B>" ) ; } String strXML = request.getAttribute( "XML" ) ; String strXSL = request.getAttribute( "XSL" ) ;

// Use XSLTProcessorFactory to instantiate an XSLTProcessor. org.apache.xalan.xslt.XSLTProcessor processor =

org.apache.xalan.xslt.XSLTProcessorFactory.getProcessor();

// Create 3 objects for XSLTProcessor to do the transformation. org.apache.xalan.xslt.XSLTInputSource xmlSource =

new org.apache.xalan.xslt.XSLTInputSource (strXML);

org.apache.xalan.xslt.XSLTInputSource xslSheet =

new org.apache.xalan.xslt.XSLTInputSource (strXSL); StringWriter writer = new StringWriter(); org.apache.xalan.xslt.XSLTResultTarget xmlResult =

new org.apache.xalan.xslt.XSLTResultTarget(writer);

// Perform the transformation. processor.process(xmlSource, xslSheet, xmlResult); response.write(xmlResult.getCharacterStream().toString()); processor.reset(); processor = null;

74 | Chapter 4 Configuring and Using the Sample Applications

Note For information about the Xerces and Xalan parsers, visit the Apache Web site at http:\\xml.apache.org.

Understanding the Toolbar Implementation

The ColdFusion sample application uses JavaScript and image files to create the toolbar and implement its functions. Four of the six toolbar buttons (Select And Identify, Recenter, Zoom Out, and Zoom In) set a functional mode that remains in effect until the user clicks another toolbar button. After a mode is set, the function associated with the mode executes each time the user clicks the map.

The button images show the user which mode is active. The ColdFusion sample application uses JavaScript to swap images of the selected button, so it appears to be available or unavailable. The script sets a mode parameter in the get request to track which button the user clicked by submitting the get request to the CFM. Then, it sets the mode parameter in the post request to the same value as the mode in the get request. The active mode determines how a new bounding box is calculated and used in the request to Autodesk MapGuide LiteView.

xmlSource = null; xslSheet = null; writer = null; xmlResult = null; }

}

parseXml.java class

Select And Identify

Recenter Help

Unzoom Zoom Out Zoom In

The ColdFusion Sample Application | 75

When the user clicks any button other than Help, the ColdFusion sample application clears the mode.

Understanding the Select And Identify Implementation

When the user clicks the Select And Identify button and then clicks the map, the sample application highlights the selected feature and displays the feature ID, feature name, and feature URL in the Feature Info frame. The general steps that the sample application takes to select and identify a feature are:

1 When the user clicks the Select And Identify button, the variable mode in

the form that surrounds the map is set to selectidentify.

2 When the user clicks the map, the ColdFusion sample application sends a

request to the ColdFusion page, featureInfo.cfm, that resides in the feature information frame.

3 The sample application parses the page, clears the map, and sends a

feature_info request to Autodesk MapGuide LiteView.

4 A custom embedded Java tag that represents the Java class uses the

returned XML, a style sheet variable, and Xerces and Xalan parsers to create an HTML stream of feature information. This tag is contained by the featureInfo.cfm file.

5 The sample application embeds the feature information directly in the

featureInfo.cfm.

6 The sample application loads featureInfo.cfm, and the unload tag calls the

JavaScript function showMapSelected().

7 The function showMapSelected() sends a request to the ColdFusion map

page.

8 The ColdFusion map page formulates the correct request to Autodesk

MapGuide LiteView to show the selected feature on the map.

Understanding the Recenter Implementation

When the user clicks the Recenter button and then clicks the map, the browser displays a new image of the map with the bounding box centered at the clicked point. The general steps that the sample application takes to recenter a map are:

1 When the user clicks the map, the sample application submits the form to

the ColdFusion page.

2 The ColdFusion page requests a new image of the map with the bounding

box centered at the point that the user clicked.

76 | Chapter 4 Configuring and Using the Sample Applications

3 Autodesk MapGuide LiteView gets the new image from Autodesk

MapGuide Server, and returns it to the browser in PNG or JPEG format.

To recenter a map, the sample application uses an interpolation technique to center the bounding box within the frame specified by the MCS, not filling the frame if the map is non-square. For more information, see “Designing the Recenter Feature,” on page 78.

Using the Sample Help Files

After installing the ColdFusion sample application, the .htm Help files are place in <InstallFolder>/SampleApp/help.

You can use these Help files as a basis for creating Help for your own Autodesk MapGuide LiteView application. The files are HTML help files, HTML Help style sheets (.css files) images (.gif and .jpg files), and JavaScript (vhelp_scripts.js). To view the Help, you must use a Netscape Navigator or Microsoft Internet Explorer browser that is capable of interpreting the style sheets. Each HTML page references the JavaScript file to determine which browser the user is using and attach the appropriate stylesheet.

When the user clicks the Help button, a URL opens and displays Help for the sample application in a new window. The Help function executes once when the button is clicked.

Understanding the Zoom In Implementation

When the user clicks the Zoom In button, and then clicks the map, the sample application zooms in on the map by a zoom factor of 2. The ColdFusion sample application takes the following steps to zoom in on a map:

1 When the user clicks the map, the sample application sends a request to

Autodesk MapGuide LiteView with a new bounding box that is shifted, and decreased by the default zoom factor of two.

2 The new map image is created and sent back to the browser.

Understanding the Zoom Out Implementation

When the user clicks the Zoom Out button, and then clicks the map, the sample application zooms out of the map by a zoom factor of one-half.

Understanding the UnZoom Implementation

When the user clicks the Unzoom button, a get request is sent to the ColdFusion map template, the sample application clears selected features and the Feature Info frame, and activates Select And Identify. The mode parameter is cleared, so Unzoom is executed only once. The ColdFusion

Troubleshooting and Other Resources | 77

application page uses its default values for the parameters and returns the application to its initial state.

Troubleshooting and Other Resources

This section describes where to get more information about Autodesk MapGuide LiteView and MapGuide, where to find other sample applications, and how to solve the following common problems for the sample applications:

■ Autodesk MapGuide LiteView does not display maps by layer.

You can simulate the display of specific map layers by following instructions in “Displaying Data by Layer” on page 77

■ Autodesk MapGuide LiteView does not scale the map asymmetrically to

fix the pixel rectangle when the bounding box and pixel rectangle are different.

You can implement the Recenter function as described in “Designing the Recenter Feature,” on page 78 to solve this problem.

■ Autodesk MapGuide LiteView can’t read the GML DTD while offline or

behind a firewall.

You can use the FeatureInfoDTD parameter in the config.ini file to point to the local GML DTD that Autodesk MapGuide LiteView Setup installs; see “Accessing the GML DTD While Offline,” on page 80 to solve this problem.

Displaying Data by Layer

To simulate the display of specific map layers, you can create separate MWFs at the zoom magnification that you want for display, and link each MWF to layer buttons. You can determine the default bounding box of the layer by using Autodesk MapGuide Author and specifying the bounding box to simulate turning on layers.

To determine the default bounding box of a layer

1 Open Autodesk MapGuide Author and choose File ➤ Preferences.

2 Check Display Mouse Position.

78 | Chapter 4 Configuring and Using the Sample Applications

3 In the Units drop-down list, select the map units. Select Mapping Coordi-

nate System, for example.

4 Move the mouse pointer to the four extents of the map, and note the coor-

dinates that are displayed in the status bar. These coordinates are the bounding box.

The sample applications use only one map, but you can create a list of several maps and define the map name as a variable in the CFM.

Designing the Recenter Feature

The width and height parameters in a map request specify a rectangle of pixels into which Autodesk MapGuide LiteView should draw the resulting map. The Recenter feature centers the bounding box within the image width and height. To recenter correctly, the ratio of the X to Y bounding box coordinates must equal the ratio of the width to height of the image, that is:

MCSx / MCSy = image_width / image_height

The default bounding box of a ColdFusion sample application, for example, is set to the following values in map.cfm:

The width and height of the sample-application image is set to the following values in map.cfm:

Troubleshooting and Other Resources | 79

The ColdFusion sample application recenters the map correctly when the user invokes the Recenter function, because the ratio of the width to height matches the ratio of bounding-box coordinates:

ratio of image width to height = 500 / 480 = 1.04

ratio of bounding box X to Y coordinates = ((–150) – (–54)) / (0 – 92) = 1.04

To see the effect of mismatched ratios, change the ColdFusion sample application so that it no longer recenters correctly:

1 Open map.cfm.

2 Change the X coordinate of the maximum X of the bounding box from

–54 to –108, as shown here:

3 Open the ColdFusion sample application page index.htm.

4 Click the Recenter tool to set Recenter mode, and then click Mexico City.

The bounding box is not centered within the image width and height, because the ratio of the image width to height is 1.04, but the ratio of the

Mexico City

80 | Chapter 4 Configuring and Using the Sample Applications

bounding box X to Y coordinates is 0.48—a mismatch. This ratio is the result of the following calculation:

((–150) – (–54)) / 108 – 92 = 0.48

The following screen shows the effect of an uncentered bounding box.

Accessing the GML DTD While Offline

The FeatureInfoDTD parameter in the config.ini file is set by default to the URL where the OpenGIS Geography Markup Language (GML) DTD is published. Usually, XML processors such as the one built into Microsoft Internet Explorer 5 and later can read this DTD file. If the ColdFusion server that runs a sample application is running behind a firewall, however, the XML processor used by a sample application might not be able to access the DTD file (and trigger a timeout error).

Note For information about FeatureInfoDTD, see Chapter 3, “Configuring Autodesk MapGuide LiteView,” in the Autodesk MapGuide LiteView Servlet Admin- istrator’s Guide.

Mexico City off-center

Troubleshooting and Other Resources | 81

To access gmlfeature.dtd locally

1 Set the FeatureInfoDTD parameter in config.ini as follows:

FeatureInfoDTD=gmlfeature.dtd

Note ColdFusion saves the XML returned by the servlet as a file in the

<InstallFolder>\SampleApp folder. The gmlfeature.dtd also is located in this folder.

2 Save and close config.ini.

3 Restart the application-server service.

This procedure sets the FeatureInfoDTD parameter to the local copy of gmlfeature.dtd, causing the Java parser to search for the file in the local folder, eliminating the need to go outside the firewall to get resources.

SRS-to-WKT Mapping

Autodesk MapGuide LiteView Setup installs the file <InstallFolder>/liteview/CsToEpsgMap.xml. This file contains a mapping from ADSK:xxxx to well-

known toolkit (WKT) strings. You can extract these WKT strings and use them in your Autodesk MapGuide LiteView client applications to display WKT strings instead of ADSK:xxxx codes.

The following example entry from CsToEpsgMap.xml shows the mapping from ADSK:UTM-49S to a WKT.

PROJCS["UTM-49S",

GEOGCS["UTM-49S",

DATUM["",

SPHEROID["International 1924",6378388,297],

TOWGS84[0,0,0,0,0,0,0]],

PRIMEM["Greenwich",0],

UNIT["Degrees", 0.0174532925199433]],

PROJECTION["UTM"],

PARAMETER["central_meridian", 111],

PARAMETER["false_northing", 10000000],

PARAMETER["false_easting", 500000],

PARAMETER["zone", -49],

PARAMETER["scale_factor", 1],

PARAMETER["ADSK_quadrant", 0],

UNIT["METER", 1]]

</WktString>

</CsMapToEpsg>

</SRSMapping>

82 | Chapter 4 Configuring and Using the Sample Applications

Where to Get More Information

You can find MapGuide developer resources at the Autodesk MapGuide Web site at www.autodesk.com/mapguide. This site provides many examples of demo and actual customer applications that were developed with MapGuide. You also will find links to other resources, such as Autodesk MapGuide Viewer API Help, API examples, general product documentation, and discussion groups.

Note The Autodesk MapGuide Viewer API is not used to develop Autodesk MapGuide LiteView applications.

About Other Autodesk MapGuide LiteView Sample Applications

You’ll find other Autodesk MapGuide LiteView sample applications on the Autodesk MapGuide Web site http:\\www.mapguide.com\sampleapps. These applications include more features than do the sample applications provided with Autodesk MapGuide LiteView. There are two Facility Management samples. Take a look at the first Facility Management Application as you scroll down the Web page.

Troubleshooting and Other Resources | 83

The map frame is in the middle, the navigation frame is at the bottom, and a control frame is on the right. The application uses the control frame as a customized way to interact with the user. As a user, you can click an option under Legend or Select Name, and get dynamic information related to that option from a database. You can search for a person’s name in the list of names, and when the name is found, the application requests feature_info for the person, displays the feature information, and zooms in on the map to the room location occupied by that person.

In the navigation frame, the N-S-E-W icon is the panning control. The Zoom In, Zoom Out, and Recenter controls are implemented as radio buttons. As a user, you select the Identify radio button, and then click a room on the map. Autodesk MapGuide LiteView returns feature information for the room, and the Facilities Management application displays it in the browser.

About the Autodesk MapGuide LiteView Application Template

You can download a template for developing Autodesk MapGuide LiteView applications from the Autodesk MapGuide Web site, http://www.mapguide.com/sampleapps. The template consists of a set of Web pages, ColdFusion scripts, and graphic files that you can use as a starting point for developing your own Autodesk MapGuide LiteView application.

The template also includes an application builder that shows you how to create custom applications dynamically from the template files. The application builder prompts users for key application properties, such as the map and legend to display, and then it updates the file application.cfm and launches the application.

84 | Chapter 4 Configuring and Using the Sample Applications

To use the application builder

1 Download the template files from the Autodesk MapGuide Web site.

2 Map a virtual directory of your Web server to the template folder.

3 In a browser, navigate to the virtual directory and open start.cfm.

Troubleshooting and Other Resources | 85

4 Follow the onscreen instructions.

The application builder modifies the file application.cfm and launches your custom application. The following screen shows the default application and a sample world map.

Alternatively, you can customize the application by modifying the file application.cfm directly.

To customize the application manually

1 Using an HTML editor, modify the application.cfm file.

2 Using a browser, open the default.htm page.

The application opens, using the configuration values in application.cfm.

86 | Chapter 4 Configuring and Using the Sample Applications

Index

Active Server Pages (ASP), use with LiteView 2 Apache Xerces and Xalan 2 application.cfm 83–85 applications

architecture 7 sample 50 template for creating 83

Autodesk Web site 82

building an application 84

Capabilities metadata 36 capabilities of LiteView 2 CFM files 62

editing 62

modifying 66 CFX Jar path, setting 58–60 CFX tag, registering 61–62 client platforms, for ColdFusion sample

application 57

ColdFusion

modifying templates 66

tags used in ColdFusion sample application

ColdFusion sample application

basics 64

client platforms 57

ColdFusion tags used in 67

configuration 58

constituent files 56

feature_info request 70

feature_info request diagram 71

frames 65

Help files 76

image files 74

Java settings 58

map request 69

map request diagram 69

modifying CFM files 62

overview 55

registering XML parser 61

removing 64

removing files 64 requirements 57 starting 63 toolbar

Zoom In 76

Zoom Out 76 toolbar implementation 74 toolbar, Help 76 toolbar, Re-center 75 toolbar, Select And Identify 75 toolbar, UnZoom 76 use of JavaScript 74 using 64 XML 73

compliance with Web Map Service (WMS) 10 configuration

editing CFM 62 Java settings 58

configuration tasks, ColdFusion sample

application 58 context path 11 creating

feature_info requests 22 LiteView applications 6

map requests 10 CsToEpsgMap.xml 81 customer support 82 customizing the application 85

default symbol layer styles 21 default.htm 83–85 displaying feature information 23 displaying, data by layer 77 documentation

audience for 2

contents 2

copying text from 3 DTDs

feature 28

for feature_info responses 28

geometry 30

error handling 82

88 |Index

example applications 82

feature information, positioning 23 feature_info requests

ColdFusion sample application 70 ColdFusion sample application

implementation 70 creating 22 DTD for responses 28 example of 23 example response to 27 format of 22 interpreting responses to 26 overview 10 parameters 24 requirements 23 response DTDs 28 responses to 26

FeatureInfoDTD parameter 80 features of LiteView 2 files, removing ColdFusion sample application 64 formatting map requests 11

optional parameters 12

get and post requests 68 GetCapabilities request 36 GetFeatureInfo request 36, 47 GetMap request 36, 44 gmlfeature.dtd 28 gmlgeometry.dtd 30 group layers, selecting features from 17

Help files, for ColdFusion sample application 76 Help function 76 highlighting selected map features 19

images

transparent 46

<InstallFolder> 2

Java class, used for parsing XML 56 Java Server Pages (JSP), use with LiteView 2 Java servlets 4 Java settings 58 JavaScript, use with LiteView 2 JavaScript, used in ColdFusion sample

application 74

JPEG 5

converting MWFs to 4

JVM (Java Virtual Machine) path, setting 58–60

layers

displaying data by 77 for symbols 21 formatting names as request parameters 18

LAYERS parameter 15

restricted characters in 16

map requests 10

ColdFusion sample application 69 ColdFusion sample application

implementation 69 DTD for responses 30 example of 12 formatting 11 formatting layer names in 18 formatting optional parameters 12 overview 10 overview of parameters 13 parameters 13 requirements 22 responses to 11 SRS parameter 19 syntax of 11

map requests, creating 10 metadata 36 modifying, ColdFusion templates 66 MWF (Map Window File)

converting to JPEG 4 converting to PNG 4

MWF names, using in requests 15

online Help for ColdFusion sample application 76 Open GIS Consortium (OGC) 10 optional parameters of map requests 13

parameters

FeatureInfoDTD 80 non-WMS-compliant 10 of feature_info requests 24 of map requests 13 of requests, LAYERS 15 SRS 19 SYMBOLS 20, 21

Index | 89

parser, XML 73 parseXml 61

registering 61–62 Perl, use with LiteView 2 platforms, client (ColdFusion sample application)

57 PNG 5 PNG (Portable Network Graphics)

converting MWFs to 4 positioning feature information 23 post and get requests 68

Re-center implementation 75, 78 registering parseXml 61 requests

example of feature_info response 27

feature_info

creating 22 example of 23 format of 22 interpreting responses to 26 requirements 23 response DTD 28

feature_info, ColdFusion sample application

implementation 70 formatting of 11 formatting of optional parameters 12 get and post 68 GetCapabilities 36 GetFeatureInfo 36, 47 GetMap 36, 44 map

creating 10 example of 12 optional parameters 13 parameters of 13 requirements 22 syntax of 11 using layer names in 18

map, ColdFusion sample application

implementation 69 overview 10

requirements

for creating a map request 22 for LiteView development 2

responses

to feature_info requests

described 26 DTD 28 example 27

interpreting 26 to feature_info requests, DTD 28, 30 to map requests, described 11 to requests, overview 10

restricted characters

in the LAYERS parameter 16 in the SELECT parameter 18

sample applications

ColdFusion 50 others available 82

WMS Viewer 50 sample response, to feature_info request 27 Select And Identify implementation 75 SELECT parameter 17

using restricted characters in 19 selected map features, highlighting 19 selecting features

from group layers 17

multiple features 18 Service metadata 36 servlets 4 setting the SYMBOLS parameter 20 skills needed for LiteView development 2 software requirements

ColdFusion sample application 57 software requirements, ColdFusion sample

application 57 SRS parameter 19 start.cfm 84 support on Web 82 symbol layer styles, default 21 SYMBOLS parameter 20, 21 syntax of map requests 11 system requirements 57

template, for creating applications 83 templates, ColdFusion 66 tips and tricks 77 toolbar implementation 74 transparency 46

UnZoom implementation 76

Web Map Service (WMS) 10

compliance with 10 non-compliant parameters 10 specification, where to get 35

support for 4 Web-based samples 82 WKT (Well-Known Toolkit) 81 WMS Viewer sample application 50

configuring 55

90 |Index

extending 51 getting help 51 modifying 51 overview 50 starting 50

WMS. See Web Map Service (WMS)

Xalan and Xerces 2, 56, 72

XML 61, 72 XML parser 73

Java class 56

Zoom In implementation 76 Zoom Out implementation 76

Autodesk 15606-011408-9330 - MAPGUIDE R6.3 SITE LIC-UPG R6, MapGuide LiteView Developer's Manual

Specifications and Main Features

Frequently Asked Questions

User Manual