Monday, 27 July 2009

The Expression Editor gets smarter (updated)

Once in a blue moon, you have an idea for something that's so awesome, that you obsessively try to implement it as fast as you can.

I present to you, intellisense for the FDO Toolbox Expression Editor!

This new feature will be in the next release of FDO Toolbox. This is obviously a first cut, and I'm sure the auto-complete may pop up at inappropriate times, but it's quite a usable first cut. It'll definitely make building expressions much easier.

Update: 29/7: This has been ported to Maestro, and it works in Mono!

Sunday, 26 July 2009

Coming to a mapguide open source installer near you...

... The ability to choose which FDO providers to install.

This works for both installation, and change (post-installation).

The only thing left to do here is to figure out in WiX how to initially disable the ArcSDE, Oracle, MySQL and PostGIS providers (since these providers require external libraries present) so that a "default" configuration works 100% out of the box.

Wednesday, 22 July 2009

fdotoolbox-users on Google Groups

I've finally created a google group for discussing FDO Toolbox. You need a Google Account to join.

Wednesday, 15 July 2009

Resource Templating in MapGuide

We've all heard about the benefits of templates and templating. It allows for reuse, consistency and standardisation. In this post, I'm going to illustrate how you can apply templating concepts to create reusable resource templates in MapGuide. Before we begin, I'm going to talk a bit about resources in MapGuide.

Resources in MapGuide are basically XML documents describing a whole host of assorted things. For example:
  • Feature Sources describe a FDO connection
  • Layer Definitions describe how a FDO feature class will be rendered
  • Map Definitions describe the layer structure and drawing order
  • Web Layouts describe the user interface elements of the AJAX viewer
  • Application Definitions (Flexible layouts) describe the user interface elements of the Fusion application
  • Symbol Definitions describe symbols
  • Load Procedures describe how a consuming application (ie. MapGuide Studio) would load a certain set of data.
These XML documents are sent back and forth from server to client (and back) via MapGuide's Resource Service API.

Consider a user who is editing a Layer Definition in MapGuide Studio or MapGuide Maestro. The following process occurs when the user opens the resource for editing.
  1. MapGuide Studio/Maestro issues a GETRESOURCECONTENT call to the MapGuide Server for a specified resource id
  2. Server returns the XML content for that resource
  3. MapGuide Studio/Maestro parses this XML content and presents this information in a layer editor user interface
Now consider the user has finished editing and saves the Layer Definition. The following process will take place:
  1. MapGuide Studio/Maestro rebuilds the XML document from the user interface.
  2. MapGuide Studio/Maestro issues a SETRESOURCECONTENT call to the MapGuide Server on that particular resource id. The XML content is sent across the wire and saved into the repository.
By understanding this basic resource editing concept, I can now illustrate how you can effectively create resource templates in MapGuide, using Web Layouts as an example.

Consider your standard AJAX viewer web layout.

Now perhaps you don't like the default toolbar/context menu layout, or perhaps you've decided on a standardised user interface for all your MapGuide applications. So naturally you would edit the web layout in MapGuide Studio/Maestro so that it matches what you're after.

Now imagine you are now creating another MapGuide application, but you need to maintain the same user interface as before. You could create a new Web Layout in Studio/Maestro and then edit it to match the previous one, or you could do the following:

1. Save the original web layout as an XML document.

Both MapGuide Studio and Maestro offer this function, you'll be asked to specify where you want to save the document.

2. Open the document in a text editor.

This is what the above Web Layout looks like (only part of the content shown to avoid a 20-page blog post :-) ):

3. Take out the map resource id and save it.

Or alternatively put some kind of textual placeholder in there so you know where to go. You now have a Web Layout resource template that can be reused for other maps.

So how do you use this template for other maps? Like so:

1. Get the resource id of the map in question

The resource id is similar to: Library://Path/To/My.MapDefinition

2. Open and Edit a copy of the Web Layout Template

Look for the map resource id element (or your textual placeholder, if you added one in) and put the above resource id in its place.

3. Save this document into the repository.

Here's where you need to understand how resource editing in MapGuide works under the hood (explained at the beginning of this post. Go on, I'll wait for you :-) )

So now the question becomes, how do you issue this SETRESOURCECONTENT call?

When Studio/Maestro are sending and receiving these commands and XML documents to/from the MapGuide Server, they are talking to a component of MapGuide known as the mapagent.

The mapagent is a public endpoint that exposes MapGuide's services to the outside world via HTTP. All MapGuide client components, whether it is Studio, Maestro, the AJAX viewer or the Fusion viewer are talking to this mapagent for most of their operations.

So now we know we have to talk to the mapagent to load our Web Layout document, but still how do we do it?

Well the mapagent comes with a rudimentary web-based user interface (rudimentary because it's designed for automated tests, not humans :-) ) that allows you to talk to the mapagent from your web browser. Assuming a standard Apache/PHP MapGuide installation, the mapagent web interface is located at:


For MapGuide Enterprise [year], it is:


What we want to do now, is locate the SetResource form, and bring it up

Looking at the fields, most are self-explanatory. We just need to specify:

a) The resource id where we want to save this Web Layout
b) The path of the Web Layout document to upload

So fill these values in and click Submit. You'll be asked for a username and password, because any mapagent operation to be performed requires authentication. So fill in the username and password for the Administrator and click OK.

Once that is done, you'll get a nice blank screen which is the mapagent's way of saying success. If you have Studio/Maestro open, refreshing it will now show your web layout right where you specified.

Load the AJAX viewer with this web layout and VOILA! You'll be greeted with the same identical user interface but with a different map.

This technique can be applied to any MapGuide resource (they are all XML documents remember), but it may prove cumbersome or error-prone for certain types of resources (eg. You could have "templated" Layer Definitions with consistent zoom levels and style rules, but the feature source you're referencing better have the expected feature class and properties, otherwise things will break)

... and that is how you can create reusable resource templates in a nutshell.

Wednesday, 8 July 2009

The expressive power of MapGuide Tooltips

One feature in MapGuide that some people may overlook (in terms of utility) is tooltips.

They look simple enough, you use them to display certain attributes when your mouse pointer is over a feature. But what some may not realise is how these tooltips are implemented in the AJAX (or Fusion) viewer.

These tooltips are implemented in the viewer as HTML div containers. What this means is that given some knowledge of basic HTML, you can create some really cool and powerful tooltips.

Case in point, I present to you exhibit A:

(from the MapGuide Application)

The HTML for this tooltip would be something similar to this (image only, I gave up on trying to escape markup in blogger):

In MapGuide Studio/Maestro this would translate as something like (image only for the same reasons):

It might look incredibly complex, but what that expression is basically doing is stringing together multiple fragments of HTML with specific feature class attributes. It's a bit cumbersome to have to use so many nested concat() calls, but the Expression Editor in MapGuide Studio can really help you here. It is also worth noting that there is going to be a cleaner concat() function in the near future, so until then this is the only way to do it.

Here's a practical example.

Google offers a free API that lets you generate dynamic charts and graphs all from a simple url. This graph below is one such example (right click and view the page source if you want)

This chart is basically a HTML img tag with the following url:,40&chs=250x100&chl=HelloWorld

If you study the url carefully, you'll see that there is a parameter asking for the values to be charted, and another parameter asking for the labels for these charted values. Now consider the Parcels layer of the Sheboygan sample dataset:

Suppose we want to represent the values of RYEAR, GEOEXTRA and RBLDGVC in a pie chart (I know this probably makes no sense from a reporting perspective, it's just for the sake of argument)

The tooltip expression for the Parcels layer would be something like:

When we now put our mouse over a Parcel, this is what we get:

Pretty cool eh? So now you may be thinking, how far can I take this?

If you know your HTML, you know that there is an element called IFRAME. Short for Inline Frame, this element allows you to "embed" other web content inside the iframe element. What this means is that, armed with the knowledge of iframes and MapGuide expressions, you can embed almost anything inside your tooltip!

I'll leave this to your imagination. But before you go too crazy on tooltips, just remember that the tooltip will always be following the mouse pointer, so it's kind of pointless to put HTML content that requires user input in there (like forms or buttons)

Happy tooltipping!
Update (19 August): Fixed the 2nd code image

Wednesday, 1 July 2009

MapGuide Migration Tool (finally updated)

Those of you who remembered when MapGuide Enterprise 2007 first came out, there was also a migration tool that allowed you to convert an existing MapGuide 6.5 dataset over to an MGE 2007 repository.

However, as new yearly releases of MapGuide Enterprise came out, the migration tool hadn't been updated to match the new releases, until now.

Autodesk have finally updated their data migration tool. Now you can migrate a MapGuide 6.5 dataset to a MapGuide Enterprise 2008, 2009 or 2010 repository.

As for me personally, I don't really have a need to use such a tool. It's great for a quick-and-easy migration job, but over time you (or your colleagues) will have to maintain that spatial data, and you really want to do it without the 6.5 cruft that may still reside in your spatial data. (eg. Breaking away from the restrictive Key/Url/Name trinity)

But if you've been stuck in 6.5 land and have just gotten started with MapGuide Enterprise, it's a nice way to easily migrate data. It is also a nice way to visualise how your 6.5 data looks like in 2008, 2009 or 2010, since MapGuide 6.5 and MapGuide Enterprise are totally different (architecturally and conceptually)