Use Case: Add a custom control to a map

[NickFitz]

This issue is for discussion of the use case “Add a custom control to a map”, its examples & list of required capabilities.

[prushforth]

MapML doesn't have a working solution yet, but we're thinking of static layers as one way to do this

[AmeliaBR]

"custom control" is a bit of a vague and all-encompassing topic. It may be useful to break this down into more specifics, for both the use case and the related capabilities (#57 and #58).

If I want to, for example, use a slider (<input type="range">) for zooming instead of +/- buttons, am I really "adding that to a map"? I am adding it to my web page, maybe positioned over top of the map, and then using the JS API to sync the map to slider input events. So the use case here is "Use custom HTML widgets to control the zoom of the map".

But I might also use a slider as a filter control that applies limits the set of displayed marker points according to some continuous data value (e.g., max price). The HTML/CSS for the slider could be very similar, but how it interacts with the map display is very different.

[NickFitz]

A "control" is a specific concept with associated interfaces in a number of client APIs, which distinguishes it from the more generic notion of some external code and UI element(s) that control the map. In particular, a control is indeed added to the map, being incorporated into the map's DOM hierarchy and ceasing to be under the complete control of the developer code that created it; it becomes part of the map's UI, on a par with the map's own UI elements. I've expanded the use case and related requirements to explain this in more depth.

[cmhodgson]

The key difference is the display and function of a map control which is "added to the map" is the responsibility of the map - it resolves the display of multiple controls, and resolves issues with multiple controls with overlapping functions (only one can be enabled at a time, etc). Writing custom controls which are not "added to the map" is really outside of the scope of the requirements, other than requiring that the map has an API for query and manipulation by code existing in the enclosing document.

[prushforth]

This is a really great discussion, and it cuts to the core of how maps can be disaggregated into lower level functions so that those functions may be recombined by HTML/CSS/JavaScript authors to make a "standard" map widget fulfill their needs.

There is the concept of custom control in libraries such as Leaflet, and they are built on top of (mostly) the API that is provided by Leaflet (using Leaflet as a presumed exemplar of how mapping libraries work YMMV). You can, and perhaps have to dig into the HTML/CSS of the (Leaflet) control in order to customize it in significant ways.

A few points:

"added to the map" should not only be taken to mean "added within the CSS margin of the map and at a very large z-index value" but should also mean anywhere in the enclosing document, in my opinion.

Not to bring up MapML , BUT since this discussion is about controls:

In MapML, the map author can include literal pre-baked HTML controls (well a couple that we have enabled, anyway) which can be used to control the map / tile / feature requests that are generated by the map when it pans and zooms (they are incorporated into the layer menu for the associated layer). There is also the notion that the map itself is a rectangular 'control' 'mapped' to the <extent> (or vice versa) of the MapML documents included in the <map> element's <layer> elements.

[AmeliaBR]

Ok, so "adding a control" to the map is not actually about controlling the map. You still have to hook up all your event handlers separately. Instead, adding a custom control for the map is more about passing in your custom HTML to the map layout code for positioning.

So, in a web components model, you could think of a <map-control> more like a container element:

<map-viewer>
  <map-layer>
     ...
  </map-layer>
  <map-control position="top right">
    <button>Reset</button>
     <!-- JS still needed to make this button do anything -->
  </map-control>
</map-viewer>

We should probably make that more explicit in the name/description of the use case. And in discussing the level of support for the related capability, it will be interesting to compare the different patterns for handling the positioning. E.g., Leaflet has a set of keywords for different control locations (topright, etc.), while Open Layers just adds the controls to a div & the author needs to position them individually with CSS.

[cmhodgson]

I think you've hit it right on the head with this, Amelia. I think that it is worth mentioning that "standard" (not custom) controls likely manage their own event handling and other wiring when they are added to the map, without needing explicit hooking up.