React-ing to the need for a modern MapGuide viewer (Part 14): The customization story so far.

I've been getting an increasing amount of questions lately about "How do you do X?" with mapguide-react-layout. So the purpose of this post is to lay out the customization story so far, so you have a good idea of whether the thing you want to do with this viewer is possible or not.

Before I start, it's best to divide this customization story into two main categories:

1. Customizations that reside "inside" the viewer
2. Customizations that reside "outside" the viewer

What is the distinction? Read on.

Customizations "inside" the viewer

I define customizations "inside" the viewer as customizations:

• That require no modifications to the entry point HTML file that initializes and starts up the viewer. To use our other viewer offerings as an analogy, your customizations work with the AJAX/Fusion viewers as-is without embedding the viewer or modifying any of the template HTML.
• That are represented as commands that reside in either a toolbar or menu/sub-menu and registered/referenced in your Web Layout or Application Definition
• Whose main UI reside in the Task Pane or a floating or popup window and uses client-side APIs provided by the viewer for interacting with the map.

These customizations are enabled in our existing viewer offerings through:

• InvokeURL commands/widgets
• InvokeScript commands/widgets
• Client-side viewer APIs that InvokeURL and InvokeScript commands can use 
• Custom widgets

From the perspective of mapguide-react-layout, here is what's supported

InvokeURL commands

InvokeURL commands are fully supported and do what you expect from our existing viewer offerings:

• Load a URL (that normally renders some custom UI for displaying data or interacting with the map) into the Task Pane or a floating/popup window.
• It is selection state aware if you choose to set the flag in the command definition.
• It will include whatever parameters you have specified in the command definition into the URL that is invoked.

If most/all of your customizations are delivered through InvokeURL commands, then mapguide-react-layout already has you covered.

InvokeScript commands

InvokeScript commands are not supported and I have no real plans to bring such support across. I have an alternate replacement in place, which will require you to roll your own viewer. 

Client-side viewer APIs

If you use AJAX viewer APIs in your Task Pane content for interacting with the map, they are supported here as well. Most of the viewer APIs are mostly implemented, short of a few esoteric APIs.

If your client-side code is primarily interacting with APIs provided by Fusion, you're out of luck at the moment as none of the Fusion client-side APIs have been ported across. I have no plans to port these APIs across 1:1, though I do intend to bring across some kind of pub/sub event system so your client-side code has the ability to respond to events like selection changed, etc.

Custom Widgets

In Fusion, if InvokeURL/InvokeScript widgets are insufficient for your customization needs, this is where you would create a custom widget. Like the replacement for InvokeScript commands I intend to enable a similar system once again through custom builds of the mapguide-react-layout viewer.

My personal barometer for how well mapguide-react-layout supports "inside" customizations is the MapGuide PHP Developer's Guide samples. 

If you load the Web Layout for this sample in the mapguide-react-layout viewer, you will see all of the examples (and the viewer APIs they demonstrate) all work as before. If your customizations are similar in nature to what is demonstrated in the MapGuide PHP Developer's Guide samples, then things should be smooth sailing.

Customizations "outside" the viewer

I define customizations "outside" the viewer as primarily being one of 2 things:

• Embedding the viewer in a frame/iframe or a DOM element that is not full width/height and providing sufficient APIs so that code in the embedding content document can interact with the viewer or for code in the embedding content document to be able to listen on certain viewer events.
• Being able to init the viewer with all the required configuration (ie. You do not intend to pass a Web Layout or Application Definition to init this viewer)

On this front, mapguide-react-layout doesn't offer much beyond a well-defined entry point to init and mount the viewer component.

Watch this space for how I hope to tackle this problem.

Rolling your own viewer

The majority of the work done since the last release is to enable the scenario of being able to roll your own viewer. By being able to roll your own viewer, you will have full control over viewer customization for things the default viewer bundle does not support, such as:

• Creating your own layout templates
• Creating your own script commands
• Creating your own components

If you do decide to go down this path, there will be some things that you should become familiar with:

• You are familiar with the node.js ecosystem. In particular, you know how to use npm/yarn
• You are familiar with webpack
• Finally, you are familiar with TypeScript and have some experience with React and Redux

Basically, if you go down this road you should have a basic idea of how frontend web development is done in the current year of 2017, because it is no longer manually editing HTML files, script tags and sprinkles of jQuery.

Because what I intend to do allow for this scenario is to publish the viewer as an npm module. To roll your own viewer, you would npm/yarn install the mapguide-react-layout module, write your custom layouts/commands/components in TypeScript, and then set up a webpack configuration to pull it all together into your own custom viewer bundle.

I hope to have an example project available (probably in a different GitHub repository) when this is ready that demonstrates how to do this.

In Closing

When you ask the question of "How can I do X?" in mapguide-react-layout, you should reframe the question in terms of whether the thing you are trying to do is "inside" or "outside" the viewer. If it is "inside" the viewer and you were able to do this in the past with the AJAX/Fusion viewers through the extension points and APIs offered, chances are very high that similar equivalent functionality has already been ported across.

If you are trying to do this "outside" the viewer. you'll have to wait for me to add whatever APIs and extension points are required.

Failing that, you will have the ability to consume the viewer as an npm module and roll your own viewer with your specific customizations.

Failing that? 

You could always fork the GitHub repo and make whatever modifications you need. But you should not have to go that far.