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

Autodesk MapGuide® Release 6

Developer’s Guide

15306-010000-5060 October 2001

Copyright © 2001 Autodesk, Inc.

All Rights Reserved

AUTODESK, INC. MAKES NO WARRANTY, EITHER EXPRESSED 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 Plan, 3D Props, 3D Studio, 3D
Studio MAX, 3D Studio VIZ, 3DSurfer, ActiveShapes, ActiveShapes (logo), Actrix, ADE, ADI, Advanced Modeling Extension, AEC
Authority (logo), AEC-X, AME, Animator Pro, Animator Studio, ATC, AUGI, AutoCAD, AutoCAD Data Extension, AutoCAD
Development System, AutoCAD LT, AutoCAD Map, Autodesk, Autodesk Animator, Autodesk (logo), Autodesk MapGuide,
Autodesk University, Autodesk View, Autodesk WalkThrough, Autodesk World, AutoLISP, AutoShade, AutoSketch, AutoSurf,
AutoVision, Biped, bringing information down to earth, CAD Overlay, Character Studio, Design Companion, Design Your World,
Design Your World (logo), Drafix, Education by Design, Generic, Generic 3D Drafting, Generic CADD, Generic Software,
Geodyssey, Heidi, HOOPS, Hyperwire, Inside Track, Kinetix, MaterialSpec, Mechanical Desktop, Multimedia Explorer, NAAUG,
ObjectARX, Office Series, Opus, PeopleTracker, Physique, Planix, Powered with Autodesk Technology, Powered with Autodesk
Technology (logo), RadioRay, Rastation, Softdesk, Softdesk (logo), Solution 3000, Texture Universe, The AEC Authority, The Auto
Architect, TinkerTech, VISION*, WHIP!, WHIP! (logo), Woodbourne, WorkCenter, and World-Creating Toolkit.

The following are trademarks of Autodesk, Inc., in the USA and/or other countries: 3D on the PC, 3ds max, ACAD, Advanced User
Interface, AME Link, Animation Partner, Animation Player, Animation Pro Player, A Studio in Every Computer, ATLAST, Auto­Architect, AutoCAD Architectural Desktop, AutoCAD Architectural Desktop Learning Assistance, AutoCAD Learning Assistance,
AutoCAD LT Learning Assistance, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk Animator
Clips, Autodesk Animator Theatre, Autodesk Device Interface, Autodesk Inventor, Autodesk PhotoEDIT, Autodesk Software
Developer's Kit, Autodesk Streamline, Autodesk View DwgX, AutoFlix, AutoSnap, AutoTrack, Built with ObjectARX (logo),
ClearScale, Colour Warper, Combustion, Concept Studio, Content Explorer, cornerStone Toolkit, Dancing Baby (image), Design
2000 (logo), DesignCenter, Design Doctor, Designer's Toolkit, DesignProf, DesignServer, DWG Linking, DXF, Extending the
Design Team, FLI, FLIC, GDX Driver, Generic 3D, gmax, Heads-up Design, Home Series, i-drop, Kinetix (logo), ObjectDBX,
onscreen onair online, Ooga-Chaka, Photo Landscape, Photoscape, Plasma, Plugs and Sockets, PolarSnap, Pro Landscape,
Reactor, Real-Time Roto, Render Queue, SchoolBox, Simply Smarter Diagramming, SketchTools, Sparks, Suddenly Everything
Clicks, Supportdesk, The Dancing Baby, Transform Ideas Into Reality, Visual LISP, Visual Syllabus, VIZable, Volo, and Where Design
Connects.

Third Party Trademarks

Apple and Macintosh are trademarks of Apple Computer, Inc., registered in the U.S. and other countries.
ColdFusion is a registered trademark of Macromedia, Inc. All rights reserved.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United
States and other countries.
Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corporation in the United States and
other countries.
Microsoft and ActiveX are registered trademarks of Microsoft Corporation in the United States and/or other countries.
All other brand names, product names or trademarks belong to their respective holders.

Third Party Software Program Credits

Copyright © 2001 Microsoft Corporation. All rights reserved.
Portions of this product are distributed under license from D.C. Micro Development, © Copyright D.C. Micro Development. All
rights reserved.
InstallShield ™ Copyright © 2001 InstallShield Software Corporation. All rights reserved.

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.

12345678910

Contents

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

What’s New in Release 6 . . . . . . . . . . . . . . . . 8

Autodesk DWG Data Source Support . . . . . . . . . . 8

Enhanced Support for Map Redraw Operations . . . . . . . 8

Symbol Bitmap Support . . . . . . . . . . . . . . . 8

Map Mode Retrieval Support . . . . . . . . . . . . . 9

Java Edition Platform Support Changes . . . . . . . . . . 9

Before You Begin . . . . . . . . . . . . . . . . . . . 9

Familiarity with Autodesk MapGuide . . . . . . . . . . 9

Programming and Scripting Languages . . . . . . . . . 10

Your Audience. . . . . . . . . . . . . . . . . 10

User Help . . . . . . . . . . . . . . . . . . 11

About the Autodesk MapGuide Viewer API . . . . . . . . . 11

Autodesk MapGuide Viewer API Help . . . . . . . . . 13

Autodesk MapGuide Web Site . . . . . . . . . . . . 13

What Is an Autodesk MapGuide Viewer API Application . . . . . 13

Viewing Maps . . . . . . . . . . . . . . . . . 14

Querying and Updating Data . . . . . . . . . . . . 14

Creating an Autodesk MapGuide Viewer API Application . . . . . 15

Chapter 2 Displaying Maps . . . . . . . . . . . . . . . . 17

Overview . . . . . . . . . . . . . . . . . . . . 18

Map Display for ActiveX Control and Plug-In. . . . . . . . . 20

Linking to a Map . . . . . . . . . . . . . . . . 20

Embedding a Map . . . . . . . . . . . . . . . 22

Map Display for the Java Edition . . . . . . . . . . . . . 24

Map Display for Autodesk MapGuide LiteView . . . . . . . . 26

Installing Viewers on Client Machines . . . . . . . . . . . 27

Chapter 3 Accessing Maps . . . . . . . . . . . . . . . . 31

Overview . . . . . . . . . . . . . . . . . . . . 32

Map Access for ActiveX Control and Plug-In . . . . . . . . . 32

Required Software for Autodesk MapGuide Viewer Plug-In. . . 34

iii

Map Access for the Java Edition . . . . . . . . . . . . . 35

Map Access from HTML . . . . . . . . . . . . . . 35

Map Access Using Java . . . . . . . . . . . . . . 38

Required Software for the Java Edition . . . . . . . . . 39

Java Edition Differences. . . . . . . . . . . . . . 39

Communicating with the Plug-In from a Java Applet . . . . . . 40

Accessing Secure Data . . . . . . . . . . . . . . . . 43

Handling Busy State and Map Refresh . . . . . . . . . . . 43

About the Busy State . . . . . . . . . . . . . . . 43

Controlling Map Refresh Operations. . . . . . . . . . 45

Handling Errors . . . . . . . . . . . . . . . . . . 47

Getting Error Codes . . . . . . . . . . . . . . . 47

Checking for Incorrect Argument Types . . . . . . . . 48

Debugging an Application . . . . . . . . . . . . . . . 48

Chapter 4 Working with Map Layers, Map Features, and Printing . . . 49

Overview . . . . . . . . . . . . . . . . . . . . 50

Working with Map Layers . . . . . . . . . . . . . . . 50

Counting Map Layers . . . . . . . . . . . . . . 50

Listing Map Layers . . . . . . . . . . . . . . . 51

Adding a Map Layer . . . . . . . . . . . . . . . 53

Linking Map Layers . . . . . . . . . . . . . . . 53

Toggling Map Layer Visibility On and Off . . . . . . . . 55

Working with Map Features . . . . . . . . . . . . . . 56

Getting Keys of Selected Map Features . . . . . . . . . 56

Getting Coordinates of a Selected Map Feature . . . . . . 58

Invoking Select Radius Mode . . . . . . . . . . . . 61

Zooming In on Selected Features . . . . . . . . . . . 61

Counting Map Features . . . . . . . . . . . . . . 62

Working with Printing . . . . . . . . . . . . . . . . 64

Setting the Print Priority . . . . . . . . . . . . . 65

Enabling the Print Events . . . . . . . . . . . . . 66

Positioning Page Elements with Page Coordinate System Units . 67

Adding Custom Page Elements . . . . . . . . . . . 68

Chapter 5 Handling Events . . . . . . . . . . . . . . . . 69

Overview . . . . . . . . . . . . . . . . . . . . 70

Working with Event Handlers. . . . . . . . . . . . . . 70

Browser Differences . . . . . . . . . . . . . . . 71

Setting Up Event Handlers . . . . . . . . . . . . . . . 72

Plug-In and Java Edition Event Handlers . . . . . . . . 72

ActiveX Control Event Handlers . . . . . . . . . . . 75

Plug-In and ActiveX Control Event Handlers . . . . . . . 75

iv | Contents

Writing Event Handlers . . . . . . . . . . . . . . . . 78

Page Setup Event Handler Example. . . . . . . . . . . 79

Print Event Handler Example . . . . . . . . . . . . 81

Plug-In Event Handler Example . . . . . . . . . . . . 83

Chapter 6 Using Reports to Query and Update Data Sources . . . . . 85

Overview . . . . . . . . . . . . . . . . . . . . . 86

How Reports Are Generated . . . . . . . . . . . . . 86

Specifying the Report Script . . . . . . . . . . . . . 86

The Request . . . . . . . . . . . . . . . . . . 87

Launching the Report . . . . . . . . . . . . . . . 87

Introducing ColdFusion and ASP . . . . . . . . . . . . . 88

Creating Report Scripts with ColdFusion . . . . . . . . . . . 89

Listing File Contents with ColdFusion. . . . . . . . . . 89

Querying and Displaying Data via the Map with ColdFusion . . 92

Modifying a Database via the Map with ColdFusion . . . . 102

Creating Report Scripts with ASP . . . . . . . . . . . . 109

Summary of ASP Objects, Components, and Events . . . . 110

Listing File Contents with ASP . . . . . . . . . . . 111

Querying and Displaying Data via the Map with ASP . . . . 115

Modifying a Database via the Map with ASP . . . . . . . 125

Chapter 7 Applications . . . . . . . . . . . . . . . . . 135

Overview . . . . . . . . . . . . . . . . . . . . 136

Custom Redlining Application . . . . . . . . . . . . . 136

Redlining Example Code . . . . . . . . . . . . . 137

Municipal Application . . . . . . . . . . . . . . . 140

Municipal Application Example Code . . . . . . . . . 141

Facility Management Application . . . . . . . . . . . . 156

Facilities Management Application Example Code . . . . . 157

DWG Filtering Application . . . . . . . . . . . . . . 164

Understanding Layers in Autodesk MapGuide . . . . . . 165

Changing Map Layer Data Source Properties . . . . . . . 165

DWG Filtering Application Example Code . . . . . . . 166

SDF Component Toolkit Applications . . . . . . . . . . . 171

Updating SDF Files—an ASP Example . . . . . . . . . 171

Converting to an SDF File—a Visual Basic Example . . . . 181

Getting SDF File Information—a Visual Basic Example . . . 188

Copying an SDF File—a Visual Basic Example . . . . . . 196

Index . . . . . . . . . . . . . . . . . . . . . . . . 203

Contents | v

vi

Introduction

1

The Autodesk MapGuide® product suite provides you

with all the tools you need to create, publish, and display

maps and associated attribute data over the Web. The

Autodesk MapGuide Developer’s Guide is a complete guide

to Autodesk MapGuide customization and development

features. This chapter introduces Autodesk MapGuide

application development, and describes how to use

Autodesk MapGuide

applications.

®

Viewer API to develop such

■ What’s new in Release 6

■ Before you begin

■ About the Autodesk

MapGuide Viewer API

■ What is an Autodesk
MapGuide Viewer API
application

■ Creating an Autodesk
MapGuide Viewer API
application

7

What’s New in Release 6

This release of the Autodesk MapGuide Viewer API includes one new object
and several new and changed methods and properties to support new and
enhanced features. For detailed information about the new object, and the
methods and properties that were added or changed, choose Help ➤
Contents ➤ What’s New in the Autodesk MapGuide Viewer API Help.

Autodesk DWG Data Source Support

Several changes and additions have been made to Autodesk MapGuide and
the Autodesk MapGuide Viewer API to support Autodesk drawing (DWG)
data sources. The most significant addition is a new MGDwgDataSources
object with several methods and properties to get and set DWG values of
Autodesk MapGuide map layers. Also, a new MGMapLayerSetup method
(getDwgDataSources) and a property (MGDwgDataSources) were added.
Two MGMapLayerSetup methods (getDataFile and setDataFile)
methods and one property (DataFile) were also changed to support DWG
data sources. See “DWG Filtering Application” on page 164 for an example
of working with DWG data sources.

Enhanced Support for Map Redraw Operations

Two new MGMap methods (getIntermediateUpdatesEnabled and
setIntermediateUpdatesEnabled) and a new property

(IntermediateUpdatesEnabled) were added to allow more control over
how frequently, and under what conditions, the Autodesk MapGuide Viewer
redraws a map. Maps are now updated every 1.5 seconds by default. This
allows the end user to view changes to the map as it is being drawn instead
of waiting until the entire map is rendered. See “Handling Busy State and
Map Refresh” on page 43 for information about controlling map refresh
operations.

Symbol Bitmap Support

Changes were made to two MGSymbolAttr methods (setRotation and
setSymbol) and two properties (Rotation and Symbol) to support bitmaps

in symbols.

8 | Chapter 1 Introduction

Map Mode Retrieval Support

One new MGMap method (getMode) and one new property (Mode) were
added to allow retrieval of a map’s mode, such as zoom, pan, and so on.

Java Edition Platform Support Changes

Autodesk MapGuide Viewer, Java™ Edition does not run if you are using
Microsoft

2.2. You need to upgrade to MRJ 2.2.4 or later.

For a complete list of supported platforms, including browsers and operating
systems, refer to “Autodesk MapGuide Viewer Requirements” in Chapter 1,

“Introduction,” in the Autodesk MapGuide User’s Guide.

®

Internet Explorer® 5.x with Macintosh® Runtime for Java (MRJ)

Before You Begin

Before you can begin developing with Autodesk MapGuide, you need to
know how to use Autodesk MapGuide and the programming and scripting
languages you use to create Autodesk MapGuide web applications. Equally
important, you need to know who your users are and what they need, as well
as how to deliver help about your applications.

Familiarity with Autodesk MapGuide

You need to be very familiar with Autodesk MapGuide. In particular, you
should read the first few chapters of the Autodesk MapGuide User’s Guide to
make sure you understand the product, especially emphasizing the following
sections:

■ Chapter 2, “Understanding Autodesk MapGuide.” Read this chapter care-

fully, with particular attention to the sections on how the components
work together, application development components, and what applica­tion development is.

■ Chapter 3, “Designing Your System.” Pay particular attention to the sec-

tions on security, architecture and performance, and choosing a
Viewer/browser environment.

The more you understand about the Autodesk MapGuide components and
how they work together, the easier it will be for you to comprehend the
examples in this book and come up with unique solutions on your own.

Before You Begin | 9

Programming and Scripting Languages

You’ll need to be familiar with one or more of the following programming
languages or toolkits to develop Autodesk MapGuide web applications.
MapGuide applications can include a variety of capabilities including
customized interface (toolbar, etc.), report generation, processing of
redlining markup, server-side processing of SDF files, Dynamic Map
Authoring, and more.

■ Use Java, JavaScript, JScript, Visual Basic, or VBScript with the Autodesk

MapGuide Viewer API to develop applications that programmatically
access and control Autodesk MapGuide Viewer. This document covers
what you need to know to develop such applications.

■ Use Macromedia

another third-party application to create custom reports. For information
about creating reports, see Chapter 6, “Using Reports to Query and Update
Data Sources.”

®

ColdFusion®, Microsoft® Active Server Pa ges (ASP), or

■ Use the SDF Component Toolkit to create server-side scripts that dynam-

ically update SDF files posted on an Autodesk MapGuide

®

Server. For more

information about using this toolkit, see “SDF Component Toolkit Appli­cations” on page 171 and refer to the SDF Component Toolkit Help.

■ Use the Autodesk MapGuide Viewer API to process redlining data and

update your data sources. For more information about working with
redlining data, see “Custom Redlining Application” on page 136.

■ Use the Dynamic Authoring Toolkit to build XML-based applications for

dynamic map solutions. For more information about this toolkit, refer to
the Dynamic Authoring Toolkit Developer’s Guide.

Your Audience

As with all development, the most important aspect of designing your appli­cation is asking yourself, “What do my users need?” Talk to the people who
will be using your application and find out how they will be using it. What
tasks will they want to perform? Will they need redlining? Are they computer
savvy, or will you need to guide them through basic usage of your applica­tion? Do they have much domain knowledge? It’s critical that you find out
what tasks your users will need to perform, as well as their knowledge of
those tasks.

10 | Chapter 1 Introduction

User Help

If you want to provide information about your application that users can
readily access, you can develop your own set of Help pages. You can then set
up the map to point to your customized Help system instead of the default
Autodesk MapGuide Viewer Help when users click the Help button or access
Help from the popup menu. For more information, refer to the Autodesk
MapGuide Help.

About the Autodesk MapGuide Viewer API

The Autodesk MapGuide Viewer API allows you to customize the way in
which someone using Autodesk MapGuide Viewer interacts with a map. You
can also create a stand-alone version of the Autodesk MapGuide Viewer that
displays maps without the use of a Web browser.

Autodesk MapGuide Viewer comes in three different types: Autodesk
MapGuide Viewer ActiveX Control, Autodesk MapGuide Viewer Plug-In, and
Autodesk MapGuide Viewer, Java Edition. These Viewer types are sometimes
referred to as Viewer versions within the Help and the documentation. Be
careful to not confuse this usage with Autodesk MapGuide release versions.
Each Autodesk MapGuide Viewer type exposes a programming interface that
you can use to programmatically access and manipulate its functionality.

For example, you could create an application that displays a map in one
frame and a form in another. In the form, you might have controls such as
buttons and list boxes that use API methods to alter or redraw the map. Or,
you might put the map and controls on a single page, as shown in the
following illustration. This application consists of a map, a form listing map
features, and a number of custom image buttons on the HTML page. Users
can select a city from the list box, and then click a button to zoom to that
city.

About the Autodesk MapGuide Viewer API | 11

Sample application with custom buttons

You could also code your application to update the form, display status infor­mation, or change the appearance of buttons as users select or double-click
specific features on the map. This two-way interaction between the map and
controls on the Web page allows you to create very powerful applications.

In this context, an Autodesk MapGuide Viewer application is a Web page
containing one or more maps, each of which is displayed in a separate
instance of the Autodesk MapGuide Viewer. The Web page can also have
frames, buttons, controls, graphics, and so on for querying and controlling
the map and its data. In most cases, you will write your application code
within one or more HTML pages using one of the supported languages (refer
to “Choosing a Viewer/Browser Environment” in the Autodesk MapGuide
User’s Guide).

12 | Chapter 1 Introduction

Autodesk MapGuide Viewer API Help

For complete information about the Autodesk MapGuide Viewer API, refer to
Autodesk MapGuide Viewer API Help, available from the Autodesk MapGuide
CD and the Autodesk MapGuide documentation page at the following web
site: www.autodesk.com/mapguidedocs. The Autodesk MapGuide Viewer API
Help provides descriptions of all of the Autodesk MapGuide Viewer API
objects, methods, properties, and events, and it includes sample applications
that you can use to get a quick start.

Autodesk MapGuide Web Site

You can find additional information about Autodesk MapGuide develop­ment on the Autodesk MapGuide Web site at www.autodesk.com/mapguide.
The site provides many examples of applications developed with Autodesk
MapGuide, both demo applications and real customer sites. You will also
find links to resources, such as Autodesk MapGuide Viewer API Help, API exam­ples, general product documentation, and discussion groups.

What Is an Autodesk MapGuide Viewer API
Application

An Autodesk MapGuide Viewer API application can be as simple as an HTML
page that displays an embedded map window file (MWF), or it can be as
complex as a CGI application, coded in C++, that modifies data files on the
server and refreshes the browsers of everyone viewing the map. Usually it is
something between the two, such as a map embedded in a Web page with
buttons and other controls on it that interact with the map.

The following sections describe several of the tasks your Autodesk MapGuide
application can perform.

What Is an Autodesk MapGuide Viewer API Application | 13

Viewing Maps

The m ost co m m on developm en t goal is t o allow Auto desk Map G uide Vie w er
users to view and interact with maps. You can do this by embedding a map
in an HTML page, in which case the Autodesk MapGuide Viewer runs within
the user’s Web browser to display the map, or you can run the Autodesk
MapGuide Viewer from within a stand-alone application that you create.
With either approach, you will use the Autodesk MapGuide Viewer API to
interact with the map. For example, you might create a button that refreshes
a map or add text boxes that allow the user to add data to the map.

Querying and Updating Data

Beyond viewing maps, users want to retrieve data to answer questions. This
includes selecting map features and running reports on them, such as
selecting power poles and seeing when they were last serviced. You set up
these reports using Macromedia ColdFusion, Microsoft Active Server Pages
(ASP), or another server-side scripting language. Additionally, you can use
these scripts to enable the user to update the data. For example, you could
display the date of last service in a text field, where the technician in the field
could update it. Your script would then take the technician’s date and update
the source database, so that all other technicians viewing that power pole on
the map would see the new date of last service. For more information about
reports, see Chapter 6, “Using Reports to Query and Update Data Sources.”

You can also enable users to mark up the maps to edit the spatial data, such
as correcting the location of a fire hydrant by drawing its correct location on
the map. This process is called redlining. Autodesk MapGuide provides APIs
that allow you to add redlining functionality to your map. You can then
create a server-side script that retrieves the redlining data, processes it, and
updates the source data. For more information about redlining, see “Custom
Redlining Application” on page 136. If your source data is in SDF files, you
can use the SDF Component Toolkit to update the SDFs directly when
redlining. For more information about working with SDF files, see “SDF
Component Toolkit Applications” on page 171.

14 | Chapter 1 Introduction

Creating an Autodesk MapGuide Viewer API
Application

The following table summarizes tasks involved when creating an Autodesk
MapGuide Viewer API application. For examples of real-world applications,
also see Chapter 7, “Applications.”

Application Type Task For more information...

Simple
Applications

Advanced
Applications

Display maps by either
linking to or embedding
them in an HTML page

Programmatically access
and manipulate maps,
map layers, and map
features

Respond to Autodesk
MapGuide Viewer events

Query and update data
sources using reports

See Chapter 2, “Displaying
Maps”

See Chapter 3, “Accessing
Maps” and Chapter 4, “Work-
ing with Map Layers, Map Fea­tures, and Printing”

See Chapter 5, “Handling
Events”

See Chapter 6, “Using Reports
to Query and Update Data
Sources”

Creating an Autodesk MapGuide Viewer API Application | 15

16

Displaying Maps

2

This chapter describes how to link to or embed a map in

a Web page for display in Autodesk MapGuide

ActiveX Control, Autodesk MapGuide Viewer Plug-In, or

Autodesk MapGuide Viewer, Java Edition. Once your

application can display a map, you can access the map

programmatically, as described in Chapter 3, “Accessing

Maps.”

®

Viewer

■ Overview

■ Map display for ActiveX

Control and Plug-In

■ Map display for the Java
Edition

■ Map display for Autodesk
MapGuide LiteView

■ Installing Viewers on client
machines

17

Overview

The process of displaying a map involves linking to or embedding a specific
map in a Web page. The Autodesk MapGuide Viewer installed on each user
machine runs automatically to display the map. This means that your users
can view the same map with one of three Autodesk MapGuide Viewers
(Autodesk MapGuide Viewer ActiveX Control, Autodesk MapGuide Viewer
Plug-In, or Autodesk MapGuide Viewer, Java Edition), depending on which
ones you support. If your users are unable to download or install an Autodesk
MapGuide Viewer, or if they do not need query or more advanced function­ality provided by Autodesk MapGuide Viewers, they can use Autodesk
MapGuide
tion, see “Map Display for Autodesk MapGuide LiteView” on page 26.

The Autodesk MapGuide Viewers you choose to support depend on the
browser operating environment of your users. The programming or scripting
languages you use to develop your applications depend on the Autodesk
MapGuide Viewers you support. For a detailed discussion of these options,
refer to “Choosing a Viewer/Browser Environment” in the Autodesk
MapGuide User’s Guide.

The following table summarizes the combinations supported by Autodesk
MapGuide.

®

LiteView instead. For more information about this viewing solu-

18 | Chapter 2 Displaying Maps

Browser/Viewer Configurations

Operating
System

Windows

Browser Client-Side

Viewer

Internet Explorer Autodesk

MapGuide Viewer
ActiveX Control

Autodesk
MapGuide Viewer,
Java Edition

Netscape
Navigator

None
(stand-alone
application)

Autodesk
MapGuide Viewer
Plug-In

Autodesk
MapGuide Viewer,
Java Edition

Autodesk
MapGuide Viewer
ActiveX Control

Programming
or Scripting
Language

HTML, VBScript,
JScript, JavaScript

HTML, JScript,
JavaScript, Java

HTML, JavaScript

HTML, JavaScript,
Java

Visual Basic

Mac OS

Solaris

Internet Explorer Autodesk

MapGuide Viewer,
Java Edition

Netscape
Navigator

Autodesk
MapGuide Viewer,
Java Edition

HTML, Java

HTML, JavaScript,
Java

Overview | 19

Map Display for ActiveX Control and Plug-In

To display your map with Autodesk MapGuide Viewer ActiveX Control
and/or Autodesk MapGuide Viewer Plug-In, you can either:

■ Link to the map, or

■ Embed the map (the map runs inside a Web browser)

Linking to a Map

You can display a map by creating a link to the map from an HTML page.
The, when the user clicks the link, the map displays full screen. Note that the
browser displays the map by itself, not as part of an HTML page.

Create the link just like any other link in HTML, using the <A> tag with the
HREF parameter. Set the HREF value to the URL of your Autodesk MapGuide
Server, along with the maps directory alias and the MWF file for the map:

<A HREF="http://www.yourserver.com/maps/usa.mwf">United States
Map</A>

Linked map

20 | Chapter 2 Displaying Maps

Displaying a Linked Map in a Different Window or Frame

To display the linked map in a different window or frame, use the TARGET
parameter. If necessary, open the second window or frame so that the orig­inal document can continue to be displayed. For example:

<A HREF="http://www.mapguide.com/maps/usa.mwf"

TARGET="MAPAREA">United States Map</A>

This displays the usa.mwf map in a Web browser window called MAPAREA.
The TARGET parameter can also specify the name of a frame.

Displaying a Specific Area of the Map

In an Autodesk MapGuide Viewer, you can adjust the view of the map
window so that it displays only the area you want.

To display a specific area of a map

1 Right-click over the map to display the popup menu, and then use the

Zoom commands or Pan to display the area of the map you want.

2 Right-click again, and then choose Copy ➤ As URL to copy the map’s URL

to the clipboard.

3 In your HTML document, choose Edit ➤ Paste to paste the URL into the

HREF parameter of the anchor tag. For example:

<A HREF="http://www.mapguide.com/maps/usa.mwf?Lat=37.81
&Lon=-122.37&Width=20.0&Units=Mi&ext=.mwf">United States Map</A>

This displays the San Francisco area. For a list of the parameters that control
the way the map is displayed when linked to or embedded in an HTML page,
choose Help ➤ Contents ➤ Advanced Topics ➤ URL Parameters in the
Autodesk MapGuide Viewer Help.

Map Display for ActiveX Control and Plug-In | 21

Embedding a Map

A second way to display a map is to embed it in an HTML page. Embedding
a map displays it with the rest of the information on that page.

To embed the map, use the EMBED (for Netscape Navigator) or OBJECT (for
Microsoft Internet Explorer) tag in the page.

To ensure that both Netscape Navigator and Internet Explorer can access the
map, use both tags. For example:

<OBJECT ID="map" WIDTH=300 HEIGHT=200 CLASSID="CLSID:62789780-B744­11D0-986B-00609731A21D">

<PARAM NAME="URL" VALUE="http://www.mapguide.com/maps/usa.mwf">
<EMBED SRC="http://www.mapguide.com/maps/usa.mwf" NAME="map"

WIDTH=300 HEIGHT=200>

</OBJECT>

For a list of the parameters that control the way the map is displayed when
it is linked to or embedded in an HTML page, choose Help ➤ Contents ➤
Advanced Topics ➤ URL Parameters in the Autodesk MapGuide Viewer Help. Be
sure that the values you use are the same for both the OBJECT and EMBED
parameters.

The following screen shows the embedded map.

22 | Chapter 2 Displaying Maps

Embedded map

Embedding a Map in a Frame-Based Page

To display a map within a frame-based page, use the <FRAME> tag to refer­ence an HTML document that embeds the map. When you display a map
within a frame, the size of the map can grow and shrink as the window is
resized. To see an example of a map within a simple frame-based HTML page,
choose Help ➤ Contents ➤ Examples Basic ➤ Simple Frameset example in
the Autodesk MapGuide Viewer API Help.

The following is an example of an HTML page for frame set layout:

<HTML>
<HEAD>
<TITLE>Frame Layout</TITLE>
</HEAD>

<FRAMESET ROWS="70%,*">

<FRAME SRC="map.htm" NAME="myFrame" SCROLLING=no

MARGINHEIGHT=0 MARGINWIDTH=0>

<FRAME SRC="list.htm" NAME="ListFrame">

</FRAMESET>

</HTML>

Map Display for ActiveX Control and Plug-In | 23

Here is an example HTML page for map.htm referenced by the frame set:

<HTML>
<HEAD>
<TITLE>Map.htm</TITLE>
</HEAD>
<BODY>
<OBJECT ID="map" WIDTH=100% HEIGHT=100%

CLASSID="CLSID:62789780-B744-11D0-986B-00609731A21D"
CODEBASE="ftp://adeskftp.autodesk.com/webpub/mapguide/ver6/

mgaxctrl.cab#Version=6,0,x,x">
<PARAM NAME="URL" VALUE="http://www.mapguide.com/maps/usa.mwf">
<PARAM NAME="ToolBar" VALUE="OFF">
<EMBED SRC="http://www.mapguide.com/maps/usa.mwf?ToolBar=OFF"

NAME="map" WIDTH=100% HEIGHT=100% BORDER=0>

</OBJECT>
</BODY>
</HTML>

Note that in your applications, you should change the release (#Version)
number from 6,0,x,x to the actual release number of Autodesk MapGuide
you are using. You can find the release number using the Help ➤ Help About
menu command in the user interface or the MGMap.aboutDlg method.

Map Display for the Java Edition

Using Autodesk MapGuide Viewer, Java Edition, you cannot display a map
by linking to it; you must embed it. The following are ways to embed a map:

■ Embed Autodesk MapGuide Viewer, Java Edition in the HTML page where

the map is embedded (runs inside a Web browser).

■ Wrap a Java applet around Autodesk MapGuide Viewer, Java Edition (can

run inside or outside of a Web browser). For information about applet
wrappers, see “Map Access Using Java” on page 38.

If you are using Autodesk MapGuide Viewer, Java Edition, you cannot link to
a map. Instead, you must embed the map in the HTML page. To do this, use
the <APPLET> tag and be sure to enter it directly into the HTML. Do not use

document.write statements. For example, you should use:

<APPLET NAME="map" WIDTH=300...

and so on, and not use:

document.write('<APPLET');
document.write(' NAME=map');

...

Note Do not specify the height and width parameters in percentages, because
percentages are unsupported in Internet Explorer on the Macintosh.

24 | Chapter 2 Displaying Maps

To display your map with Autodesk MapGuide Viewer, Java Edition

1 Start with the standard HTML <APPLET> tag.

2 Set the

CODE parameter to the path to the MGMapApplet.class file in the

com.autodesk.mgjava package. This package is where the API for Autodesk

MapGuide Viewer, Java Edition resides. You can find this package in the
mgjava.jar archive file, which contains all Autodesk MapGuide Viewer,
Java Edition class files for Windows, Macintosh, or Solaris systems. There
is also an mgjava.cab file for Windows only. To download these files,
choose Help ➤ Contents ➤ Plug-In/Java Edition Downloads in the
Autodesk MapGuide Viewer API Help. The MGMapApplet obj e ct provided b y
the MGMapApplet.class file implements the MGMap object interface for
Autodesk MapGuide Viewer, Java Edition. Setting the CODE parameter to
MGApplet instantiates Autodesk MapGuide Viewer, Java Edition.

3 Set the VALUE parameter to the URL of your Autodesk MapGuide Server

and the path to the MWF file for the map. For example:

<HTML>
<HEAD>
<TITLE> Autodesk MapGuide Viewer, Java Edition Example</TITLE>
</HEAD>
<BODY>

<CENTER>
<H2>Simple Invocation of Installed Autodesk MapGuide

Applet</H2>

<APPLET WIDTH=300 HEIGHT=200 ALIGN="baseline"

CODE="com/autodesk/mgjava/MGMapApplet.class">
<PARAM NAME="mwfURL"

VALUE="http://www.mapguide.com/maps/usa.mwf">
</APPLET>
</CENTER>

</BODY>
</HTML>

Map Display for the Java Edition | 25

Map Display for Autodesk MapGuide
LiteView

Autodesk MapGuide LiteView is a platform-independent, server-side viewing
solution that delivers maps in the form of static raster images to client Web
browsers from your Web page. It is not a type of Autodesk MapGuide Viewer.
Autodesk MapGuide LiteView is useful when users need only to display the
map and do not need the more advanced queries and other functionality of
Autodesk MapGuide Viewer. Also, since LiteView is a server-side solution,
users do not have to download and install one of the Autodesk MapGuide
Viewer types to view your maps.

To display a map using Autodesk MapGuide LiteView, you send a URL
request that returns the map displayed as a raster image file in the browser.
Note that you do not use the Autodesk MapGuide Viewer API with Autodesk
MapGuide LiteView. For complete information on implementing Autodesk
MapGuide LiteView, refer to the Autodesk MapGuide LiteView Developer’s
Guide. The following table summarizes the supported configurations for
Autodesk MapGuide LiteView:

Autodesk MapGuide LiteView Configurations

Operating
System

Windows

Mac OS

Solaris

Browser Server-Side

Any browser that
supports PNG file
format

Viewing Solution

Autodesk MapGuide
LiteView

Programming
or Scripting
Language

ColdFusion (CF),
Active Server Pages
(ASP), Java Server
Pages (JSP) or Perl

26 | Chapter 2 Displaying Maps

Installing Viewers on Client Machines

If users accessing your Web site don’t have an Autodesk MapGuide Viewer
installed on their system, they need to download one in order to view the
map you have displayed in the Web page. You can include code in your
HTML file that automatically detects whether or not the user has Autodesk
MapGuide Viewer, and then either downloads it automatically or prompts
the user to download it themselves.

To install the Autodesk MapGuide Viewer ActiveX Control

1 To install the latest version of Autodesk MapGuide Viewer ActiveX Con-

trol for Internet Explorer users, include the CODEBASE parameter to access
the ActiveX Control cabinet file, mgaxctrl.cab, in the HTML page that spec­ifies your map. This parameter detects whether the latest version of the
Autodesk MapGuide Viewer ActiveX Control is installed. If the user does
not have the ActiveX Control or has an older version, the latest version
will be installed automatically.

In the following example, the CODEBASE parameter references the
mgaxctrl.cab file located on the Autodesk MapGuide FTP site. Alterna­tively, you can copy this file to your Web server and reference the file
there. You can find a copy of this file in the \ActiveXCab folder on the
Autodesk MapGuide CD:

<OBJECT ID="map" WIDTH=300 HEIGHT=200

CLASSID="CLSID:62789780-B744-11D0-986B-00609731A21D"
CODEBASE="ftp://adeskftp.autodesk.com/webpub/mapguide/ver6/

mgaxctrl.cab#Version=6,0,x,x">
<PARAM NAME="URL"

VALUE="http://www.mapguide.com/maps/usa.mwf">

<EMBED SRC="http://www.mapguide.com/maps/usa.mwf"

NAME="map" WIDTH=300 HEIGHT=200

PLUGINSPAGE="<www.autodesk.com/mapguideviewerdownload>">

</OBJECT>

Note that in your applications, you should change the release (#Version)
number from 6,0,x,x to the actual release number of Autodesk
MapGuide you are using. You can find the release number using the Help
➤ Help About menu command in the user interface or the
MGMap.aboutDlg method.

Installing Viewers on Client Machines | 27

To install the Autodesk MapGuide Viewer Plug-In

1 To install the latest version of Autodesk MapGuide Viewer Plug-In for

Netscape Navigator users, write additional code to prompt the user to
download Autodesk MapGuide Viewer Plug-In, as follows:

To download Autodesk MapGuide Viewer Plug-In

// Call this function on a page onLoad event or frameset onLoad event
function init()
{

// For Netscape browsers, check for
// Autodesk MapGuide Viewer Plug-In
if (navigator.appName == "Netscape")
{

for(j=0;j<navigator.plugins.length;j++)
{

if (navigator.plugins[j].name == "Autodesk MapGuide")

return;
}
// If the Autodesk MapGuide Viewer Plug-In is
// not detected, display the message...
displayDownloadMsg();
return;

}
// If the Autodesk MapGuide Viewer Plug-In is installed,
// check the version by returning the API version
var version = getMap().getApiVersion();
// If the API/Plug-In version is previous to 6.0,
//display the message
if (version < "6.0")
{

displayDownloadMsg();
return;

}
}
function displayDownloadMsg()
{

// Display dialog box.

msg = "You do not have the latest version of " +

"Autodesk MapGuide Viewer. Do you want to " +
"download it now? Click OK to download or Cancel" +

"to proceed with your current Autodesk MapGuide Viewer."
// If user clicks OK, load download page from Autodesk Web site
if (confirm(msg))

top.window.location =

"www.autodesk.com/mapguideviewerdownload";

}

28 | Chapter 2 Displaying Maps

To install the Autodesk MapGuide Viewer, Java Edition

1 To check a client machine for Autodesk MapGuide Viewer, Java Edition,

include the following applet in the HTML page that displays your map:

<APPLET

WIDTH="200"
HEIGHT="50"
CODE="CheckInstall.class"
<PARAM NAME="ClassToCheck"

VALUE="com.autodesk.mgjava.MGMapApplet">

<PARAM NAME="Installer"

VALUE="http://www.autodesk.com/mapguideviewerdownload">

</APPLET>

If Autodesk MapGuide Viewer, Java Edition is not found, the user is given
the option to download it from the Autodesk MapGuide download page.
For this code to work, the CheckInstall.class file must reside in the same
directory as the Web page that contains this code. Alternatively, you can
add a CODEBASE parameter that points to the folder where this file exists.

For a working example, choose Help ➤ Examples Advanced ➤ Java Edition
Examples ➤ Example3 in the Autodesk MapGuide Viewer API Help. For a
default Windows installation, you can find a copy of the

CheckInstall.class file in the following location:

C:\Program Files\Autodesk\MapGuideDocumentation6

\ViewerAPIHelp\ViewerAPI\JavaEdition\examples\classes

Installing Viewers on Client Machines | 29

30