Changes between Version 1 and Version 2 of MapGuideTutorial


Ignore:
Timestamp:
Mar 11, 2008, 7:30:11 AM (16 years ago)
Author:
pagameba
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideTutorial

    v1 v2  
    148148 * Widgets with associated HTML elements are identified
    149149 * the !JavaScript file associated with each identified Widget is loaded
    150  * any dependencies of the Commands are loaded
    151  * when all Commands (and their dependencies) are loaded, a new instance of each Command is created for each HTML element.
    152  * when all Commands have been initialized, the FUSION_INITIALIZED event is emitted.
    153 
    154 An important step in this process is the loading of the Map widget(s).  After each Map widget has been created, it:
    155 
    156 attempts to create a session with the server for that Map instance.  All Map instances will share the session.
    157 if an initial map is specified:
    158 issue a MAP_LOADING event
    159 attempt to load the Map (which will wait until the session has been created)
    160 issue a MAP_LOADED event when the map has finished loading
     150 * any dependencies of the Widget are loaded
     151 * when all Widgets (and their dependencies such as CSS files) are loaded, a new instance of each Widget is created for each HTML element.
     152 * when all Widgets have been initialized, the {{{FUSION_INITIALIZED}}} event is emitted.
     153
     154An important step in this process is the loading of the Map Widget(s).  After each Map Widget has been created, it:
     155
     156 * attempts to create a session with the server for that Map instance.  All Map instances of the same Type will share the same session.
     157 * if an initial Map is specified:
     158   * issue a {{{MAP_LOADING}}} event
     159   * attempt to load the Map (which will wait until the session has been created)
     160   * issue a {{{MAP_LOADED}}} event when the map has finished loading
    161161 
    162 All Commands (except Map Commands) are associated with a specific Map Command by name.  If a specific Map Command Name is not specified in the Command, then the Command will be associated with the first Map in the WebLayout.  As most applications have only one map instance, it is typical to leave out the explicit MapName when defining Commands.
    163 
    164 Most Commands require the Map to be loaded in order to be usable in the application.  As it is possible to define a Map Command without providing a default map for it to load, some widgets are designed to allow selecting a Map to load.  These widgets are typically enabled even when no map is loaded.
    165 
    166 For widgets that do require a Map to be loaded, they automatically register for the MAP_LOADED event and will enable themselves as soon as this event has been issued.
    167 
    168 Fusion Architecture
    169 
    170 Fusion Integration into MGOS
     162All Widgets in a !WidgetSet are associated with the !MapWidget of that !WidgetSet.
     163
     164== Fusion Architecture ==
     165
     166== Fusion Integration into !MapGuide Open Source ==
    171167
    172168MapGuide Open Source architecture is divided into three tiers:
    173169
    174 Server Tier.  This tier runs the MGOS server.  Fusion is not integrated into this tier.
    175 Web Extensions Tier.  This tier runs with a Web Server.  Fusion is installed in this tier and makes use of the MGOS Web Extensions API to implement some functionality.
    176 Client Tier.  This tier runs in the client's web browser.  Most of Fusion exists in this tier, and it completely replaces the existing MGOS client tier (known as the AJAX viewer).
    177 
    178 Diagram 1 shows how Fusion integrates into the MGOS Tiers.  The blue blocks are new Fusion components and the light grey blocks are existing MGOS components.
    179 
    180 The Fusion Server components work directly with the MGOS PHP API to implement specific functionality such as buffering features and working with selections.
    181 
    182 The Fusion JavaScript API and widgets are installed with the MGOS Web Tier, but they are actually loaded up to and executed in the Client Tier.
    183 WebLayouts, HTML and Widgets
    184 
    185 The API and widgets are linked to specific HTML elements within an HTML page through the WebLayout XML document.  A widget is the executable code (javascript class) that is loaded when Fusion identifies an HTML element id and WebLayout command name that are the same.  The Action of the WebLayout Command identifies the exact javascript file to be loaded and the javascript object that needs to be instantiated to create a functional widget.  The runtime instance of the javascript object is the widget.
    186 
    187 When the runtime instance is created, it uses the HTML element id to determine where in the HTML page it should display its user interface.  Any custom configuration for the widget is placed in the WebLayout Command XML block as sub tags (each widget has its own list of what customization is possible, see the Command API Reference for details). 
    188 
    189 If you are customizing the look and feel of a single widget by overriding the CSS styling for the widget, this is normally done by using the #<id> syntax to limit your changes to that specific widget.
    190 Understanding WebLayouts
    191 
    192 A Web Layout is an XML document that provides control over the appearance and behaviour of elements of a Fusion application.  It consists of blocks of XML that control various aspects of a Fusion application.  The root element of a Web Layout document is always <WebLayout>.
    193 The following elements may exist within the WebLayout element:
    194 Map
    195 ToolBar
    196 CommandSet
    197 Map
    198 
    199 The Map block is optional and may occur 0 or more times.  It defines per-Map metadata that cannot be stored with the Map in any other way.  The Map block contains the following elements:
    200 ResourceId.  The ResourceId tag identifies the Map to which this metadata is relevant.
    201 Links.  Links are used to identify external URLs that contain information related to groups or layers.  Links are discussed in more detail below.
    202 LayerEvents.  LayerEvents are used to make changes to the visibility of related groups and/or layers when a layer or group changes visibility.  LayerEvents are described in more detail below.
    203 Links
    204 
    205 The Links block can contain any number of Group and Layer blocks.  Group and Layer blocks contain identical tags:
    206 Name.  This tag is used to identify a Group or Layer by its name.
    207 Url.  This tag is the href that is opened when the user wants to get information about the Group or Layer.  It may be absolute or relative, but if it is relative, it is relative to the application.
    208 
    209 Example Links block:
    210 
    211 <Links>
    212   <Group>
    213     <Name>Transportation</Name>
    214     <Url>http://localhost/transportation.html</Url>
    215   </Group>
    216   <Layer>
    217     <Name>Parcels</Name>
    218     <Url>http://localhost/parcels.html</Url>
    219   </Layer>
    220 </Links>
    221 LayerEvents
    222 
    223 The LayerEvents block can contain any number of Layer and/or Group blocks.  A Layer or Group block identifies the Layer or Group to which it applies in a Name tag.  There are two additional blocks that control what happens when the Layer or Group changes visibility.  The OnEnable block is used when the Layer or Group becomes visible, and the OnDisable block is used when the Layer or Group becomes hidden.  Both blocks have the same structure.  They contain any number of Layer or Group blocks that contain a Name tag (which identifies a Layer or Group) and an Enable tag (which determines if the Layer or Group should become visible or hidden).
    224 
    225 When any layer or group changes visibility via the legend control or programmatically via the API, if a LayerEvent exists for that Layer or Group, then the appropriate OnEnable or OnDisable block will be 'executed' as well.  This means any layers or groups in the appropriate block will change state as dictated by the Enable tag of that Layer or Group.
    226 
    227 Example LayerEvents block:
    228 
    229 <LayerEvents>
    230   <Layer>
    231     <Name>RoadBuffer</Name>
    232     <OnEnable>
    233       <Layer>
    234         <Name>RoadCenterline</Name>
    235         <Enable>true</Enable>
    236       </Layer>
    237     </OnEnable>
    238     <OnDisable>
    239       <Layer>
    240         <Name>RoadCenterline</Name>
    241         <Enable>false</Enable>
    242       </Layer>
    243     </OnDisable>
    244   </Layer>
    245 </LayerEvents>
    246 Example
    247 
    248 A complete Map block example:
    249 
    250 <Map>
    251   <ResourceId>Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition</ResourceId>
    252   <Links>
    253     <Group>
    254       <Name>Transportation</Name>
    255       <Url>http://localhost/transportation.html</Url>
    256     </Group>
    257     <Layer>
    258       <Name>Parcels</Name>
    259       <Url>http://localhost/parcels.html</Url>
    260     </Layer>
    261   </Links>
    262   <LayerEvents>
    263     <Layer>
    264     <Name>RoadBuffer</Name>
    265       <OnEnable>
    266         <Layer>
    267           <Name>RoadCenterline</Name>
    268           <Enable>true</Enable>
    269         </Layer>
    270       </OnEnable>
    271       <OnDisable>
    272         <Layer>
    273           <Name>RoadCenterline</Name>
    274           <Enable>false</Enable>
    275         </Layer>
    276       </OnDisable>
    277     </Layer>
    278   </LayerEvents>
    279 </Map>
    280 ToolBars
    281 
    282 ToolBars are provided as a convenience for creating user interface elements that are displayed as a horizontal toolbar of buttons, menus and separators.  A Web Layout may specify zero or more ToolBar tags.
    283 A ToolBar contains the following sub-tags:
    284 Name.  Required.  This is a unique name for the ToolBar.  The ToolBar element that is created has an HTML id with this value.
    285 Container.  Required.  This is the HTML id of an element (typically a DIV) that the ToolBar is to be created within.  More than one ToolBar can be assigned to the same container.
    286 Visible.  Optional.  This contains either true or false, indicating the initial visibility of the ToolBar.  The default value is true.  There is currently no way to change the visibility of a ToolBar so it is recommended to leave this tag out or set it to true.
    287 Button.  Optional.  There can be zero or more Button blocks in a ToolBar, although a ToolBar with no buttons has no purpose.  Button blocks are described in more detail below.
    288 Button blocks
    289 
    290 A Button block inside a ToolBar is used to make something appear in the user interface.  The order of Buttons in the ToolBar is used to determine the order of the elements in the user interface.  A Button block contains a mandatory Function tag which must contain one of the following values:
    291 Command.
    292 Flyout
    293 Separator
    294 
    295 If the Function tag value is Command, the Button is a clickable button that activates a Command described in the WebLayout.  This Button block contains one more tag, Command, which contains the name of a Command to be found in the CommandSet (Commands and the CommandSet are described below.
    296 
    297 If the Function tag value is Flyout, the Button is specifying a drop-down menu that opens when the user clicks the Button in the ToolBar.  This Button block contains a Label tag, which contains the text displayed in the ToolBar, and some number of SubItem tags that specify the items in the menu.  The SubItem blocks are structured identically to a Button block, and contain a Function tag and variable other tags depending on the value of the Function tag.  Flyout menus can contain sub-menus by specifying a Function tag value of Flyout.
    298 
    299 If the Function tag value is Separator, the Button specifies a visual separator is to be placed in the ToolBar.  Separators have no other tags in their Button block.
    300 
    301 An example of a ToolBar block is:
    302 
    303 <ToolBar>
    304   <Name>MainToolbar</Name>
    305   <Container>ToolbarContainer</Container>
    306   <Visible>true</Visible>
    307   <Button>
    308     <Function>Command</Function>
    309     <Command>ZoomIn</Command>
    310   </Button>
    311   <Button>
    312     <Function>Command</Function>
    313     <Command>ZoomOut</Command>
    314   </Button>
    315   <Button>
    316     <Function>Flyout</Function>
    317     <Label>Extent History</Label>
    318     <SubItem>
    319       <Function>Command</Function>
    320       <Command>PreviousExtent</Command>
    321     </SubItem>
    322     <SubItem>
    323       <Function>Command</Function>
    324       <Command>NextExtent</Command>
    325     </SubItem>
    326   </Button>
    327 </ToolBar>
    328 
    329 CommandSet
    330 
    331 The CommandSet block is mandatory and only one CommandSet block is allowed in the WebLayout.  The CommandSet block contains one or more Command blocks.  The Command blocks are used to configure widgets.
    332 
    333 Although the content of a Command block is dictated by the type of widget that the Command will create, some elements of Command blocks are common.  This document describes the common elements.  Additional configuration of Commands is described in the Command Reference document.
    334 
    335 All Command blocks contain the following tags:
    336 
    337 Name.  The Name of the Command is used by Fusion to determine where the Command is to be placed in the user interface.  The Command will be created inside an HTML element that has an id with the same value as the Command's Name.  In the case of a Command that is referenced by a ToolBar, the Command does not require an HTML element as the ToolBar will create one for the Command.  Each Command must have a unique Name.
    338 Action.  The Action of the Command is the actual widget that will be created for the Command.  If a Command references a widget that does not exist, an error will occur that will prevent the application from loading.
    339 Location.  This is an optional tag and is used to identify where custom widgets can be found.  If Location is not provided, the widget is assumed to be one of the stock widgets distributed with Fusion.  If the Location is provided, it must be a relative path to the directory containing the widget's javascript file.  Fusion has an ext directory and, by convention, custom widgets (and optional packages of widgets) are installed in sub-directories under this directory.  If you follow this convention, the Location tag would contain a value like 'ext/mywidgets'.
    340 TargetViewer.  This tag is provided for backwards compatibility.  It is not used by Fusion and is ignored.  In future versions, this tag will be removed entirely.  It should contain a value of 'All'.
    341 
    342 Please use the Command Reference document to find out about the specific tags used by the various widgets.
    343 Understanding Events
     170Server Tier:
     171  This tier runs the !MapGuide Open Source server.  Fusion is not integrated into this tier.
     172Web Extensions Tier:
     173  This tier runs with a Web Server.  Fusion is installed in this tier and makes use of the !MapGuide Open Source Web Extensions API to implement some functionality.
     174Client Tier:
     175  This tier runs in the client's web browser.  Most of Fusion exists in this tier, and it completely replaces the existing !MapGuide Open Source client tier (known as the AJAX viewer).
     176
     177Diagram 1 shows how Fusion integrates into the !MapGuide Open Source Tiers.  The blue blocks are new Fusion components and the light grey blocks are existing !MapGuide Open Source components.
     178
     179The Fusion Server components work directly with the !MapGuide Open Source PHP API to implement specific functionality such as buffering features and working with selections.
     180
     181The Fusion !JavaScript API and widgets are installed with the !MapGuide Open Source Web Tier, but they are actually loaded up to and executed in the Client Tier.
     182
     183== !ApplicationDefinitions, HTML and Widgets ==
     184
     185The API and widgets are linked to specific HTML elements within an HTML page through the !ApplicationDefinition XML document.  A widget is the executable code (!JavaScript class) that is loaded when Fusion identifies an HTML element id and Widget Name that are the same.  The Type of the Widget identifies the exact !JavaScript file to be loaded and the !JavaScript object that needs to be instantiated to create a functional widget.  The runtime instance of the !JavaScript object is the widget.
     186
     187When the runtime instance is created, it uses the HTML element id to determine where in the HTML page it should display its user interface.  Any custom configuration for the widget is placed in the ApplicationDefinition Widget XML block as sub tags (each widget has its own list of what customization is possible, see the Widget API Reference for details). 
     188
     189If you are customizing the look and feel of a single widget by overriding the CSS styling for the widget, this is normally done by using the {{{#<id>}}} syntax to limit your changes to that specific widget.
     190
     191
     192== Understanding Events ==
    344193
    345194The event code in Fusion is designed to provide an asynchronous notification mechanism that can be used to register for, and receive notification of, key events that happen asynchronously in Fusion.  The following terms are used with respect to events:
    346195
    347 event id: a unique identifier for an event, represented by a javascript variable that is all in upper case (e.g FUSION_INITIALIZED)
    348 trigger: when an event occurs, it is 'triggered' and all the registered callback functions are notified
    349 register: provide a callback function that is called when an event is triggered
    350 deregister: remove a callback function that was previously registered
    351 publish: anything that can trigger an event must publish all the valid event ids
    352 
    353 The event mechanism of Fusion is implemented by two functions: registerForEvent and deregisterForEvent.  Both functions have the same signature, taking an event ID as the first parameter and a callback function pointer as the second parameter.
     196 * ''event id'': a unique identifier for an event, represented by a javascript variable that is all in upper case (e.g {{{FUSION_INITIALIZED}}})
     197 * ''trigger'': when an event occurs, it is 'triggered' and all the registered callback functions are notified
     198 * ''register'': provide a callback function that is called when an event is triggered
     199 * ''deregister'': remove a callback function that was previously registered
     200 * ''publish'': anything that can trigger an event must publish all the valid event ids
     201
     202The event mechanism of Fusion is implemented by two functions: {{{registerForEvent}}} and {{{deregisterForEvent}}}.  Both functions have the same signature, taking an event ID as the first parameter and a callback function pointer as the second parameter.
    354203
    355204The Fusion application object provides two specific events that can be used by applications to get notification of when Fusion initialization has completed and when an error occurs anywhere in Fusion.  These events are:
    356205
    357 FUSION_INITIALIZED.  This is triggered when Fusion's initialization is complete and the application is running.  This signals that it is safe for the application to communicate with specific widgets.  Note that the Map widget, specifically, will be ready but may not have actually loaded the map.  There is a separate event for that (see the Map widget in the Command API reference).  Applications should register for this event before calling Fusion.initialize().
    358 FUSION_ERROR.  This is triggered when an internal error happens.  Details on the error are passed to the callback function.  Applications should register for this event before calling Fusion.initialize() to ensure that they receive errors that happen during initialization.
     206FUSION_INITIALIZED:
     207  This is triggered when Fusion's initialization is complete and the application is running.  This signals that it is safe for the application to communicate with specific widgets.  Note that the Map widget, specifically, will be ready but may not have actually loaded the map.  There is a separate event for that (see the Map widget in the Command API reference).  Applications should register for this event before calling Fusion.initialize().
     208FUSION_ERROR:
     209  This is triggered when an internal error happens.  Details on the error are passed to the callback function.  Applications should register for this event before calling {{{Fusion.initialize()}}} to ensure that they receive errors that happen during initialization.
    359210
    360211Widgets in Fusion also use and trigger events.  Widgets are designed to be completely independent of one another, allowing them to be added to, or removed from, applications with little or no impact on the other widgets in the application.  However, there are cases (especially with the Map widget) where it is important that widgets be able to communicate with other widgets or with the application as a whole.  For these situations, there is an event mechanism built into Fusion that allows widgets, and applications built on Fusion, to register for and trigger events.  The event mechanism allows widgets to be independent of each other, but still provide a high level of integration when required.
    361212
    362 To register a callback function for a widget event, the application must first obtain a reference to the widget through one of the methods of the Fusion object (getWidgetById typically) and then call registerForEvent passing one of the event IDs that is valid for that widget.
    363 
    364 Working with Maps
     213To register a callback function for a widget event, the application must first obtain a reference to the widget through one of the methods of the Fusion object ({{{getWidgetById}}} typically) and then call {{{registerForEvent}}} passing one of the event IDs that is valid for that widget.
     214
     215== Working with Maps ==
    365216
    366217In Fusion, the Map widget is central to everything that is going on.  It is not valid to design a Fusion application without a Map in it.  The Map widget is the primary interface between the application and the spatial data represented by the map.  Most widgets in Fusion either display information about the map or allow the user to interact with the map in some way.
    … …  
    368219The Map widget API is probably the most used one in Fusion.  It is completely documented in the Command API reference, but the most used methods are described here.
    369220
    370 loadMap(mapDefinition).  This causes the Map widget to load the specified MapDefinition.
    371 reloadMap().  This causes the Map widget to reload the current MapDefinition.  This is necessary when the map state has changed in certain ways (adding or removing layers in the map, for instance) and is primarily an internal function.
     221loadMap(mapDefinition):
     222  This causes the Map widget to load the specified MapDefinition.
     223reloadMap():
     224  This causes the Map widget to reload the current MapDefinition.  This is necessary when the map state has changed in certain ways (adding or removing layers in the map, for instance) and is primarily an internal function.
    372225setExtents(minx, miny, maxx, maxy).  This is used to set the map extents to a particular bounding box programmatically.
    373 drawMap().  This is used to render a map image and load it in the browser.  Normally, this is called automatically as required, but occasionally it may be required to be called programmatically when the state of the map has changed on the server without the knowledge of the Map widget.
    374 query(options).  This is described more completely in the Command API Reference, but the query method is used to query the Map in some way and create (or modify) a selection.
    375 getSessionId()
    376 
    377 When a Map is defined in the WebLayout file, it can have a default MapDefinition that is automatically loaded when the application is loaded.  But it is not mandatory to specify a default map.  When no default map is specified, the Map widget is still initialized.  Loading of a MapDefinition is then done in response to a widget (such as the MapMenu widget) or some application-specific code.  Regardless of how it happens, when a MapDefinition has been loaded, the Map widget will trigger a MAP_LOADED event.&nbsp; Most widgets are not useful if there is no map loaded, so they use the MAP_LOADED event to determine when they should be enabled.  This means that most widgets will appear initially disabled until the map has been loaded.  There are some notable exceptions, including the Map Menu widget which is used to provide a drop-down menu of MapDefinitions that the user can pick from.
     226drawMap():
     227  This is used to render a map image and load it in the browser.  Normally, this is called automatically as required, but occasionally it may be required to be called programmatically when the state of the map has changed on the server without the knowledge of the Map widget.
     228query(options):
     229  This is described more completely in the Command API Reference, but the query method is used to query the Map in some way and create (or modify) a selection.
     230getSessionId():
     231
     232When a Map is defined in the ApplicationDefinition file, it can have a default MapDefinition that is automatically loaded when the application is loaded.  But it is not mandatory to specify a default map.  When no default map is specified, the Map widget is still initialized.  Loading of a MapDefinition is then done in response to a widget (such as the MapMenu widget) or some application-specific code.  Regardless of how it happens, when a MapDefinition has been loaded, the Map widget will trigger a MAP_LOADED event.&nbsp; Most widgets are not useful if there is no map loaded, so they use the MAP_LOADED event to determine when they should be enabled.  This means that most widgets will appear initially disabled until the map has been loaded.  There are some notable exceptions, including the Map Menu widget which is used to provide a drop-down menu of MapDefinitions that the user can pick from.
    378233
    379234Once the Map is loaded, many events may be triggered, including: