New mg-desktop binaries

Coinciding with the final release of MapGuide Open Source 2.5, is a new release of mg-desktop.

So if you're wondering that that screenshot was all about, that was a simple test application using the new experimental Java API for mg-desktop. This is based on the enhanced Java API work for the Web API in 2.5, so it has none of the cruftiness of the original MapGuide Java wrapper API.

The Java API is also windows only as the MapGuideDesktopApi.jar is a SWIG-generated JNI wrapper around the native mg-desktop libraries. Since these libraries currently only exist as windows dlls, this jar obviously will not work on platforms that are not Microsoft Windows.

This Java API is there so you can explore what can be done with mg-desktop in the Java ecosystem. I myself am not fully proficient in Java (the platform) to be able to extend mg-desktop in Java in the same way as I have done for .net (so uh ... is swing still what you use for GUIs in Java?).

The Java API is only bundled with the zip package of mg-desktop. The mg-desktop nuget package does not include the Java API (it wouldn't make much sense to include it either).

Besides the new experimental Java API, mg-desktop itself has some small API enhancements as well:

• IMapViewer now includes a new overload of SelectByGeometry() that accepts a callback and allows you to do "one-shot" programmatic selection that does not trigger the selection events that are normally raised by the viewer and does not require event subscription/unsubscription.
• The MgdRenderingService::RenderDynamicOverlay() method now has a new behaviour flag value (8 to render base layers). If you logically OR this new flag value into the rendering options behaviour, your overlay image will include the map's base (tiled) layers as well. This means that you no longer have to use the RenderMap API to get a map image that includes tiled layers, and this one has the advantage of not having it's background pre-filled (it's an overlay image after all). Secondly this new behaviour is the viewer default, meaning you don't have to use the currently documented workarounds and also means that pre-rendering hooks in the viewer are actually useful on a map with tiled layers for once!

For this release, I've decided to stop doing .net 2.0 builds of mg-desktop. It's just too much effort to produce a .net 2.0 build of mg-desktop nowadays  For a .net 2.0 build, the whole FDO/MapGuide stack has to be built in VS2008. Whereas with .net 4.0 build, we can just ride the coat-tails of the current MapGuide Open Source build process where 80% of the stuff is already built for us. Plus I'd figure most of you would be on .net 4.0 anyway. 

This means that the mg-desktop build used by the Local Connection mode in Maestro 4.0.x will forever be on the same version as it is right now. Maestro 4.0.x is a maintenance branch that we aren't actively developing new features into so this shouldn't be much of an issue.

On the nuget front, this release replaces the 2.4 series. I'm not sure if this is how new versions are supposed to be put out as nuget doesn't really have the notion of "branches". If you install a new mapguide nuget package, it will now be pulling down the 2.5 package by default unless you explicitly specify the version number.

So a command like this:

Install-Package mapguide-api-base-x86

will install the 2.5 version of the package (this release), but a command like this:

Install-Package mapguide-api-base-x86 -Version 2.4.0.7096

will install the latest 2.4 package. If you don't know the specific number, you can hit tab after the -Version parameter and the Package Manager Console will display an autocomplete prompt with all the applicable versions. You want to pick the latest major.minor version that matches the installed major.minor version of MapGuide that you're working with.

Something to take note of if you're building MapGuide web applications where the version you're working with matters, or if you need to fetch the correct CS-Map dictionaries for an older mg-desktop package.

Download

MapGuide packages on nuget.org

MapGuide Open Source 2.5 released

Here it is! The final release of MapGuide Open Source 2.5.

Download

This final release includes the following changes from RC2

Fusion

We landed in a big changeset which should put this whole saga of conflicting widgets behind us:

• Quick Plot, Select Radius and Select Polygon widgets are no longer mutually-exclusive widgets. For Select Radius/Polygon this means they are now "click once to select once" affairs. If you need to re-select, just re-click the menu/toolbar item.
• All digitizer actions now raise a new MAP_DIGITIZER_ACTIVATED event when digitization begins and raise a new MAP_DIGITIZER_DEACTIVATED event when digitization stops. All widgets that would require the user to draw a geometric shape will raise these events
• The maptip, pan and zoom widgets will disable/restore themselves on these digitizer events to prevent them for interfering with you drawing your geometry. You can still mouse wheel zoom while digitizing, panning while digitizing is not possible. Ideally, we'd like to still pan around while digitizing with the middle mouse button, but the mouse button is hard-coded in OpenLayers :( Something that's nice to address in the future.
• Fix the z-index on the Scalebar widget which caused it to be drawn *below* the map viewer.
• Small UI tweaks on the FeatureInfo/Query/Redline widgets
• All digitization prompts now have a cancellation link attached just in case the manual button (eg. Measure) or ESC key cancellation method is not available

Other changes

• MgException::GetDetails() now includes the stack trace information as per API documentation.
• MgFeatureService::UpdateFeatures() should now behave correctly in non-transactional mode. This API should finally behave as described in the API documentation and my dedicated post to it.

What's next?

I've been trying to push for faster release cycles (I think we can all agree 2.4 to 2.5 has been much faster than 2.2 to 2.4), but realistically I don't think we will see a 2.6 release until early 2014 at the most.

This is because MapGuide is strongly tied to FDO and unlike MapGuide, I don't have much influence with FDO's release cycle. I don't really want to put out new releases of MapGuide that use a trunk build of FDO unless they're preview releases. I cannot consider starting a release cycle for 2.6 until the next FDO at least hits beta and since history has shown that new binary releases of FDO happen around December-April, we should try to adjust the MapGuide release cycle to be in sync with FDO as much as we can.

This isn't necessarily a bad thing. As it means we have plenty of time in the interim to land in this backlog of new features that couldn't make it into 2.5 and flesh out some sandboxed work into fully working new features that can realistically land in 2.6.

So I guess what that means realistically is that in terms of any future MapGuide releases this year, you'll probably only be seeing 2.5.x point releases and maybe the occasional 2.6 preview release as a "snapshot" of what's happening for 2.6. 2.6 proper probably won't happen until 2014 ticks over.

Not all is quiet on the mg-desktop front

Looks like it's working so far!

Announcing: MapGuide Open Source 2.5 RC2

I was wrong.

I thought we would only need one RC before pumping out the final release, but the amount of fixes, polish and shine that's been done to Fusion since RC1 is such that a second RC is warranted.

The changes from RC1 are mostly Fusion-centric, and it's a big list.

Templates

We've fixed up some annoyances that are present in the 5 templates that come with MapGuide

Toolbar text on the TurquoiseYellow is much more legible. Black text on a black gradient toolbar did not scream readability

The templates also had various behavioural fixes to improve the user experience:

• The sidebar of the LimeGold template could not be expanded once it was collapsed
• For templates with collapsible sidebars, they will re-expand the sidebar if the user invokes any of the (Show Legend/Overview/TaskPane/SelectionPanel) menu items, or a widget has loaded content into the Task Pane.

Greater Widget Autonomy

Some widgets were treated as mutually exclusive widgets. That meant, if you invoke this widget, it became the active widget. These widgets had no business hijacking the active widget state and brought unnecessary confusion to the user experience. The widgets in question are:

• Redline
• Buffer
• Feature Information
• Measure
• Query
• Theme

These widgets all load their UIs into either the Task Pane or a popup window. As long as you can see their UIs, they should be considered active. These widgets are pretty much like Invoke URL widgets anyway: Self-managed and independent of the active widget state. 

Having their UIs open should not interfere with panning/zooming/selecting/etc. The above widgets have been modified to no longer take over or care about active state. In addition certain widgets on that list have been modified to be more self-contained, which are detailed below.

Redline

The Redline widget hasn't changed much since the last time I wrote about it. However, we did discover afterwards that SHP-based import/export was broken on Linux due to missing ZipArchive support in its bundled PHP. That has been fixed.

Measure

This widget was a prime offender in bad user interactions, the offence being leaving dangling digitizers behind. You could be panning or zooming, and it would still be measuring because the digitizers weren't deactivated and/or properly cleaned up. Other widgets on that list above shared some of the same problems with this widget, but the Measure widget was the worst of them all.

We've changed this widget in the following ways to ensure such a thing doesn't happen again.

The widget still auto-initiates measurement, but we've added manual controls to the UI to stop/start this process.

In addition, we've added an abort link to the information bar in case the Measure UI is easily hidden or obscured (eg. In the Aqua template)

Feature Information

The layers dropdown now has a refresh link, so you don't have to re-invoke the widget to refresh this list.

Query

To be consistent with every other widget that uses a digitizer, the digitizing actions in this widget now use the Information Bar to provide digitization prompts.

The widget also cleans up any active digitizers when unloaded. Part of the greater widget autonomy and self-management that I mentioned above.

Legend

The legend widget now properly displays layer nodes above the group nodes at any level in the tree, thus syncing up with the AJAX viewer and presenting the exact visual representation of your layer/group structure as shown in Maestro's Map Definition editor

Scalebar

We have a scalebar widget? Yes we did, it just didn't work until now. What you saw here is the functional scalebar widget.

ScalebarDual

We have this widget too? Yes we did. This is basically a wrapper around the OpenLayers.Control.ScaleLine control. You couldn't access and include this widget with your Flexible Layouts because it didn't have a widgetinfo XML file.

CTRLClick

This widget doesn't actually exist (hasn't for a long time), but its widgetinfo XML file was still there, thus having Maestro give you the false impression that this widget actually exists and can be added to your Flexible Layouts. Well this is definitely not the case, and the widgetinfo XML file has been removed meaning Maestro will no longer show this widget.

Center Selection

Here's another broken widget that's been fixed for this release.

Selection Panel

Did you know this widget is actually configurable with extension properties? Yeah, we didn't document them in the widgetinfo XML, that's why Maestro shows nothing for this widget. That's fixed now.

Did you also know this widget has a horizontal representation as well? Yeah, that was broken too, but fixed for this release as well.

Non-Fusion Miscellany

For this release, we've also officially deprecated Mapping Service APIs related to eMap DWF functionality. The front-end DWF map viewer was deprecated a long time ago, but nothing was official in terms of API documentation about the Web APIs that supported this viewer. Thanks to our SWIG enhancement work, you'll get nice C#/Java compiler warnings when using these APIs. 

We're doing this because eMap functionality support has been long since removed from the DWF Toolkit and MapGuide is still currently hamstrung on a super-ancient version of the DWF Toolkit due to the need to support eMap, which could also present interoperability problems with newer versions of AutoCAD and its verticals (that would be using newer versions of the DWF Toolkit). I've seen several DWF files plotted from MapGuide crash recent versions of Autodesk Design Review probably due to this reason.

Being stuck on an old DWF Toolkit was also one of the roadblocks in my failed 64-bit Linux experiment. And you know why MapGuide still doesn't support DWFX files? Same reason.

Not saying that this is what we're definitely going to be doing with a new DWF Toolkit, but it clearly shows what's stopping us from doing so (eMap support). So if we ever do upgrade our DWF Toolkit, we should at least give a one release-cycle warning. If you happen to still be using the DWF-based map viewer and/or the supporting Web APIs, this is your final boarding call to either migrate or seek alternative solutions.

I'm pencilling in a final release of 2.5 one week from now. What you see in this release will be pretty much be what's in the final release. Any issues filed against this release will be shelved to 2.5.1 or 2.6 unless those issues are of the really show-stopping nature.

Download

MapGuide tidbits: Fusion/AJAX Viewer similarities and differences

Disclaimer: Some of the Fusion examples here use a testing build of Fusion made after the release of MapGuide Open Source 2.5 RC1 and as such may not be reproducible on that and earlier releases of Fusion.

For this post, we're going to focus on the differences between the AJAX and Fusion viewers and their similarities.

Similarities

On a conceptual level, there are actually many similarities between the AJAX Viewer and Fusion.

• Both have a way of defining a discrete piece of application functionality. Fusion has Widgets. AJAX Viewer has Commands
• Both have to be defined within a master collection of functionality (WidgetSet in a Fusion Flexible Layout, CommandSet in a AJAX Viewer Web Layout)
• UI References to these widgets are defined in the viewer's menus and toolbars (Abstracted in Fusion Flexible Layouts as "containers". Menus and Toolbars are fixed in the AJAX Viewer Web Layout)
• Both Flexible and Web Layouts need a Map Definition specified, which all the Widgets/Commands will be interacting with.

These conceptual similarities are reflected in the similar editor workflows in Maestro.

Specifying a Map (AJAX Viewer)

Specifying a Map (Fusion)

Defining the master set of functionality (AJAX Viewer)

Defining the master set of functionality (Fusion)

Laying out menu/toolbar access to this functionality (AJAX Viewer)

Laying out menu/toolbar access to this functionality (Fusion)

This is where the similarities end

Differences (especially on widgets)

Each AJAX Viewer command type is unique with their own specialized set of configuration parameters (ie. Each command type is its own specialized XML data type in the Web Layout XML schema)

Each Fusion widget is unique, but is driven through arbitrary XML elements under the widget's "Extension" XML element. The valid XML content that can reside under the widget extension is defined by the widget's respective widgetinfo XML. Here's an example widgetinfo for the Task Pane widget. This widgetinfo XML is how Maestro is able to not only build the default XML for that widget, but also provide additional information/description about each Extension Property for that widget.

It is this arbitrary XML configuration nature of Fusion widgets that allows the ApplicationDefinition XML schema to stay the same (since the introduction of Fusion in MapGuide Open Source 2.0) and allows for individual widgets to be improved upon with additional features and properties without needing to do endless XML schema revisions (as is the case with the AJAX Viewer Web Layout)

Widget Types

In Fusion there is are two separate types of widgets

1. Dockable widgets
2. Non-dockable widgets

(NOTE: I'm not sure about the official terminology here, but this is the lingo I'm using for the Fusion Editor UI changes you'll see in the next release of Maestro 5.0, some of which I'm also previewing in this post)

Dockable widgets are widgets that can be housed within a Fusion "container" (ie. A menu or toolbar)

Non-dockable widgets cannot be docked within a Fusion "container". The Legend and TaskPane widgets are examples of such widgets.

The layout of such non-dockable widgets is generally handled by Fusion and its template. If such a widget is included in the Flexible Layout, Fusion will render the widget UI into the DOM element of the template with the same id. For the 5 templates that come with MapGuide, all the necessary DOM elements are set up for such widgets to be rendered into, so you generally do not have to concern yourself with such plumbing details.

The only time you need to be concerned with such details is:

1. You are creating your own Fusion template
2. You are using a non-standard non-dockable widget.

If you are creating your own Fusion template, you need to make sure that either declaratively or programmatically that your template provides a DOM element whose id matches the type of non-dockable widget that Fusion could render into. I won't go too much into this detailed topic, because this would most likely have to be a subject of a separate post.

If you are using a non-standard non-dockable widget (eg. Scalebar), it won't show if the template does not provide a DOM element with a matching ID, which is probably the case with the 5 standard templates. I'll show to get such widgets working later in this post.

Now the reason I want to emphasize this distinction between dockable and non-dockable widgets is because as of the latest beta of MapGuide Maestro 5.0, the Fusion editor failed to make this distinction, meaning it was possible to do illegal things like this:

And then have your Fusion template break down for the most cryptic of reasons. So we've fixed this up 2 ways.

Firstly, when you add a widget to a container, non-dockable widgets are filtered out, making it impossible to cause scenarios like the one above.

Secondly, we've tweaked the Widget Management dialog to show you which widgets are dockable and which ones are not.

Non-dockable widgets will auto-render into the template's DOM by Fusion just by existing in the Widget Set. There is no layout/placement work required on your part. That is all handled by Fusion and the template you're using. This gives a nice segway back into our Scalebar example.

The Scalebar is a non-dockable widget, and probably exists in any new Application Definition document you create in Maestro. So where is this scalebar when we load the template up with our Application Definition?

If you look at the HTML of the template (Slate). You'll come to find that there is no div in the markup or created programmatically in the template's JavaScript that has an id of "Scalebar". This is why our scalebar does not show, because Fusion could not find the matching DOM element in the template for the Scalebar widget to render into.

So to fix that, we need to put in a div with that id into the template's index.html.

(NOTE: I myself am not sure if there are any DOM placement rules we have to follow, I'm just going by a suggestion from the mapguide-users mailing list. This is a trial and error process at the moment)

If we reload the template now, you should finally see our mystery scale bar widget!

So for such non-dockable widgets (which the next release of Maestro 5.0 will help you distinguish), it's best to double-check your Fusion template's HTML/JS to make sure such widgets can be displayed.

Hopefully, this post sheds more light on how Fusion and AJAX viewers are similar, but also how they're different. But more importantly the ins and outs of widgets, the fundamental building blocks of a MapGuide Fusion application.

MapGuide tidbits: Localization

MapGuide Maestro makes translating your MapGuide applications much simpler, but this is only half the equation. MapGuide Maestro only assists in translating your Menus and Toolbars of your viewer application. The viewer itself may require translation.

I've authored up a section of the MapGuide wiki several months ago, that covers all the localization tasks you need to do to fully translate MapGuide to your desired language.

Hope this helps.

MapGuide tidbits: The MgMap constructor

Question. How do you create your MgMap objects. Like this?

MgMap map = new MgMap();

If you do, please stop. Not only is this way of creating a MgMap object long been deprecated (thanks to RFC129, you'll now get nice C#/java compiler warnings about it), but you lose access to a whole bunch of convenience APIs that have been introduced with RFC9 (ie. MapGuide Open Source 1.2)

• MgLayerBase.GetClassDefinition()
• MgLayerBase.SelectFeatures()
• MgLayerBase.SelectAggregate()
• MgLayerBase.UpdateFeatures()
• MgSelectionBase.GetSelectedFeatures()

These APIs are only available if your MgMap was created like so:

MgSiteConnection siteConn = new MgSiteConnection();

...

MgMap map = new MgMap(siteConn);

This constructor is deprecated along with a whole bunch of other related MgMap methods. See the RFC for more information. You should be using the alternatives as described in that RFC.