Changes between Version 4 and Version 5 of MapGuideTutorial


Ignore:
Timestamp:
03/12/08 05:29:33 (17 years ago)
Author:
pagameba
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideTutorial

    v4 v5  
    4141These widgets need to be described in an ApplicationDefinition xml file.  Fusion allows you to store the ApplicationDefinition resource in the MapGuide repository or as a separate XML file.  For the purpose of this document, we will be assuming that you are storing the ApplicationDefinition resource as a separate XML file.  There are instructions at the end of this document for using an ApplicationDefinition resource stored in a !MapGuide repository.
    4242
    43 By convention, the name of the file is ApplicationDefinition.xml.  So, create a new file in the {{{hello}}} directory and name it ApplicationDefinition.xml.  For our very simple example, we need an ApplicationDefinition tag with a Title tag, a !MapGroup tag, and a !WidgetSet tag to hold our four widgets (see the ApplicationDefinition page for a more complete description).  Individual widgets are represented as Widget tags inside the WidgetSet tag where the actual widget is specified by the Type tag and the HTML element that the widget will be created in is specified by the Name tag.  Our four widgets each have a specific Widget tag with several options, most of which are not required for this example.  The resulting XML for Hello Sheboygan is:
     43By convention, the name of the file is ApplicationDefinition.xml.  So, create a new file in the {{{hello}}} directory and name it ApplicationDefinition.xml.  For our very simple example, we need an ApplicationDefinition tag with a Title tag, a [wiki:ApplicationDefinition/MapSet/MapGroup MapGroup] tag, and a [wiki:ApplicationDefinition/WidgetSet WidgetSet] tag to hold our four widgets (see the ApplicationDefinition page for a more complete description).  Individual widgets are represented as [wiki:ApplicationDefinition/WidgetSet/Widget Widget] tags inside the [wiki:ApplicationDefinition/WidgetSet WidgetSet] tag where the actual [wiki:ApplicationDefinition/WidgetSet/Widget Widget] is specified by the Type tag and the HTML element that the [wiki:ApplicationDefinition/WidgetSet/Widget Widget] will be created in is specified by the Name tag.  Our four widgets each have a specific [wiki:ApplicationDefinition/WidgetSet/Widget Widget] tag with several options, most of which are not required for this example.  The resulting XML for Hello Sheboygan is:
    4444{{{
    4545<ApplicationDefinition
    … …  
    9090      <Disabled/>
    9191    </Widget>
    92     <Widget xsi:type="UiWidgetType">
     92    <Widget>
    9393      <Name>Pan</Name>
    9494      <Type>Pan</Type>
    … …  
    140140== Under the Hood ==
    141141
    142 As you can see, quite a lot of things are going on without a lot of code.  Adding other widgets is as simple as adding an HTML container for them in the HTML page and adding a Widget in the WidgetSet.  So how exactly does Fusion turn this small amount of HTML and XML into a functional web mapping application?
     142As you can see, quite a lot of things are going on without a lot of code.  Adding other widgets is as simple as adding an HTML container for them in the HTML page and adding a [wiki:ApplicationDefinition/WidgetSet/Widget Widget] in the [wiki:ApplicationDefinition/WidgetSet WidgetSet].  So how exactly does Fusion turn this small amount of HTML and XML into a functional web mapping application?
    143143
    144144The first  important step is including fusion.js in your web page (the first script tag in the ''Hello Sheboygan'' example).  This makes Fusion available to your application.  The second important step is invoking the {{{Fusion.initialize()}}} method during (or after) the '''onload''' event of the web page (the contents of the second script tag).  {{{Fusion.initialize()}}} starts the process of getting the application running and the following steps happen:
    … …  
    147147 * the ApplicationDefinition configuration file is loaded and parsed
    148148 * Widgets with associated HTML elements are identified
    149  * the !JavaScript file associated with each identified Widget is loaded
    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 
    154 An important step in this process is the loading of the Map Widget(s).  After each Map Widget has been created, it:
     149 * the !JavaScript file associated with each identified [wiki:ApplicationDefinition/WidgetSet/Widget Widget] is loaded
     150 * any dependencies of the [wiki:ApplicationDefinition/WidgetSet/Widget Widget] are loaded
     151 * when all [wiki:ApplicationDefinition/WidgetSet/Widget Widgets] (and their dependencies such as CSS files) are loaded, a new instance of each [wiki:ApplicationDefinition/WidgetSet/Widget Widget] is created for each HTML element.
     152 * when all [wiki:ApplicationDefinition/WidgetSet/Widget Widget] have been initialized, the {{{FUSION_INITIALIZED}}} event is emitted.
     153
     154An important step in this process is the loading of the [wiki:ApplicationDefinition/WidgetSet/MapWidget MapWidget](s).  After each [wiki:ApplicationDefinition/WidgetSet/MapWidget MapWidget] has been created, it:
    155155
    156156 * attempts to create a session with the server for that Map instance.  All Map instances of the same Type will share the same session.
    … …  
    160160   * issue a {{{MAP_LOADED}}} event when the map has finished loading
    161161 
    162 All Widgets in a !WidgetSet are associated with the !MapWidget of that !WidgetSet.
     162All [wiki:ApplicationDefinition/WidgetSet/Widget Widgets] in a [wiki:ApplicationDefinition/WidgetSet WidgetSet] are associated with the [wiki:ApplicationDefinition/WidgetSet/MapWidget MapWidget] of that [wiki:ApplicationDefinition/WidgetSet WidgetSet].
    163163
    164164== Fusion Architecture ==
    … …  
    179179The Fusion Server components work directly with the !MapGuide Open Source PHP API to implement specific functionality such as buffering features and working with selections.
    180180
    181 The 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 
    185 The 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 
    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 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 
    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.
     181The Fusion !JavaScript API and [wiki:ApplicationDefinition/WidgetSet/Widget Widget] are installed with the !MapGuide Open Source Web Tier, but they are actually loaded up to and executed in the Client Tier.
     182
     183== [wiki:ApplicationDefinition ApplicationDefinitions], HTML and [wiki:ApplicationDefinition/WidgetSet/Widget Widgets] ==
     184
     185The API and [wiki:ApplicationDefinition/WidgetSet/Widget Widget] are linked to specific HTML elements within an HTML page through the !ApplicationDefinition XML document.  A [wiki:ApplicationDefinition/WidgetSet/Widget Widget] is the executable code (!JavaScript class) that is loaded when Fusion identifies an HTML element id and [wiki:ApplicationDefinition/WidgetSet/Widget#Name Widget Name] that are the same.  The Type of the [wiki:ApplicationDefinition/WidgetSet/Widget Widget] identifies the exact !JavaScript file to be loaded and the !JavaScript object that needs to be instantiated to create a functional [wiki:ApplicationDefinition/WidgetSet/Widget Widget].  The runtime instance of the !JavaScript object is the [wiki:ApplicationDefinition/WidgetSet/Widget 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 [wiki:ApplicationDefinition/WidgetSet/Widget Widget] is placed in the ApplicationDefinition [wiki:ApplicationDefinition/WidgetSet/Widget Widget] XML block as sub tags (each [wiki:ApplicationDefinition/WidgetSet/Widget 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 [wiki:ApplicationDefinition/WidgetSet/Widget Widget] by overriding the CSS styling for the [wiki:ApplicationDefinition/WidgetSet/Widget Widget], this is normally done by using the {{{#<id>}}} syntax to limit your changes to that specific [wiki:ApplicationDefinition/WidgetSet/Widget Widget].
    190190
    191191
    … …  
    205205
    206206{{{Fusion.Event.FUSION_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().
     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 [wiki:ApplicationDefinition/WidgetSet/Widget Widgets].  Note that the [wiki:ApplicationDefinition/WidgetSet/MapWidget MapWidget], specifically, will be ready but may not have actually loaded the map.  There is a separate event for that .  Applications should register for this event before calling Fusion.initialize().
    208208{{{Fusion.Event.FUSION_ERROR}}}:
    209209  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.
    210210
    211 Widgets 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.
    212 
    213 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.
     211[wiki:ApplicationDefinition/WidgetSet/Widget Widgets] in Fusion also use and trigger events.  [wiki:ApplicationDefinition/WidgetSet/Widget 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 [wiki:ApplicationDefinition/WidgetSet/Widget Widgets] in the application.  However, there are cases (especially with the [wiki:ApplicationDefinition/WidgetSet/MapWidget MapWidget]) where it is important that [wiki:ApplicationDefinition/WidgetSet/Widget Widgets] be able to communicate with other [wiki:ApplicationDefinition/WidgetSet/Widget Widgets] or with the application as a whole.  For these situations, there is an event mechanism built into Fusion that allows [wiki:ApplicationDefinition/WidgetSet/Widget Widgets], and applications built on Fusion, to register for and trigger events.  The event mechanism allows [wiki:ApplicationDefinition/WidgetSet/Widget Widgets] to be independent of each other, but still provide a high level of integration when required.
     212
     213To register a callback function for a [wiki:ApplicationDefinition/WidgetSet/Widget Widget] event, the application must first obtain a reference to the [wiki:ApplicationDefinition/WidgetSet/Widget 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 [wiki:ApplicationDefinition/WidgetSet/Widget Widget].
    214214
    215215== Working with Maps ==
    216216
    217 In 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.
     217In Fusion, the [wiki:ApplicationDefinition/WidgetSet/MapWidget MapWidget] is central to everything that is going on.  It is not valid to design a Fusion application without a Map in it.  The [wiki:ApplicationDefinition/WidgetSet/MapWidget MapWidget] 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.
    218218
    219219The 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.