Announcing: MapGuide Maestro 5.0 beta 4 and 4.0.3 maintenance

It's been 2 months since the last beta (wow, time flies!), so here's a new beta release to make sure things are on the right track, with select bug fixes and minor enhancements backported to a new 4.0.3 maintenance release that's also available.

Here's what you can find in this release.

A Resource ID "address bar"

What is this new thing in the UI?

Ever notice MapGuide resource ids look a lot like URLs? So why can't we work with MapGuide resource ids like web site addresses? Enter the Resource ID "address bar". You can now open resources (or re-activate an existing open editor) by typing/pasting in the resource id and clicking "Go" or hitting enter on the address bar.

Due to the multi-connection nature of Maestro, you need to be specific about the connection that the resource id applies to when multiple connections are open, which is what the 2nd drop-down in the address bar is for.

The address bar serves double-duty, auto-updating when you select any resource in the Site Explorer, telling you its resource id.

Credit goes to Jason Birch, for floating this idea.

Live Map Definition Editor improvements

The Live Map Definition editor now sports a 3-pane interface, to give the legend the full vertical space it needs, and to make way for a new Repository View

The Repository View enables us to browse the existing repository from which this Map Definition is being edited and be able to drag and drop the layers we want onto the current map. There's still some way to go in improving usability. For this release, the only drag-and-drop action supported is dragging layers from the Repository View into the Legend. Other drag-and-drop actions will be implemented post-beta4.

Other Changes

I've covered plenty of other new features since the previous beta, so they're listed here

• Support for "exploding" themes into filtered sub-layers
• Better error dialogs for XML content errors
• Accurate style previews and support for previewing Symbol Definitions
• Improved Fusion editor support for OpenStreetMap
• and much more!

Download

Slicing and dicing themes into more manageable chunks with Maestro

Ever try to theme a layer and have this message thrown at you?

This message is shown for a reason. Having a 100+ theme is generally impractical:

• From a display perspective. Your viewer legend won't have enough vertical space to show such a large theme.
• From a performance perspective. There's a reason the AJAX viewer truncates such themes and Fusion before MapGuide 2.4 completely grinds your MapGuide Server to a halt. Your MapGuide Server would be spammed with Legend icon requests.

So what could you do if you have to show a large theme?

By using the "divide and conquer" approach, breaking this large theme down into smaller manageable sub-layers. A strategy would be to theme this layer by some common parent attribute (that has a smaller distribution of unique values), and then splitting off this layer into sub-layers that are filtered on each rule filter in the parent layer. From there, you could then generate specific smaller (and more manageable) themes for each of these sub-layers.

The next beta of Maestro will help you achieve this type of workflow.

The layer editor now has an "Explode Theme" button for each basic geometry style (disabled for composite styles as that is a whole different kettle of fish).

Clicking this button presents a dialog with some options for splitting this layer up.

Clicking "Create" will then generate these sub-layers.

If you open any of these sub-layers, you will see that it is based off of the same Feature Source and feature class, but it inherits the rule's filter, style and scale range.

From here, you can then generate themes that are only applicable for this sub-layer.

Previously there was a bug where generating a theme disregarded it's layer filter meaning you could generate style rules for a layer that will never actually have any matches. This bug has been fixed as a result of this new feature, because otherwise, you would still be seeing the same message above trying to generate the same theme for this sub-layer.

Next beta is coming real soon. Few more things to be fixed.

Improving the quality of XML content errors in Maestro

XML resource content model violations are a rarity in Maestro.

The Generic XML resource editor does client-side validation to ensure valid XML is sent back to the MapGuide Server. The specialized editors and APIs in Maestro will ensure that the minimum content model requirements for any given resource type are satisfied. But sometimes, we may have missed something and when that happens, having this error thrown at your face and displayed through the normal generic error dialog is not really helpful.

So with such errors (should they occur), you really want to see the offending XML content that triggered the error, and it just so happens that in the next beta of Maestro (and next 4.0.x stable release), we now have a specialized dialog just for displaying this particular class of errors.

So if you scroll down to line 491 of the XML content as indicated by the error details, you'll find that Maestro was not correctly building the minimum content model required for a particular fusion widget (which has been subsequently fixed thanks to this new feature)

Like I already mentioned, such errors are a rarity and should not be happening. But at least now if/when such errors do happen you now have the offending XML on hand to explain why it happened, which will greatly help me to ensure such cases never happen again in the future.

Improving the MapGuide API documentation (part 2)

Don't you bemoan the fact that you need to have the MapGuide API reference on hand because Visual Studio's intellisense doesn't really help you?

With my recent post-RC2 checkins, the intellisense becomes meaningful!

For those who don't know, the MapGuide .net assemblies are not pure .net classes. They are proxy classes to unmanaged C++ classes that reside in various unmanaged dlls that you must remember to copy along with your OSGeo.MapGuide assemblies to your application's output directory. A common rookie mistake is forgetting to copy these additional dlls. Referencing the OSGeo.MapGuide assemblies is not enough, you need to remember to copy these extra dlls.

We use a popular tool called SWIG to create the proxy wrappers not only for .net, but also for PHP and Java (which is how we can have the MapGuide API in these 3 different languages). A major downside to using SWIG is that API documentation fragments get lost in translation, so you always needed to have the API reference on hand if you ever needed to know what a class or method does.

So given these facts, how did we achieve this?

It turns out that doxygen supports XML output of your C++ API documentation, meaning the class and member information gets written to nice and logically structured XML files.

Do you know what else is XML-based? The intellisense documentation files for .net assemblies. When you have two XML-based sources. Moving/translating data from one form to another becomes very simple.

The XML format for a .net assembly intellisense file is actually quite simple

As you can see, it's nothing more than a series of elements describing the various classes, methods and properties of the MapGuide API.

So with the help of a modified version of Doxygen.NET (a .net library that provides an object-oriented API into doxygen's XML output), I wrote a utility that parses the XML output of doxygen and writes out the equivalent .net intellisense XML file. The utility itself was very simple to write because the MapGuide API was designed and in a convention-based manner (needing to have bindings in 3 different languages kind of necessitates this design) and that allows us to make many valid assumptions:

• All .net proxy classes reside under a single namespace (OSGeo.MapGuide) despite being in 5 different physical assemblies.
• Only C++ classes are ever exported. No enums, structs or any other esoteric C++ features.
• Only methods and static fields are exported. No need to handle const correctness, pass-by-reference and other C++-specific ways of calling methods.

This utility produces 5 xml files (one for each OSGeo.MapGuide assembly) that when dropped side-by-side with their respective assembly will cause Visual Studio to use them for documenting any classes and methods that appear in the auto-completion prompt.

The final release of MapGuide Open Source 2.4 will include these intellisense files. In the meantime, you can grab the 5 files from here and drop them beside your MapGuide .net assemblies. If those assemblies are already referenced in a project in an open instance of Visual Studio, you will need to reload that project's solution to get it to pick up the documentation files.

Oh and one more thing. If auto-complete does not show any documentation for a given class or member, it means the main API reference probably doesn't say much either, which goes to show that content-wise the documentation still has lots of room for improvement.

MapGuide Open Source 2.4 RC2 released

Get all the information and downloads from here

This release includes some AJAX viewer fixes and usability improvements to Fusion.

Any Fusion widget that uses a digitizer (eg. Measure, Redline), now takes advantage of the MapMessage component to "visually" tell you that digitization is in process. Previously the MapMessage component was only used for the QuickPlot widget, which is really an inefficient use for a component which has great utility in relaying notifications and messages to the user.

For example, here's what the viewer looks like during a "Select Radius" operation.

And here's how the viewer looks, when the Measure widget is active.

You get the idea.

But the main feature of the RC2 release is the improved documentation. Not only is the MapGuide API documentation gotten a touch up, but this release also includes for the first time ever: API documentation for Fusion!

For the longest time, not only did the Fusion build files not actually build the documentation (it's only built on certain steps that the normal MapGuide build process doesn't use), but the Fusion source itself was not annotated in a NaturalDocs-friendly manner, making the resulting generated documentation difficult to comprehend.

We've combed through the core and widgets to put at least basic class and method descriptions in the main APIs you would be working with in Fusion. The end result, is something that's passable for this release (some documentation is better than no documentation), but could definitely do with some improvement in the content department for future releases.

Linux builds of RC2 will follow shortly.

mg-desktop: The NuGet edition

So with the latest release of mg-desktop, I was supposed to have a NuGet version ready as well.

For those who don't know what NuGet is, it is a Visual Studio 2010 extension which basically functions like an apt-get for libraries and tools in Visual Studio. A command-line version of NuGet also exists.

It turns out nuget.org didn't like my original mg-desktop package which was 38MB in total, so I had to get creative in slicing and dicing this package down to sub-packages of reasonable size, without compromising the utility of the individual sub-packages. The resulting mg-desktop package is now a set of following sub-packages:

• mapguide-api-base
• mg-desktop
• mg-desktop Viewer

mapguide-api-base^ contains the core MapGuide API components

• Foundation
• Geometry
• PlatformBase
• A subset of the CS-Map coordinate system dictionaries

This package is sufficient enough to build applications using only the Coordinate System and Geometry APIs of MapGuide, though you will need to set up the coordinate system dictionary path manually as there is no Platform.ini (which defines this path) to initialize if you are solely using this package. So you will need to have the MENTOR_DICTIONARY_PATH environment variable defined, or point the path manually like so.

mg-desktop* contains the mg-desktop specific components. It has a dependency on mapguide-api-base and will download/install it too if required. This does not have the viewer component, which is a separate package.

mg-desktop Viewer is the viewer component for mg-desktop. It has a dependency on mg-desktop and will download/install it too if required. It will also auto-reference System.Windows.Forms and System.Drawing in your project if needed.

So depending on your particular needs, you select the appropriate packages with NuGet, which will download the required packages/dependencies and automagically set up everything for you (references, post-build steps, etc).

One important thing to note about this package is that it the 32-bit build of mg-desktop for .net Framework 4.0. You cannot consume this package for .net projects whose framework version is < 4.0 and in order for your application to run on 64-bit systems, the root executable project must be explicitly set to x86 and not AnyCPU. Stick with the zip distribution if you are using .net Framework 3.5 or older.

The other important thing to note is that this is my first NuGet package upload. My NuGet n00biness is on full display :-) If there are any problems with any of the packages, I'd appreciate any pointers or patches sent my way to fix these problems.

Download

• mapguide-api-base package home
• mg-desktop package home
• mg-desktop viewer package home

^ I'll probably split off the CS-Map dictionaries into a separate package in a future version. Also if I ever decide to NuGet-ify the official assemblies for MapGuide Open Source 2.4, it will definitely have a dependency on this package.

* Likewise, I'll probably split off FDO into its own package

(Ab)using GETLEGENDIMAGE for maximum profit

For most users, the GETLEGENDIMAGE operation in MapGuide is usually for constructing the icons you see in the legend, like so:

But if you look beyond the 16x16 pixel box, you will find (like I just did) that this operation is an ideal way to "preview" a given style rule for a Layer Definition.

So much so, that the next beta of Maestro 5.0 will now use GETLEGENDIMAGE for previews in all style editor dialogs (except for labels), replacing the existing "simulated" preview that used System.Drawing APIs to approximate what the resulting style would look like.

We say approximate, because MapGuide has dedicated components for Rendering and Stylization that would be painstaking to fully replicate with System.Drawing APIs. Remember that Maestro is a fully managed .net application, so we can't just tap into unmanaged libraries willy-nilly, unless the feature in question is deemed to be windows-only, like the Local Connection feature introduced in Maestro 4.0.

Take for example, a polygon style with a pre-defined pattern.

Or a line styles with composite lines, something where our simulated previewing mechanism definitely breaks down.

So GETLEGENDIMAGE can be trusted to show the correct style (which is sort of its intended purpose, now that I think of it), so we can now exploit this function for maximum payoff:

Previewing Symbol Definitions!

You don't have to house a reference to a Symbol Definition inside a Layer Definition in order to preview it. Symbol Definitions can now be previewed on their own!

Now things aren't fully rosy yet. The top level previews are still done with the imperfect System.Drawing method

And composite styles are still as meaningless as ever.

And things will probably stay that way for now. The reason is simple. If we wholesale replaced this method of previewing with the GETLEGENDIMAGE approach, each style rule in that Layer Definition would require a GETLEGENDIMAGE request to be sent.

And if we've learned anything about one of the main pain points of Fusion in the past, it's that a MapGuide Server doesn't like to be bombarded with 100s of GETLEGENDIMAGE requests at once. So we're sticking with the imperfect preview method for this case, on the assumption that if you want to see what the style really looks like, you would bring up the style editor dialog for that rule to see for yourself.

I may revisit this problem again in the future if we ever do get support for requesting a set of legend images in a single batch but until then, if you ever want to see the actual style, just simply fire up its style editor dialog.