Wednesday, 21 February 2018

React-ing to the need for a modern MapGuide viewer (Part 20): It doesn't have to *specifically* be a URL

Wow! It's been 5 months since the last post related to mapguide-react-layout.

No I haven't stopped development. There's still plenty of things I want to achieve with this project before I consider it "done". It just had to take a back seat to other things that needed some attention:
Now that things have calmed down a bit, before I talk about the new release of mapguide-react-layout that will drop real soon, I want to talk about a capability of mapguide-react-layout that has been present for some time now, but I want to dedicate this entire post to because understanding this capability is the key in knowing how we can add new features to mapguide-react-layout yet retain the ability to use our existing Web Layout and Application Definitions to reference such new features.

I'm sure most of you should already be familiar with InvokeURL commands. You can define these commands in both a Web Layout and an Application Definition. They get represented in the AJAX/Fusion viewer as toolbar or menu items. When you click them, they invoke the specified URL into a given target (the Task Pane, a new window or a specific frame). InvokeURL commands is the basic gateway to custom MapGuide viewer functionality.

InvokeURL commands are also supported in mapguide-react-layout, except we can do extra things with such commands in mapguide-react-layout by leveraging the fact that a URL is merely a type of URI (Uniform Resource Identifier) and a URI ... does not necessarily have to start with http://. MapGuide resource identifiers (eg. Library://Foo/Bar.MapDefinition) are basically like URIs so this shouldn't be too much of a foreign concept.

So what does mapguide-react-layout do with this fact?

To demonstrate, here's a new feature that will be in the next release of mapguide-react-layout: A component to easily add external WMS layers

How can you access this new feature? Through an InvokeURL command.

Except, you don't invoke a URL you invoke a URI ... of our own custom creation.

As you can see from the above screenshot, we've invented our own component:// URI scheme to easily tap into new features in mapguide-react-layout without any structural changes required in the Web Layout or Application Definition schemas. We just leverage the existing InvokeURL command support and leverage the fact that whatever we're invoking in mapguide-react-layout ... doesn't necessarily have to be a URL. component URIs are structured as follows:

component://[component name][?query]

A component name refers to any component that's registered in the component registry. If a component can take parameters, you can pass them through the query string. Several components are available in the standard viewer bundle. The list of accessible components is available here.

If you use the npm module to roll your own custom viewer bundle, we provide APIs to allow you to easily create your own custom components. This is demonstrated in this example project.

The list of components available is small so far, that will grow over time as we add new features in future releases of mapguide-react-layout and the best thing about this is that to take advantage of such features, no changes to any authoring tools is required. You just have to enter a different kind of URI instead of a URL.

No comments: