Make "Use Tiles", "Use Features" and "Use Multiple Extents" into GetMap format_options values to text/mapml format, values passed by HTML 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="WMS request URL template"></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 leaf node format_options parameter tokens take precedence over the inner node format_options parameters, and if present, will result in generation of a leaf node document. See discussion of the conceptual tree of MapML related document types available from GeoServer here for a discussion of inner vs leaf node concept.

In brief, mapmlmultiextent (see below), mapmlusefeatures and mapmlusetiles parameterize the first level of MapML document (inner node, 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 should become a LayerGroup (only) setting. Setting it to checked/true should result in the HTML preview serializing a format_options parameter named mapmlmultiextent into the <layer- src="..."> src URL as the format_options=mapmlmultiextent:true corresponding to the setting's checked state (the parameter should be omitted in the unchecked state). The global setting should be removed / moved to LayerGroup editing page publishing tab:

The reason for the above change is that any client will be able to decide if it wants multiple extents to represent a multi-layer request or a layer group, and the GeoServer administrator can decide if they want the multi-extent form of the MapML document to be the default in the preview.

[aaime]

Adding some notes:

• Format options should always be dumped in the same order to avoid creating extra tile caches
• Document the regular expression that would match the format options for mapml usage, e.g. mapmlusetiles=(true|false);mapmlusefeatures=(true|false);...