Make "Use Tiles", "Use Features" and "Use Multiple Extents" into format_options values that apply to the text/mapml format, passed by preview generator

[prushforth]

Use Features and Use Tiles

Currently the "Use Tiles" and "Use Features" checkboxes from the MapML extension module user interface establish the behaviour of the structure of all content for the layer, making it unnecesary to pass these values through the GetMap format_options parameter tokens when the format parameter is set to text/mapml. Although functional, this is not necessarily optimal because the administrator might need to create another layer to establish the same content's availability under a different state for these checkboxes, causing duplication and consequent potential for confusion and error.

This issue proposes to convert / map these user interface settings to format_options tokens and token values, so that WMS clients that are not the GeoServer layer preview client page may obtain text/mapml responses that conform to their needs, by supplying appropriate format_options tokens and values when the format parameter is in the text/mapml state.

In this issue, we create an explicit format_option boolean value for each setting ("Use Tiles" and "Use Features") that reflects the state of the checkbox BY DEFAULT, when generating the URL used in the <layer- src="..."> src attribute that is generated by the preview client page, so that the setting can be established dynamically by any WMS client without having to change the layer setting or add a copy of the layer in order that the client can use a different value for the setting.

Specifically:

"Use Tiles" checkbox controls the GeoServer format_options value named mapmlusetiles:false (default) | true

The unchecked setting conforms to mapmlusetiles:false (the default value)

and in the preview generation <layer- src="..."> URL, OMITS the format_options=mapmlusetiles:false parameter (because the default value is false).

The response text/mapml document will contain a <map-extent> element generated with WMS GetMap and WMS GetFeatureInfo (if the layer is queryable) request URL template(s) in the corresponding </map-link> tref value.

Conversely, the checked setting conforms to format_options=mapmlusetiles:true:

and in the preview SETS the parameter format_options=mapmlusetiles:true in the <layer- src="..."></layer-> src URL value, which should lead to a text/mapml document containing a <map-extent> element containing a <map-link rel="tile" tref="..."></map-link> with the tref set up to either create tile-shaped WMS requests if no appropriate GWC GridSet exists, or if a GridSet exists will contain a GetTile URL template.

"Use Features" checkbox controls the GeoServer format_options value named mapmlusefeatures:false (default) | true

works similarly.

The unchecked setting conforms to mapmlusefeatures:false (the default value)

and in the preview generation <layer- src="..."> URL, OMITS the format_options=mapmlusefeatures:false parameter (because the default value is false).

Conversely, the checked setting conforms to format_options=mapmlusefeatures:true:

and in the preview HTML generator method sets the parameter format_options=mapmlusefeatures:true in the <layer- src="..."></layer-> src URL value, which should lead to a text/mapml document containing a <map-extent> element containing a <map-link rel="..." tref="http://.../?format_options=mapmlfeatures:true"></map-link>.

If present in a GetMap request for format=text/mapml, the mapmlusefeatures format parameter takes precedence over the mapmlfeatures format parameter, in that the generated text/mapml document will contain (if mapmlusefeatures:true is present) a <map-extent> containing a <map-link tref="https://.../?format_options=mapmlfeatures:true..."></map-link>, which will actually return the requested features, when processed.

In sum, mapmlusefeatures and mapmlusetiles parameterize the first level of MapML document (text/mapml) creation. in particular they control the content of generated <map-extent> elements. The mapmlusefeatures:true setting tells the <map-extent> generating machinery to serialize a <map-link rel="features" tref="URL template containing format_options=mapmlfeatures:true">, while the mapmlusetiles:true setting configures how the <map-extent>(s) are configured relative to tiling.

Multiple <map-extent> elements

The WMS-global boolean setting controls how multi-layer requests are serialized: when unchecked / false / in the default state, a GetMap request that refers to more than one layer results in a single <map-extent> with a single GetMap and a single GetFeatureInfo (if queryable), the URL templates for which contain the layers=layer1,layer2,layer3... layers parameter list. If the setting is checked, the text/mapml generator will serialize as many <map-extent> elements as there are layers in the layers=layer1,layer2,layer3 parameter list value.

This setting should become a format_options parameter as well, with the generated preview HTML client incorporating the setting into the <layer- src="..."> src URL as the format_options:mapmlmultiextent:true|false corresponding to the setting's checked state.