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
8/3/2019 Create a Basic Web Mapping Application
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/
8/3/2019 Create a Basic Web Mapping Application
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
8/3/2019 Create a Basic Web Mapping Application
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.
8/3/2019 Create a Basic Web Mapping Application
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
8/3/2019 Create a Basic Web Mapping Application
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.
8/3/2019 Create a Basic Web Mapping Application
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/3/2019 Create a Basic Web Mapping Application
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
8/3/2019 Create a Basic Web Mapping Application
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
8/3/2019 Create a Basic Web Mapping Application
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
8/3/2019 Create a Basic Web Mapping Application
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
8/3/2019 Create a Basic Web Mapping Application
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.
8/3/2019 Create a Basic Web Mapping Application
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.
8/3/2019 Create a Basic Web Mapping Application
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
8/3/2019 Create a Basic Web Mapping Application
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.
8/3/2019 Create a Basic Web Mapping Application
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();
8/3/2019 Create a Basic Web Mapping Application
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.
8/3/2019 Create a Basic Web Mapping Application
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.
8/3/2019 Create a Basic Web Mapping Application
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):
8/3/2019 Create a Basic Web Mapping Application
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.
8/3/2019 Create a Basic Web Mapping Application
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
8/3/2019 Create a Basic Web Mapping Application
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).
8/3/2019 Create a Basic Web Mapping Application
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.
Top Related