create a basic web mapping application

8/3/2019 Create a Basic Web Mapping Application

1/23

Create a Basic Web Mapping Application

Overview

The following tutorial will guide you in creating a simple DMSG Fusion application based on MapGuideOpen Source. Its broken up into the following successive sections:

Chapter 1 - Template Preparation

Lesson 1 - Basic Templates

Lesson 2 Planning your UI

Lesson 3 Adding Containers

Lesson 4 - Adding Jx

Lesson 5 - Adding Fusion

Chapter 2 Creating your Application

Lesson 1 - Add a map

Lesson 2 - Adding toolbars

Lesson 3 - Adding a context menu

Lesson 4 - Adding the Task Pane & Panels

Lesson 5 - Removing a widget

Lesson 6 - Editing a widgets properties

The lessons are self-contained packages with specific exercises. Although its not necessary, it is strongly

suggested that you follow the tutorial in the correct order of lessons. Each lesson package contains the

following files:

index.htmlo The index.html file is the base for your fusion application. It contains the HTML markup,

Jx Layout, and the DMSG Fusion scripts. template.css

o The template.css file contains all the CSS that will apply to your tutorial template.Although you will not modify this file its important to understand the various

components described therein.

ApplicationDefinition.xml


2/23

o The ApplicationDefinition.xml file defines how your DMSG Fusion application interactswith index.html. It dictates how various elements (e.g., toolbars, context menus, etc.)

are built and what type of functionality is available to your users.

redirect.phpo The redirect.php file is a proxy script for AJAX requests. This file does not need to be

edited.

source.C#L#.txto This file contains the source code snippets for a particular chapter and lesson.

Software Requirements

You are required to have the following installed and in working order:

1. MapGuide Open Source2. WWW Service Extensions3. DMSG Fusion

For the purpose of this tutorial we will assume that your DMSG Fusion installation exists at the following

address:

http://localhost:8008/mapguide/fusion/


3/23

Chapter 1 Template Preparation

Lesson 1 Basic Templates

In its basic form, a DMSG Fusion template is nothing more than a valid HTML page with various HTML

tags and CSS. Fusion uses the HTML tags as containers for widgets. The widgets, their properties, and

their configuration are store in a repository call the Application Definition. The Application Definition is

an XML-based file that gets ingested by Fusion when an application starts. The XML gets converted into

JSON (JavaScript Object Notation) and tells Fusion how to configure the web mapping application.

HTML Template

A basic HTML template contains the following code:

Sample DMSG Fusion Application

@import url(template.css);

window.onload = function() {

}

The code contains a valid Strict DOCTYPE, reference to one or more CSS files, JavaScript, and a body. Its

important to note the Strict DOCTYPE DMSG Fusion requires this for layout purposes. By not including

a DOCTYPE the browser will assert its own, resulting in unexpected behavior.

When initiating a DMSG Fusion application you will be most concerned with the onload function of the

browser window. DMSG Fusion, UI Layout, and various other objects get created and initialized once

this event has fired. This will be covered in depth in Lesson 5 of Chapter 1.

Application Definition


4/23

A basic Application Definition contains the following sections:

MapSet

The MapSet contains one or more maps available to the application. The MapSet code block begins

with the following line:

MapSets contain MapGroups (i.e., a map). MapGroups define various properties of the map such as

type, whether its tiled or not, and the location of the resource.

WidgetSet

The Widget set contains all widgets available to the application (along with their respective properties)

as well as the configuration information for items such as menus and toolbars. The WidgetSet code

block begins with the following line:

There are three main sections of a WidgetSet Menus, Toolbars, and Widgets. Menus include File

Menus, Context Menus, Task Menus, etc. Toolbars are collections of widgets that are to appear

together in an application. For instance, you may wish to create a navigation toolbar. The navigation

toolbar would group like widgets together to make it easier for users of your application to interact with

the map.

In the following lessons you will be exposed to various widgets and configurations under the WidgetSet.

CSS

The CSS file for DMSG Fusion (and the Jx UI library) is no different from typical CSS in web applications.

Great care has been taken to separate content from style in DMSG Fusion. This means that web

designers and developers alike can modify the style of their application purely with CSS.

DMSG Fusion utilizes advanced CSS concepts such Selectors and Pseudo classes to achieve many stylistic

aspects of an application. It is highly recommended that if you plan on modifying the default style of

DMSG Fusion that you become familiar with these concepts.


5/23

Lesson 2 Planning Your UI

Typically, web designers will produce a drawing or wireframe of their application before developing

code. The sample application that will be produced from this tutorial started out as a drawing:

The various components of the above illustrated web mapping application are as follows:

1) Toolbar

The toolbar is a collection of widgets oriented either horizontally or vertically. Typical toolbar

collections include navigation tools, print tools, and analytical tools.

2) Panel Set

A panel set is a collection of one or more containers. These containers are intended to hold output

information relating to the application. Typical examples of panel content include legends, selection

info, overview maps, and configuration panes.

3) Map


6/23

For most web mapping applications the map is the main focus. In this instance we decided to place the

map in the middle of the application and surround it with functional content. The map can be as big as

you require and accommodate any placement requirements.

4) Task Pane

The Task Pane is a special container that is preconfigured with one or more tasks. These tasks include

buffer analysis, measurement tools, and custom task code. The Task Pane can be contained in other

containers (e.g., panel sets, tabs, etc.). For the purpose of this application it resides in its own fixed

space .

5) Status Bar

The Status Bar typically conveys snippets of useful information about the application. Since there is

usually a finite amount of space available for widgets in the Status Bar you will want to plan the contents

carefully.

Jx, the UI library used by DMSG Fusion, provides the above and a number of additional elements to work

with in your application. Here is a brief list of whats available:

o Absolute or relative containerso Panelso Tabso Toolbarso Buttonso Dialogso Etc.

For more information on Jx please consult the Jx documentation associated with DMSG Fusion.


7/23

Lesson 3 Adding Containers

The first step in creating your template is to populate the tag with valid, semantically correct

markup (snippet 1). Each element added to the template has an id . This id is very important for

certain containers as it tells DMSG Fusion to use this HTML element as a container for a widget (or set of

widgets). For example:

In the Application Definition there will be a toolbar widget container called Toolbar (case-sensitive). If

you do not include an HTML element called Toolbar in your template then DMSG Fusion will not render

the toolbar in the application. Note that the name of the Widget and its corresponding HTML element is

arbitrary you may select any name you wish.

When do I need an HTML container for a widget?

You could theoretically require an explicit container for every single widget in your application. At some

point, however, this would get very confusing and defeat the purpose of simple, semantic markup. Hereis a brief table denoting when you require an explicit container in your HTML markup:

Content Container Required? Notes

Simple stand-alone widget Yes Assumes the widget does not

belong to a collection.

Widget as part of a collection No Collection can include toolbars,

menus, etc.

Panel Yes

Tab Yes

Dialog Yes Requires a content ID as part of

the Jx instantiation


8/23

Lesson 4 Adding Jx

Jx is a JavaScript UI library that aims to simplify creation of web-based applications by providing a set of

common user interface components such as trees, tabs, dialogs, and more, that are flexible, reasonably

light-weight, easily configurable through CSS, and that behave consistently across all major browsers.

The Jx library is automatically included with DMSG Fusion. Here is a brief list of the UI elements that are

available to your application:

Button

DMSG Fusion uses Jx.Button to automatically create buttons in your application if required. Buttons

have several states: active, inactive, selected, and hover. There are also several different kinds of

buttons, including Multi and Flyout which provide additional functionality beyond the basic button.

Color

The Color object is used by the ColorPicker widget. The ColorPicker object returns the selected color

to the application for use by other widgets.

Dialog


9/23

Dialogs present an alternative to fixed panels in a DMSG Fusion application. Dialogs can be moved,

opened/closed, and modal. To use dialogs with DMSG Fusion you simply create an instance in the

window onload event and associate the contentID with the appropriate widget in the Application

Definition.

Layout

Jx.Layout provides the framework for DMSG Fusion applications. Jx.Layout can be either absolutely

or relatively positioned, depending on the requirements of your application. Jx.Layout takes care of

sizing issues and container placement that would otherwise be very difficult to achieve across

browsers.

Menu

DMSG Fusion uses Jx.Menu for all menus in the default interface. Its possible to create a menu

instance outside of DMSG Fusions scope as well. Menus are useful for a number of applications as

they gather like operations and functionality in relatively compact spaces.

Panel


10/23

Jx.Panels are used to create spacious containers for a number of widgets. Panels as part of

PanelSets become aware of adjacent panels and function as one object.

Splitter

Splitters are used to literally split two sets of content with a dividing draggable UI line. Splitters can

have a Snapper associated with them, in which case they can collapse.

Tab


11/23

Jx.Tabs group content together in a compact manner in the application UI. A typical instance of tabs

in a web mapping UI would group the legend, selection info, and overview map together. Tabs are

useful when you do not require the content of each tab to be visible all the time.

Toolbar

DMSG Fusion utilizes Jx.Toolbar to create the application toolbars as defined in the application

Definition. Each time you specific a Toolbar container DMSG Fusion will create an instance of

Jx.Toolbar.

In the practical examples there are 3 snippets of source code that have been placed into the application

template:

Layout (snippet 1)

The application has an overall container call thePage in the :

The first task in the onload event is to create a Jx.Layout object on the main container:

new Jx.Layout('thePage');

Creating a Layout object from thePage allows all subsequent Layout objects to abide by the size rules

of the parent container. From that point on we create similar Layout objects for each of our 5 defined

components of the application.

Splitter (snippet 2)

Two splitters are required for the sample application: a split between the map and the panel set and a

split between the Status Bar widgets. The map/panel splitter code is as follows:

var splitter = new Jx.Splitter('Splitter', {elements: [$('PanelPane'), $('Map')],

containerOptions: [{width: 200}, {}]});

The arguments are:

0 id of the div containing the elements to split (string)

1 options (object)

a) The elements to splitb) The container options for each element


12/23

In this case we want to create a new splitter object for the PanelPane and Map divs inside the

Splitter container. We also want to make the PanelPane have a default width of 200 and have the

Map fill the rest of the space.

The Status Bar splitter is created in the same manner. The elements which constitute the splitter are

identified and their options are specified as part of the options object passed in the second argument.

Note that for Jx.Splitters you are required to have divs created on the page. DMSG Fusion will not

create these elements for you (nor will Jx).

Panels (snippet 3)

var p1 = new Jx.Panel({label: 'Legend'});

p1.content.id = 'Legend';

Each panel in the application using Jx.Panel is created in a manner similar to the example above. There

are a number of options you can pass when creating the panel for the purposes of our application we

simply created a label. Its important to note that the id of the content container relates to the widget

name in the Application Definition. In this case DMSG Fusion will look for a widget called Legend to

place in the panel.


13/23

Lesson 5 Adding Fusion

The final task in Chapter 1 is to add DMSG Fusion to the template. There are two primary code snippets

required to Fusionize the application:

and

/* initialize Fusion */

Fusion.registerForEvent(Fusion.Event.FUSION_INITIALIZED, fusionInitialized);

Fusion.registerForEvent(Fusion.Event.FUSION_ERROR, fusionError);

Fusion.initialize();

The first block of text (snippet 1) is added to the section of the template. It includes the DMSG

Fusion JavaScript file and makes it available to your application. The second block of text (snippet 2)

gets called at the end of your window.onload event. This line of code invokes DMSG Fusion. At this

point, DMSG Fusion will parse the Application Definition and generate the application UI. The code in

snippet 2 also registers the application for two events INITIALIZED and ERROR. When you register for

an event you specify a callback function to fire when the event gets triggered. In this case we have want

to call fusionInitialized (snippet 4) when the application has completed initializing and fusionError

(snippet 3) when DMSG Fusion returns an error.

When you go to look at the application youll notice that the page seems broken. Actually, it is broken.

We have not yet added any widgets to the Application Definition that relate to the HTML containers in

the template. Chapter 2 will take you through adding, removing, and editing various DMSG Fusion

widgets.


14/23

Chapter 2 Creating your Application

Lesson 1 Adding a Map

Chapter 2 lessons deal primarily with editing the Application Definition. Our first task is to add a map to

our interface. Before we can reference a map in our Map widget we must clearly definition the resource

to display. This is accomplished by specifying a MapGroup in the MapSet (snippet 1):

MapGuide

true

Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition

This MapGroup specifies the Sheboygan sample data as our resource to display. You can have as many

MapGroups as necessary in the MapSet. Later on we will be adding another MapGroup specifically for

the overview map. This will be necessary because the overview map is essentially a new instance of a

map and well want to have less detail displayed at various scales.

Once the MapGroup has been added we add the Map widget (snippet 2) to the WidgetSet as follows:

Map

Map

The map.

sheboygan

ContextMenu


15/23

Here is a breakdown of the widget properties:

The name attribute refers to the HTML container in your template. In this case we will be adding the

map to a div element with an id of Map (note the case).

This widgets type is Map. When DMSG Fusion parses the Application Definition it will use this Type to

browse the widgets directory on disk and load the appropriate JavaScript file. In this instance it will load

widgets/Map.js and any dependencies.

StatusText does not currently show itself in the application UI.

The MapId refers to the MapGroup id in the MapSet. This is how DMSG Fusion links the widget to the

resource definition.

The Extension section of the Map widget (or any widget) holds attributes specific to the widget. For

instance, in this case the Map widget informs the ContextMenu of its existence. This, in turn, allows the

ContextMenu to redner itself in the appropriate location of the UI.

Take a look at the application in your browser you should see a map of Sheboygan. Next well add a

Toolbar and StatusBar so that we can interact with the map.


16/23

Lesson 2 Adding Toolbars & the Status Bar

Preface: (snippet 1) The bulk of the application widgets have been added to the Application Definition in

this Lesson without explicit mention. For all intents and purposes they are added in a fashion similar to

the Map widget from chapter 2 Lesson 1.

Toolbars can contain any number of widgets for use in a web mapping application in children calledItems. Discrete sets of tools within a toolbar can be achieved by using separators (discussed below). In

the sample application that we are building there is one toolbar across the top of the application

that contains a number of widgets. A basic toolbar XML construct is as follows (snippet 2):

Toolbar

Toolbar

Widget

Pan

In this example we are adding a toolbar named Toolbar and including a widget named Pan. In the

application template there is a toolbar HTML container called Toolbar. In the WidgetSet of the

Application Definition there is a widget named Pan. Note that there is no Pan HTML container in the

application template. The toolbar will automatically create that for you. The remainder of the widgets

are added to the toolbar in snippet 3.

Toolbars can contain the following Item types:

WidgetItemType

Any valid widget that reveals itself in a manner appropriate for a toolbar. For instance, Pan, Zoom, and

Print are acceptable widgets for a toolbar. Legend and Overview Map are not well suited for a toolbar.

SeparatorItemType

Separates groups of widgets in a toolbar.

FlyoutItemType

A menu Item that contains additional widgets/menu items.

When looking at the application template youll notice that weve added the following (snippet 1 of

index.html):

var l = new Jx.Layout($('Toolbar').childNodes[0]);

l.resize();


17/23

DMSG Fusion toolbars are Jx objects with a layout property. After DMSG Fusion has initialized we need

to resize the toolbar according to its HTML container (in this case the Jx.Layout object Toolbar).

StatusBar

The statusbar is an ApplicationDefinition container that utilizes a Jx.Splitter when rendering. Each item

in the statusbar is separated by a dragable handle.


18/23

Lesson 3 Adding a Context Menu

A Context Menu is a dynamic menu available on right-click within a specific HTML container. In our

example we have added a Context Menu to the Map Widget (see Chapter 2 Lesson 1 for a refresher).

Adding a Context Menu is hown in the following code block (snippet 1):

ContextMenu

ContextMenu

Widget

menuPan

In this example we are adding a ContextMenu named ContextMenu and including a widget namedmenuPan. Note that there is no HTML container predefined for a Context Menu. DMSG Fusion will

create on for you when the application initializes.

The reminder of the sample Context Menus widgets and menus are shown in snippet 2.


19/23

Lesson 4 Adding the Task Pane & Panels

The Task Pane has been added to the template as a Jx.Layout. The HTML element used is TaskPane.

Since the Task Pane will not share its template real estate with any other widget we do not require it to

go into a specialized container beyond the layout object. The following Application Definition is used to

place the Task Pane in the template UI (snippet 1):

TaskPane

TaskPane

TaskContextMenu

With respect to the above code snippet, its worth noting the MenuContainer Extension. This

extension associates a Menu construct with the Task Pane (located in the upper right hand corner of the

Task Pane interface).

Panels in DMSG Fusion are Jx.Panel objects that get populated with specific widgets from the

Application Definition. Jx.Panel objects are created with the following code:

var panel1 = new Jx.Panel({label: 'Some Label'});

panel1.content.id = 'Some Name';

The above two lines of code will create a Panel for use in a PanelSet:

var panelManager = new Jx.PanelManager('PanelPane', [panel1, panel2]);

The Panel Manager uses an HTML container (in this instance named PanelPane) to contain all Panels

created. The Panel Manager is responsible for sizing and keeping track of which Panel is visible at any

given time. Each Jx.Panel has a content container with an id. This id correlates to the name of thewidget in the Application definition. For example (snippet 2):


20/23

Legend

Legend

In the application template there is a Jx.Panel with a content id of Legend. When DMSG Fusion parses

the Application Definition and comes across the Legend widget it will populate the panel with the

Legend code. The same logic and process applies to the Selection Info (snippet 3) and Overview Map

(snippet 4).

A note about the Overview Map

As mentioned earlier, the Overview Map uses a separate MapGroup definition to render its contents.

This a) help reduce clutter with a less detailed map and b) avoids potential conflicts with widgets

interacting with each map. For the Sheboygan dataset we created the following MapGroup (snippet 5):

MapGuide

true

Library://Samples/Sheboygan/Maps/SheboyganOverview.MapDefi

nition

This MapGuide package is available in the data folder of this tutorial install.


21/23

Lesson 5 Removing a Widget

Removing a widget from a DMSG Fusion web mapping application is a relatively simple operation.

Widget definitions can reside in the Application Definition without rendering themselves in the

application. There are two basic ways widgets make their way into the UI:

1) Via HTML Containers

Removing the HTML Container will effectively remove the widget from the application. DMSG Fusion

ignores any widget definition that does not have a corresponding HTML container.

2) Via WidgetSet Constructs (e.g., Menus, Toolbars, etc.)

Removal of the widget name from a WidgetSet construct removes the widget in the same manner as #1.

If nothing calls the widget during the Application Definition parse then it is ignored.

The following example illustrates the removal of a widget via a WidgetSet Construct (snippet 1):

Widget

Pan

Removing this block of code from the Toolbar container in the WidgetSet effectively removes the Pan

widget from the application. We can go one step further and remove the Pan widget definition from the

Application Definition altogether (snippet 2):

Pan

Pan

Drag the map to view areas out of range.

../../images/stdicons/icon_pan.gif

Pan mode

Note that you cannot remove the widget definition without removing the reference in the WidgetSet

Construct. During the Application Definition parse, DMSG Fusion looks for this widget. If it does not find

it an error will be thrown. In this sense its different from HTML containers. An HTML container can


22/23

exist in the application with no corresponding widget name. The same cannot be said of a WidgetSet

Construct if declared then the widget must exist.

In snippet 3 of the source file the following is specified:

menuPan

Pan

Drag the map to view areas out of range.

../../images/stdicons/icon_pan.gif

Pan mode

Pan

FROM CONTEXT MENU

Widget

menuPan

Even though we removed the Pan from the toolbar its functionality available to the users via the Context

Menu. A widget can exist multiple times in any given Application Definition. The differentiator is the

name attribute of the widget code block. In the above case, menuPan has been created specifically for

the ContextMenu. Multiple declarations of the same widget is useful for more than container

assignment you can also alter the attributes of the widget for specific uses. For instance, you may

want to have one Pan widget that has a label (e.g., for a menu) and another that just shows itself as an

icon (e.g., for a toolbar).


23/23

Lesson 6 Editing a Widgets Properties

The final lesson of Chapter 2 deals with editing a widgets properties. As weve seen, all widgets have a

base set of properties that they share. Specific widgets have additional properties that are part of either

an extension or their base attributes. Altering a widgets properties is as simple as changing the value

for a given tag within the widget cod block. Look at the following widget (snippet 1):

ZoomInRectangle

Zoom

Zoom in on an area.

52

../../images/stdicons/icon_zoomin.gif

Zoom rectangle.

In the Extension block of this ZoomInRectangle widget there is a Factor property. Its currently set to 2.

IF we change it to 4 and reload the application then the ZoomInRectangle widget will zoom by a factor

of 4 instead of 2. We can also change the label attribute of this widget. Currently, it does not have a

label (as denoted by the self terminated tag ). To create a Label we simply would enter the

following in place of :

Zoom In

The ZoomInRectangle widget now has a label in the Application UI. When editing widget properties its

best to test each edit by refreshing the application. Mistyped XML can be tricky to track down after

several untested edits have been completed.

create a basic web mapping application

Documents