MapGuide RFC 167 - Unified Fusion template entry point and cleanup external base layer support

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	2 Aug 2018
Last Modified	2 Aug 2018
Author	Jackie Ng
RFC Status	implemented
Implementation Status	implemented
Proposed Milestone	4.0,3.1.2
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1	Jackie,Gordon,Reno,Martin
+0
-0
-1
no vote	Crispin,Haris,Trevor

Overview

This RFC proposes to introduce a new server-based PHP entry point to our existing MapGuide Fusion viewer templates and clean up how external base layers are supported.

Motivation

Fusion has 5 viewer templates:

• templates/mapguide/aqua/index.html
• templates/mapguide/limegold/index.html
• templates/mapguide/maroon/index.html
• templates/mapguide/slate/index.html
• templates/mapguide/turquoiseyellow/index.html

When a Fusion application is loaded, it is loaded with one of the above 5 templates with the ApplicationDefinition.

This loading process is done fully client-side which presents some difficulties in current browsers and in usage.

1. Using document.write for writing script tags, which is ​unsafe in modern browsers.
2. This unsafe technique is also being used to load supporting scripts for Google Maps, OpenStreetMap and Stamen tile layers. For OSM/Stamen, this is not even necessary (as base OpenLayers already has the required types to use these tile layers)
3. Various request ping-pong to fetch additional resources
4. Various usages of synchronous XmlHttpRequest
5. Switching to fusion.js for development or debugging is not readily apparent for users with a web development background.

Proposed Solution

New PHP entry point

We'll introduce a new PHP entry point for all fusion viewer templates that will address most of these issues

• templates/mapguide/index.php

This entry point takes all the existing supported parameters of the current templates, with support for the following additional query string parameters.

• template - The name of the template to load. The 5 templates now have an index.templ template file with the required placeholders that the entry point can make substitutions on
• debug - If set to 1 the entry point will load fusion.js instead of fusionSF-compressed.js (the production bundle). This makes debugging and development a much easier process as it does not require actual modifications to the underlying template to load the correct fusion script.

The entry point will also pre-load the Application Definition and serialize the content out to JSON in the template itself, avoiding the need to make a request for this content later.

If Google Maps is detected in the Application Definition, the Google Maps script tag will be rendered out to the template. The fusion script itself will no longer append script tags to support external base layers. This is now the responsibility of this new PHP entry point.

To ensure the new entry point is being used for any new Application Definitions being authored, the templateinfo of the 5 templates will be updated so that their template URLs refer to this new entry point.

Avoid loading scripts for OSM/Stamen

If OSM/Stamen tile layers are detected in the Application Definition, fusion will no longer try to load the following scripts:

• http://www.openstreetmap.org/openlayers/OpenStreetMap.js
• http://maps.stamen.com/js/tile.stamen.js?v1.3.0

The above scripts are merely convenience wrappers around layer types already present in OpenLayers.

• OSM (Mapnik) support is already serviced with OpenLayers.Layer.OSM
• Stamen and the other OSM layers (CycleMap/TransportMap) can be serviced with OpenLayers.Layer.XYZ

Such implementations are now inline, avoiding the need to load these scripts. Fusion will also ignore any references to <VirtualEarthScript> as Bing Maps is already supported with OpenLayers.Layer.Bing, so loading the script defined in this element is not required.

Fixing XYZ layer support

The previous section requires us to fix up the (incomplete) XYZ layer support in Fusion. For XYZ layer support to work, the Application Definition needs to define XYZ tile urls in the Application Definition.

As part of this RFC, fusion will look for the <urls> element in the options of a OSM or XYZ external layer definition. Multiple <urls> instances can be specified, if this is the case these URLs will be used in a round-robin fashion by the underlying OpenLayers.Layer.XYZ layer.

For example, you can consume the World_Topo_Map XYZ layer from ArcGIS online with the following XYZ external layer definition:

<Map>
  <Type>XYZ</Type>
  <SingleTile>false</SingleTile>
  <Extension>
    <Options>
      <name>ArcGIS Rest XYZ</name>
      <type>XYZ</type>
      <urls>https://server.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/tile/${z}/${y}/${x}</urls>
    </Options>
  </Extension>
</Map>

Note the ${x, ${y and ${z placeholders. This is required for any XYZ tile source URL you specify.

XYZ layers can also be used as an alternative OSM tile source (eg. You are hosting your own OSM tiles or you want to use ​OSM CycleMap or TransportMap layers without the API key watermark like so:

<Map>
  <Type>XYZ</Type>
  <SingleTile>false</SingleTile>
  <Extension>
    <Options>
      <name>OSM Custom Tiles</name>
      <type>XYZ</type>
      <urls>http://myalternativeosmtileserver1/${z}/${y}/${x}</urls>
      <urls>http://myalternativeosmtileserver2/${z}/${y}/${x}</urls>
    </Options>
  </Extension>
</Map>

Finally, proper XYZ tile support means that Fusion can finally consume ​XYZ Tile Set Definitions introduced in MGOS 3.0 by using a templated GETTILE mapagent URL as the XYZ tile source URL:

<Map>
  <Type>XYZ</Type>
  <SingleTile>false</SingleTile>
  <Extension>
    <Options>
      <name>MapGuide XYZ TileSet</name>
      <type>XYZ</type>
      <urls>http://localhost/mapguide/mapagent/mapagent.fcgi?OPERATION=GETTILEIMAGE&amp;VERSION=1.2.0&amp;CLIENTAGENT=OpenLayers&amp;USERNAME=Anonymous&amp;MAPDEFINITION=Library://Samples/Sheboygan/TileSets/SheboyganXYZ.TileSetDefinition&amp;BASEMAPLAYERGROUPNAME=Base Layer Group&amp;TILECOL=${y}&amp;TILEROW=${x}&amp;SCALEINDEX=${z}</urls>
    </Options>
  </Extension>
</Map>

Test Build

The work behind this RFC has been done in the following sandbox branches:

• MapGuide - ​fusion_entrypoint_refactor
• Fusion - ​cms_refactor

A test build that incorprates these changes can be found ​here.

Upon adoption of this RFC, the above sandbox branches will be merged into their respective trunk and 3.1 branches.

Implications

For developers who want to take advantage of this new entry point, the link migration strategy is as follows:

Template	Current URL	New URL
Aqua	fusion/templates/mapguide/aqua/index.html?...	fusion/templates/mapguide/index.php?template=aqua&...
LimeGold	fusion/templates/mapguide/limegold/index.html?...	fusion/templates/mapguide/index.php?template=limegold&...
Maroon	fusion/templates/mapguide/maroon/index.html?...	fusion/templates/mapguide/index.php?template=maroon&...
Slate	fusion/templates/mapguide/slate/index.html?...	fusion/templates/mapguide/index.php?template=slate&...
TurquoiseYellow	fusion/templates/mapguide/turquoiseyellow/index.html?...	fusion/templates/mapguide/index.php?template=turquoiseyellow&...

Users with custom fusion templates (assuming they follow the conventions of the existing 5 templates) can take advantage of this new entry point by providing an index.templ template file with the following placeholders:

• %__LIB_BASE__% - The URL base where the fusion script file (fusion.js and fusionSF-compressed.js) is based
• %__FUSION_SCRIPT__% - The fusion script file. This will be fusion.js if debug=1 and fusionSF-compressed.js otherwise
• %__TEMPLATE_BASE__% - The URL base for template specific content and assets (eg. stylesheets)
• %__SCRIPTS__% - If Google Maps is required, the necessary script tag will be rendered here.
• %__APPDEF_JSON__% - The JSON of the application definition that will be rendered here.

The existing index.html entry points in the current templates will not be removed with this RFC and can still be used, but developers should be aware that Google Maps support is only now available if the fusion template was loaded via the new PHP entry point.

Also, the index.templ of the 5 current templates modifies the Fusion.initialize() call to pass in the application definition JSON (injected through the %__APPDEF_JSON__% placeholder) to avoid a separate request to fetch and parse this content. Any custom fusion template that wants to take advantage of this new entry point will need to modify their Fusion.initialize() call to take advantage of the already pre-loaded application definition JSON.

Test Plan

Test end-to-end Fusion authoring workflows using the new template entry point. Verify with debug=1 on the entry point URL that fusion.js is loaded instead of fusionSF-compressed.js

Funding / Resources

Community