Add map permalink functionality

[chrismayer]

Goal is to add a simple permalink functionality for the map state like it is done in http://openlayers.org/en/latest/examples/permalink.html

[justb4]

We are looking into this in a project. I paste some comments here, as there are implementation options.

First there is map basic context as in
https://openlayers.org/en/latest/examples/permalink.html#map=12.659486938142972/1107025.7/7011582.75/0

But the encoding is somewhat specific, would require specific parsing (of '/' separated) and one always needs a complete spec including rotation.

Two real-world examples:

• France national geoportal:
  https://www.geoportail.gouv.fr/carte?c=4.527906651375692,44.98704671209671&z=14&l0=GEOGRAPHICALGRIDSYSTEMS.MAPS.SCAN-EXPRESS.STANDARD:WMTS(1)&permalink=yes

• Swiss topo portal:
  https://map.geo.admin.ch/?topic=swisstopo&lang=en&bgLayer=ch.swisstopo.pixelkarte-farbe&E=2560256.11&N=1256280.28&zoom=4&layers=ch.swisstopo.zeitreihen&catalogNodes=1392&layers_timestamp=18641231&swipe_ratio=0.56

These also have sharing (buttons) options (link, embed iframe) possibly separate issue.
Important is that both examples above are not using the location hash (#) but query (? &) params.

I've implemented location hash before, example:
https://app.map5.nl/nltopo/#osm/opentopo/13/5.758038/52.31908

One big disadvantage (over query params) I found (also in the OL example above) is that the browser back-button and history is "screwed up", i.e. goes through previous map-contexts i.s.o. previous web-page. (Or I missed something there).

Maybe both options are possible as a config option when at least the permalink format is standardized, I propose: <?|#>c=<x>,<y>&z=<zoom>&r=<rotation> as minimum. More extended implementations may add Layers, projection, popups,tabs etc. In all cases we can use URLSearchParams to parse either location.hash or location.search based on config option. I've even seen implementations that have the parameter names as config option, or a param-prefix like map_ to get map_z etc, as to avoid collisions with server-side or other components (like vue-router). The prefix with default empty string is a good option.

[dkerkow]

This sounds reasonable to me. Just one thought that I would like to add:

What about using the map bounds instead of the map center?

When using only the map center and zoom, the resulting map extend would be drastically different on different screen dimensions, like desktop and mobile (portrait oriented).

Using the map extent as hash would enable us to show a targeted area fully covered, no matter what device opens the link.

[justb4]

Ok, working on this... Yes, using extent i.s.o. zoom+center is an option. The WIP already uses a dedicated class PermalinkController as there is some state and events to manage and some config options and apps may have app-specific parameters, like open popups.

This could also be a config option: which Map (View) parameters to manage: center+zoom or extent, layerIds and possibly app-specific. There's already some (optional) config options: param-prefix, projection (e.g. WGS84), location (hash or search), so could be added.

[chrismayer]

An (more or less widely spread) app of mine also implements a kind of permalink protocol (which is its main purpose, see here):

https://apps.meggsimum.de/shareloc/share.html?zoom=8&X=10.469156495550259&Y=48.45685440920124&bgLayer=bkg.topplus-web-open&marker=48.496587610806586,11.656494140625&popupText=A%20marker

There I also decided against # for the reasons you mentioned. Again to keep things simple I'd pledge to use query params. If a hybrid approach (? and # ) is easy - why not but I wouldn't bother about # if it screws and blows things up.

Regarding concrete params: I would start with the most common ones having in mind that we might have to extend the list of params in the future.
Prefixing might be a good idea to avoid conflicts, but we should keep the prefix short to ensure the URL does not become too long too fast.

[justb4]

Update: the "fill-up" of browser history is IMO independent on the use of ? or #. It depends on the use of window.history.pushState() to remember map view state and the reverse: listening for window popstate events. So that could be a config option as well with sensible defaults.

The common use for the web is also that ? should be interpreted by the server and # by the client/browser. For example VueRouter makes heavy use of #. But anyway using location.search or location.hash is already a config option, just like history.

For layers my first thought is to use layer id's, as they should be unique (though sometimes lids are generated, though that could be done with a unique hash of layer URL and name).

Another requirement from our project is to use extent i.s.o. zoom+center as the latter can give very different views dependent on the device (desktop, tablet, mobile).

(I'll add my WIP as PR in moments).

[justb4]

Another thought on history: when the app provides a share button (link, email, embed) there is no need to keep history in browser address bar (and v.v.). IMO share button is a separate issue to open.

[chrismayer]

Done in #121