From 7f5007e21b9aa301e362820f76ac156aa3abfc37 Mon Sep 17 00:00:00 2001 From: Joseph Miller Date: Thu, 30 May 2024 11:21:46 -0400 Subject: [PATCH] [GEOS-11368] Allow Freemarker templates to update MapML responses started on template page ftl file names correction --- doc/en/user/source/extensions/mapml/index.rst | 321 +----------------- .../source/extensions/mapml/installation.rst | 319 +++++++++++++++++ .../user/source/extensions/mapml/template.rst | 178 ++++++++++ 3 files changed, 501 insertions(+), 317 deletions(-) create mode 100644 doc/en/user/source/extensions/mapml/installation.rst create mode 100644 doc/en/user/source/extensions/mapml/template.rst diff --git a/doc/en/user/source/extensions/mapml/index.rst b/doc/en/user/source/extensions/mapml/index.rst index adda4c9c962..f110f4137d7 100644 --- a/doc/en/user/source/extensions/mapml/index.rst +++ b/doc/en/user/source/extensions/mapml/index.rst @@ -12,322 +12,9 @@ The MapML module for GeoServer adds new MapML resources to access WMS, WMTS and .. warning:: MapML is an experimental proposed extension of HTML for the Web. The objective of the project is to standardize map, layer and feature semantics in HTML. As the format progresses towards a Web standard, it may change slightly. Always use the latest version of this extension, and follow or join in the project's progress at https://maps4html.org. -Installation --------------------- - -#. Visit the :website:`website download ` page, locate your release, and download: :download_extension:`mapml` +.. toctree:: + :maxdepth: 2 - .. warning:: Make sure to match the version of the extension (for example |release| above) to the version of the GeoServer instance! - -#. Extract the contents of the archive into the :file:`WEB-INF/lib` directory of the GeoServer installation. - -#. Restart GeoServer. - -Configuration -------------- - -Configuration can be done using the Geoserver administrator GUI. The MapML configuration is accessible in the *MapML Settings* section under the *Publishing* tab of the Layer or Layer Group Configuration page for the layer or layer group being configured. Here is the MapML Settings section, with some example values filled in: - -.. figure:: images/mapml_config_ui.png - -There is also a MapML-specific global WMS setting in the *MapML Extension* section of the ``WMS`` Services Settings Page. This setting is used to control the handling of multi-layer requests. - -.. figure:: images/mapml_config_wms.png - -If the ``Represent multi-layer requests as multiple elements`` is checked (and the configuration is saved), an individually accessible element will be generated for each requested layer. The default is to represent the layers as a single (hidden) . - -.. figure:: images/mapml_wms_multi_extent.png - -Styles ------- - -Like any WMS layer or layer group available from GeoServer, a comma-separated list of styles may be supplied in the WMS GetMap `styles` parameter. If no style name is requested, the default style will be used for that layer. For single-layer or single-layer group requests, the set of alternate styles is presented as an option list in the layer preview map's layer control, with the currently requested style indicated. - -.. figure:: images/mapml_preview_multiple_styles_menu.png - -Note that in order to ensure that the default layer style is properly available to the preview map's option list, make sure that the style is moved to the ``Available Styles`` list in the ``Publishing`` tab of the Layer Configuration page. If the style is set to ``Default`` but not explicitly made ``Available``, the style will not be available to MapML. Similarly but a with a slight variation in requirement, for Layer Groups, the 'default' layer group style must be copied and given a name matching `default-style-` plus the layer group name. - -License Info -^^^^^^^^^^^^ - -Together these two attributes allow the administrator to define the contents of the ```` element in the MapML header. Here is an example of the resulting XML: - - - -**License Title** - The License Title will be included as the value of ``title`` attribute of the ```` element in the MapML header. - -**License Link** - The License Link will be included as the value of ``href`` attribute of the ```` element in the MapML header, and should be a valid URL referencing the license document. - - -Tile Settings -^^^^^^^^^^^^^ - -Using tiles to access the layer can increase the performance of your web map. This is especially true if there is a tile cache mechanism in use between GeoServer and the browser client. - -**Use Tiles** - If the "Use Tiles" checkbox is checked, by default the output MapML will define a tile-based reference to the WMS server. Otherwise, an image-based reference will be used. If one or more of the MapML-defined GridSets is referenced by the layer or layer group in its "Tile Caching" profile, GeoServer will generate tile references instead of generating WMS GetMap URLs in the MapML document body. - -Vector Settings -^^^^^^^^^^^^^^^ - -MapML supports the serving of vector feature representations of the data. This results in a smoother user navigation experience, smaller bandwidth requirements, and more options for dynamic styling on the client-side. - -**Use Features** - If the "Use Features" checkbox is checked, by default the output MapML will define a feature-based reference to the WMS server. Otherwise, an image-based reference will be used. Note that this option is only available for vector source data. MapML element with a feature link: - -.. code-block:: html - - - - - - - - - - - - -When both "Use Tiles" and "Use Features" are checked, the MapML extension will request tiled maps in ``text/mapml`` format. -The contents of the tiles will be clipped to the requested area, and feature attributes will be skiipped, as the MapML client cannot leverage them for the moment. - - -**Feature Styling** - Basic styling of vector features is supported by the MapML extension. The style is defined in the WMS GetMap request, and the MapML extension will convert the rules and style attributes defined in the SLD into CSS classes and apply those classes to the appropriate features. Note that this conversion is currently limited to basic styling and does not include transformation functions, external graphics, or styling dependent on individual feature attributes (non-static style values). See below for a more detailed compatibility table: - -+------------------+-------------------+-----------+ -| Symbolizer | Style Attribute | Supported | -+==================+===================+===========+ -| PointSymbolizer | Opacity | yes | -| +-------------------+-----------+ -| | Default Radius | yes | -| +-------------------+-----------+ -| | Radius | yes | -| +-------------------+-----------+ -| | Rotation | no | -| +-------------------+-----------+ -| | Displacement | no | -| +-------------------+-----------+ -| | Anchor Point | no | -| +-------------------+-----------+ -| | Gap | no | -| +-------------------+-----------+ -| | Initial Gap | no | -| +-------------------+-----------+ -| | Well Known Name | yes | -| +-------------------+-----------+ -| | External Mark | no | -| +-------------------+-----------+ -| | Graphic Fill | no | -| +-------------------+-----------+ -| | Fill Color | yes | -| +-------------------+-----------+ -| | Fill Opacity | yes | -| +-------------------+-----------+ -| | Stroke Color | yes | -| +-------------------+-----------+ -| | Stroke Opacity | yes | -| +-------------------+-----------+ -| | Stroke Width | yes | -| +-------------------+-----------+ -| | Stroke Linecap | yes | -| +-------------------+-----------+ -| | Stroke Dash Array | yes | -| +-------------------+-----------+ -| | Stroke Dash Offset| yes | -| +-------------------+-----------+ -| | Stroke Line Join | no | -+------------------+-------------------+-----------+ -| LineSymbolizer | Stroke Linecap | yes | -| +-------------------+-----------+ -| | Stroke Dash Array | yes | -| +-------------------+-----------+ -| | Stroke Dash Offset| yes | -| +-------------------+-----------+ -| | Stroke Line Join | no | -+------------------+-------------------+-----------+ -| PolygonSymbolizer| Displacement | no | -| +-------------------+-----------+ -| | Perpendicular Offs| no | -| +-------------------+-----------+ -| | Graphic Fill | no | -| +-------------------+-----------+ -| | Fill Color | yes | -| +-------------------+-----------+ -| | Fill Opacity | yes | -| +-------------------+-----------+ -| | Stroke Color | yes | -| +-------------------+-----------+ -| | Stroke Opacity | yes | -| +-------------------+-----------+ -| | Stroke Width | yes | -| +-------------------+-----------+ -| | Stroke Linecap | yes | -| +-------------------+-----------+ -| | Stroke Dash Array | yes | -| +-------------------+-----------+ -| | Stroke Dash Offset| yes | -| +-------------------+-----------+ -| | Stroke Line Join | no | -+------------------+-------------------+-----------+ -| TextSymbolizer | ALL | no | -+------------------+-------------------+-----------+ -| RasterSymbolizer | ALL | no | -+------------------+-------------------+-----------+ -| Transformation | ALL | no | -| Functions | | | -+------------------+-------------------+-----------+ -| Zoom | ALL | yes | -| Denominators | | | -+------------------+-------------------+-----------+ - - -WMS GetMap considerations -^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, each layer/style pair that is requested via the GetMap parameters is composed into a single ...... structure as exemplified above. - -If the 'Represent multi-layer requests as multiple elements' checkbox from the global WMS Settings page is checked as described above, a request for multiple layers or layer groups in MapML format will result in the serialization of a MapML document containing multiple elements. Each layer/style pair is represented by a element in the response. The elements are represented in the client viewer layer control settings as sub-layers, which turn on and off independently of each other, but which are controlled by the parent element's state (checked / unchecked, opacity etc) (right-click or Shift+F10 to obtain context menus): - -.. figure:: images/mapml_wms_multi_extent.png - -With 'Represent multi-layer requests as multiple elements' checked, if two or more layers are requested in MapML format via the GetMap 'layers' parameter, the MapML extension serialize each layer's according to its "Use Features" and "Use Tiles" settings. Note that there is currently no "Use Features" setting available for layer groups. - -Tile Caching -^^^^^^^^^^^^ - -In the Tile Caching tab panel of the Edit Layer or Edit Layer Group page, at the bottom of the page you will see the table of GridSets that are assigned to the layer or layer group. - -The values ``WGS84`` and ``OSMTILE`` are equivalent to the EPSG:4326 and EPSG:900913 built in GeoWebCache GridSets. -However, for the MapML module to recognize these GridSets, you must select and use the MapML names. For new layers or layer groups, or newly created grid subsets for a layer or layer group, the MapML values are selected by default. For existing layers that you wish to enable the use of cached tile references by the MapML service, you will have to select and add those values you wish to support from the dropdown of available GridSets. The set of recognized values for MapML is ``WGS84`` (equivalent to EPSG:4326), ``OSMTILE`` (equivalent to EPSG:900913), ``CBMTILE`` (Canada Base Map) and ``APSTILE`` (Alaska Polar Stereographic). - -The MapML client will normally request image tiles against WMTS, but if configured to use feature output, -it will try to use tiles in ``text/mapml`` format, which should be configured as a cacheable format -in order to enable WMTS requests. - -.. figure:: images/mapml_tile_caching_panel_ui.png - -Sharding Config -^^^^^^^^^^^^^^^^ - -The Sharding Config options are intended to allow for parallel access to tiles via different server names. The actual server names must be configured in the DNS to refer to either the same server or different servers with the same GeSserver layer configuration. In the example above, the mapML client would alternate between the servers a.geoserver.org, b.geoserver.org, and c.geoserver.org to access the map images. The values in the example above would result in the following MapML: - -.. code-block:: html - - - - - - - -**Enable Sharding** - If Enable Sharding is checked, and values are provided for the Shard List and Shard Server Pattern fields, then a hidden shard list input will be included in the MapML. - -**Shard List** - If Enable Sharding is checked, the Shard List should be populated with a comma-separated list of shard names which will be used to populate the shard data list element. - -**Shard Server Pattern** - The Shard Server Pattern should be a valid DNS name including the special placeholder string {s} which will be replace with the Shard Names from the Shard List in requests to the server. This pattern should not include any slashes, the protocol string (http://) or the port number (:80), as these are all determined automatically from the URL used to access the MapML resource. - - -Dimension Config -^^^^^^^^^^^^^^^^ - -**Dimension** - The selected dimension (if any) is advertised in the mapml as an input with the appropriate value options or ranges, as configured in the *Dimension* tab of the Layer Configuration page. Only dimensions enabled in the *Dimension* tab are available as options. - -Attribute to mapping -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**List of attributes** -The list allows you to read the names of the layer attributes, it doesn't really do more than that. - -**Feature Caption Template String** - -To cause an attribute to be serialized in MapML vector content as the element value, -you must enter its name as a ${placeholder} in the text box immediately below the attributes list. You can also add (a small amount of) plain text that will be -copied verbatim into the content. is used as the accessible name of features by screen reader software, which will often -read out this value without the user having to expand a popup; in other words, it will be used as a visual and audible tooltip when the -feature is focused. - - -MapML Resources ---------------- - -MapML resources will be available for any published WMS layers by making a GetMap request with the WMS output format to ``format=text/mapml``. See :ref:`WMS` for further WMS details, :ref:`wms_getmap` for GetMap details, and :ref:`wms_output_formats` for output format reference information. - -**SRS/CRS** - -Note that the WMS SRS or CRS must be one of the projections supported by MapML: - -- MapML:WGS84 (or EPSG:4326) -- MapML:OSMTILE (or EPSG:3857) -- MapML:CBMTILE (or EPSG:3978) -- MapML:APSTILE (or EPSG:5936) - -The equivalent EPSG codes are provided for reference, but the MapML names are recommended, as they -imply not only a coordinate refefence system, but also a tile grid and a set of zoom levels (Tiled CRS), -that the MapML client will use when operating in tiled mode. When using tiles, it's also recommended -to set up tile caching for the same-named gridsets. - -If the native SRS of a layer is not a match for the MapML ones, remember to configure the projection -policy to "reproject native to declare". You might have to save and reload the layer configuration -in order to re-compute the native bounds correctly. - -If the SRS or CRS is not one of the above, the GetMap request will fail with an ``InvalidParameterValue`` exception. -The main "MapML" link in the preview page generates a HTML client able to consume MapML resources. -The link is generated so that it always work, if the CRS configured for the layer is not supported, it will automatically fall back on MapML:WGS84. - - -**MapML Output Format** - -The output image format for the MapML resource should be specified using the format_options parameter with a key called ``mapml-wms-format``. If provided, the provided mime type must be a valid WMS format specifier. If not provided, it defaults to to the format set with the Default Mime Type dropdown under MapML Settings in the Publishing tab of the Edit Layer settings page. - -Example:: - - http://localhost:8080/geoserver/tiger/wms?service=WMS&version=1.1.0&request=GetMap&layers=tiger:giant_polygon&bbox=-180.0,-90.0,180.0,90.0&width=768&height=384&srs=EPSG:4326&styles=&format=text/mapml&format_options=mapml-wms-format:image/jpeg - -MapML Visualization -------------------- - -With the MapML Extension module installed, the GeoServer Layer Preview page is modified to add a WMS GetMap link to the MapML resources for each layer or layer group. The MapML link in the Layer Preview table is generated by the MapML extension to an HTML Web map page that is created on the fly which refers to the GeoServer resource: - -.. figure:: images/mapml_preview_ui.png - -You can add layers to the map as you like, by dragging the URL bar value generated by the the Layer Preview WMS formats dropdown menu selection of "MapML" as shown below, and dropping it onto another layer's MapML preview: - -.. figure:: images/mapml_wms_format_dropdown.png - -If all goes well, you should see the layers stacked on the map and in the layer control. - -MapML visualization is supported by the Web-Map-Custom-Element project. The MapML viewer is built into the GeoServer layer and layer group preview facility. You can find out more about the Web-Map-Custom-Element at the project `website `. Here is a simple, self-contained example of an HTML page that uses the and elements: - -.. code-block:: html + installation + template - - - - - MapML Test Map - - - - - - - - - - - -In the above example, the place-holders ``topp:states``, ``localhost:8080``, ``osmtile``, and ``population`` would need to be replaced with the appropriate values, and/or the ``style`` parameter could be removed entirely from the URL if not needed. You may also like to "View Source" on the preview page to see what the markup looks like for any layer. This code can be copied and pasted without harm, and you should try it and see what works and what the limitations are. For further information about MapML, and the Maps for HTML Community Group, please visit http://maps4html.org. diff --git a/doc/en/user/source/extensions/mapml/installation.rst b/doc/en/user/source/extensions/mapml/installation.rst new file mode 100644 index 00000000000..c01992e4e16 --- /dev/null +++ b/doc/en/user/source/extensions/mapml/installation.rst @@ -0,0 +1,319 @@ +Installation +-------------------- + +#. Visit the :website:`website download ` page, locate your release, and download: :download_extension:`mapml` + + .. warning:: Make sure to match the version of the extension (for example |release| above) to the version of the GeoServer instance! + +#. Extract the contents of the archive into the :file:`WEB-INF/lib` directory of the GeoServer installation. + +#. Restart GeoServer. + +Configuration +------------- + +Configuration can be done using the Geoserver administrator GUI. The MapML configuration is accessible in the *MapML Settings* section under the *Publishing* tab of the Layer or Layer Group Configuration page for the layer or layer group being configured. Here is the MapML Settings section, with some example values filled in: + +.. figure:: images/mapml_config_ui.png + +There is also a MapML-specific global WMS setting in the *MapML Extension* section of the ``WMS`` Services Settings Page. This setting is used to control the handling of multi-layer requests. + +.. figure:: images/mapml_config_wms.png + +If the ``Represent multi-layer requests as multiple elements`` is checked (and the configuration is saved), an individually accessible element will be generated for each requested layer. The default is to represent the layers as a single (hidden) . + +.. figure:: images/mapml_wms_multi_extent.png + +Styles +------ + +Like any WMS layer or layer group available from GeoServer, a comma-separated list of styles may be supplied in the WMS GetMap `styles` parameter. If no style name is requested, the default style will be used for that layer. For single-layer or single-layer group requests, the set of alternate styles is presented as an option list in the layer preview map's layer control, with the currently requested style indicated. + +.. figure:: images/mapml_preview_multiple_styles_menu.png + +Note that in order to ensure that the default layer style is properly available to the preview map's option list, make sure that the style is moved to the ``Available Styles`` list in the ``Publishing`` tab of the Layer Configuration page. If the style is set to ``Default`` but not explicitly made ``Available``, the style will not be available to MapML. Similarly but a with a slight variation in requirement, for Layer Groups, the 'default' layer group style must be copied and given a name matching `default-style-` plus the layer group name. + +License Info +^^^^^^^^^^^^ + +Together these two attributes allow the administrator to define the contents of the ```` element in the MapML header. Here is an example of the resulting XML: + + + +**License Title** + The License Title will be included as the value of ``title`` attribute of the ```` element in the MapML header. + +**License Link** + The License Link will be included as the value of ``href`` attribute of the ```` element in the MapML header, and should be a valid URL referencing the license document. + + +Tile Settings +^^^^^^^^^^^^^ + +Using tiles to access the layer can increase the performance of your web map. This is especially true if there is a tile cache mechanism in use between GeoServer and the browser client. + +**Use Tiles** + If the "Use Tiles" checkbox is checked, by default the output MapML will define a tile-based reference to the WMS server. Otherwise, an image-based reference will be used. If one or more of the MapML-defined GridSets is referenced by the layer or layer group in its "Tile Caching" profile, GeoServer will generate tile references instead of generating WMS GetMap URLs in the MapML document body. + +Vector Settings +^^^^^^^^^^^^^^^ + +MapML supports the serving of vector feature representations of the data. This results in a smoother user navigation experience, smaller bandwidth requirements, and more options for dynamic styling on the client-side. + +**Use Features** + If the "Use Features" checkbox is checked, by default the output MapML will define a feature-based reference to the WMS server. Otherwise, an image-based reference will be used. Note that this option is only available for vector source data. MapML element with a feature link: + +.. code-block:: html + + + + + + + + + + + + +When both "Use Tiles" and "Use Features" are checked, the MapML extension will request tiled maps in ``text/mapml`` format. +The contents of the tiles will be clipped to the requested area, and feature attributes will be skiipped, as the MapML client cannot leverage them for the moment. + + +**Feature Styling** + Basic styling of vector features is supported by the MapML extension. The style is defined in the WMS GetMap request, and the MapML extension will convert the rules and style attributes defined in the SLD into CSS classes and apply those classes to the appropriate features. Note that this conversion is currently limited to basic styling and does not include transformation functions, external graphics, or styling dependent on individual feature attributes (non-static style values). See below for a more detailed compatibility table: + ++------------------+-------------------+-----------+ +| Symbolizer | Style Attribute | Supported | ++==================+===================+===========+ +| PointSymbolizer | Opacity | yes | +| +-------------------+-----------+ +| | Default Radius | yes | +| +-------------------+-----------+ +| | Radius | yes | +| +-------------------+-----------+ +| | Rotation | no | +| +-------------------+-----------+ +| | Displacement | no | +| +-------------------+-----------+ +| | Anchor Point | no | +| +-------------------+-----------+ +| | Gap | no | +| +-------------------+-----------+ +| | Initial Gap | no | +| +-------------------+-----------+ +| | Well Known Name | yes | +| +-------------------+-----------+ +| | External Mark | no | +| +-------------------+-----------+ +| | Graphic Fill | no | +| +-------------------+-----------+ +| | Fill Color | yes | +| +-------------------+-----------+ +| | Fill Opacity | yes | +| +-------------------+-----------+ +| | Stroke Color | yes | +| +-------------------+-----------+ +| | Stroke Opacity | yes | +| +-------------------+-----------+ +| | Stroke Width | yes | +| +-------------------+-----------+ +| | Stroke Linecap | yes | +| +-------------------+-----------+ +| | Stroke Dash Array | yes | +| +-------------------+-----------+ +| | Stroke Dash Offset| yes | +| +-------------------+-----------+ +| | Stroke Line Join | no | ++------------------+-------------------+-----------+ +| LineSymbolizer | Stroke Linecap | yes | +| +-------------------+-----------+ +| | Stroke Dash Array | yes | +| +-------------------+-----------+ +| | Stroke Dash Offset| yes | +| +-------------------+-----------+ +| | Stroke Line Join | no | ++------------------+-------------------+-----------+ +| PolygonSymbolizer| Displacement | no | +| +-------------------+-----------+ +| | Perpendicular Offs| no | +| +-------------------+-----------+ +| | Graphic Fill | no | +| +-------------------+-----------+ +| | Fill Color | yes | +| +-------------------+-----------+ +| | Fill Opacity | yes | +| +-------------------+-----------+ +| | Stroke Color | yes | +| +-------------------+-----------+ +| | Stroke Opacity | yes | +| +-------------------+-----------+ +| | Stroke Width | yes | +| +-------------------+-----------+ +| | Stroke Linecap | yes | +| +-------------------+-----------+ +| | Stroke Dash Array | yes | +| +-------------------+-----------+ +| | Stroke Dash Offset| yes | +| +-------------------+-----------+ +| | Stroke Line Join | no | ++------------------+-------------------+-----------+ +| TextSymbolizer | ALL | no | ++------------------+-------------------+-----------+ +| RasterSymbolizer | ALL | no | ++------------------+-------------------+-----------+ +| Transformation | ALL | no | +| Functions | | | ++------------------+-------------------+-----------+ +| Zoom | ALL | yes | +| Denominators | | | ++------------------+-------------------+-----------+ + + +WMS GetMap considerations +^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, each layer/style pair that is requested via the GetMap parameters is composed into a single ...... structure as exemplified above. + +If the 'Represent multi-layer requests as multiple elements' checkbox from the global WMS Settings page is checked as described above, a request for multiple layers or layer groups in MapML format will result in the serialization of a MapML document containing multiple elements. Each layer/style pair is represented by a element in the response. The elements are represented in the client viewer layer control settings as sub-layers, which turn on and off independently of each other, but which are controlled by the parent element's state (checked / unchecked, opacity etc) (right-click or Shift+F10 to obtain context menus): + +.. figure:: images/mapml_wms_multi_extent.png + +With 'Represent multi-layer requests as multiple elements' checked, if two or more layers are requested in MapML format via the GetMap 'layers' parameter, the MapML extension serialize each layer's according to its "Use Features" and "Use Tiles" settings. Note that there is currently no "Use Features" setting available for layer groups. + +Tile Caching +^^^^^^^^^^^^ + +In the Tile Caching tab panel of the Edit Layer or Edit Layer Group page, at the bottom of the page you will see the table of GridSets that are assigned to the layer or layer group. + +The values ``WGS84`` and ``OSMTILE`` are equivalent to the EPSG:4326 and EPSG:900913 built in GeoWebCache GridSets. +However, for the MapML module to recognize these GridSets, you must select and use the MapML names. For new layers or layer groups, or newly created grid subsets for a layer or layer group, the MapML values are selected by default. For existing layers that you wish to enable the use of cached tile references by the MapML service, you will have to select and add those values you wish to support from the dropdown of available GridSets. The set of recognized values for MapML is ``WGS84`` (equivalent to EPSG:4326), ``OSMTILE`` (equivalent to EPSG:900913), ``CBMTILE`` (Canada Base Map) and ``APSTILE`` (Alaska Polar Stereographic). + +The MapML client will normally request image tiles against WMTS, but if configured to use feature output, +it will try to use tiles in ``text/mapml`` format, which should be configured as a cacheable format +in order to enable WMTS requests. + +.. figure:: images/mapml_tile_caching_panel_ui.png + +Sharding Config +^^^^^^^^^^^^^^^^ + +The Sharding Config options are intended to allow for parallel access to tiles via different server names. The actual server names must be configured in the DNS to refer to either the same server or different servers with the same GeSserver layer configuration. In the example above, the mapML client would alternate between the servers a.geoserver.org, b.geoserver.org, and c.geoserver.org to access the map images. The values in the example above would result in the following MapML: + +.. code-block:: html + + + + + + + +**Enable Sharding** + If Enable Sharding is checked, and values are provided for the Shard List and Shard Server Pattern fields, then a hidden shard list input will be included in the MapML. + +**Shard List** + If Enable Sharding is checked, the Shard List should be populated with a comma-separated list of shard names which will be used to populate the shard data list element. + +**Shard Server Pattern** + The Shard Server Pattern should be a valid DNS name including the special placeholder string {s} which will be replace with the Shard Names from the Shard List in requests to the server. This pattern should not include any slashes, the protocol string (http://) or the port number (:80), as these are all determined automatically from the URL used to access the MapML resource. + + +Dimension Config +^^^^^^^^^^^^^^^^ + +**Dimension** + The selected dimension (if any) is advertised in the mapml as an input with the appropriate value options or ranges, as configured in the *Dimension* tab of the Layer Configuration page. Only dimensions enabled in the *Dimension* tab are available as options. + +Attribute to mapping +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**List of attributes** +The list allows you to read the names of the layer attributes, it doesn't really do more than that. + +**Feature Caption Template String** + +To cause an attribute to be serialized in MapML vector content as the element value, +you must enter its name as a ${placeholder} in the text box immediately below the attributes list. You can also add (a small amount of) plain text that will be +copied verbatim into the content. is used as the accessible name of features by screen reader software, which will often +read out this value without the user having to expand a popup; in other words, it will be used as a visual and audible tooltip when the +feature is focused. + + +MapML Resources +--------------- + +MapML resources will be available for any published WMS layers by making a GetMap request with the WMS output format to ``format=text/mapml``. See :ref:`WMS` for further WMS details, :ref:`wms_getmap` for GetMap details, and :ref:`wms_output_formats` for output format reference information. + +**SRS/CRS** + +Note that the WMS SRS or CRS must be one of the projections supported by MapML: + +- MapML:WGS84 (or EPSG:4326) +- MapML:OSMTILE (or EPSG:3857) +- MapML:CBMTILE (or EPSG:3978) +- MapML:APSTILE (or EPSG:5936) + +The equivalent EPSG codes are provided for reference, but the MapML names are recommended, as they +imply not only a coordinate refefence system, but also a tile grid and a set of zoom levels (Tiled CRS), +that the MapML client will use when operating in tiled mode. When using tiles, it's also recommended +to set up tile caching for the same-named gridsets. + +If the native SRS of a layer is not a match for the MapML ones, remember to configure the projection +policy to "reproject native to declare". You might have to save and reload the layer configuration +in order to re-compute the native bounds correctly. + +If the SRS or CRS is not one of the above, the GetMap request will fail with an ``InvalidParameterValue`` exception. +The main "MapML" link in the preview page generates a HTML client able to consume MapML resources. +The link is generated so that it always work, if the CRS configured for the layer is not supported, it will automatically fall back on MapML:WGS84. + + +**MapML Output Format** + +The output image format for the MapML resource should be specified using the format_options parameter with a key called ``mapml-wms-format``. If provided, the provided mime type must be a valid WMS format specifier. If not provided, it defaults to ``image/png``. + +Example:: + + http://localhost:8080/geoserver/tiger/wms?service=WMS&version=1.1.0&request=GetMap&layers=tiger:giant_polygon&bbox=-180.0,-90.0,180.0,90.0&width=768&height=384&srs=EPSG:4326&styles=&format=text/mapml&format_options=mapml-wms-format:image/jpeg + +MapML Visualization +------------------- + +With the MapML Extension module installed, the GeoServer Layer Preview page is modified to add a WMS GetMap link to the MapML resources for each layer or layer group. The MapML link in the Layer Preview table is generated by the MapML extension to an HTML Web map page that is created on the fly which refers to the GeoServer resource: + +.. figure:: images/mapml_preview_ui.png + +You can add layers to the map as you like, by dragging the URL bar value generated by the the Layer Preview WMS formats dropdown menu selection of "MapML" as shown below, and dropping it onto another layer's MapML preview: + +.. figure:: images/mapml_wms_format_dropdown.png + +If all goes well, you should see the layers stacked on the map and in the layer control. + +MapML visualization is supported by the Web-Map-Custom-Element project. The MapML viewer is built into the GeoServer layer and layer group preview facility. You can find out more about the Web-Map-Custom-Element at the project `website `. Here is a simple, self-contained example of an HTML page that uses the and elements: + +.. code-block:: html + + + + + + MapML Test Map + + + + + + + + + + + +In the above example, the place-holders ``topp:states``, ``localhost:8080``, ``osmtile``, and ``population`` would need to be replaced with the appropriate values, and/or the ``style`` parameter could be removed entirely from the URL if not needed. You may also like to "View Source" on the preview page to see what the markup looks like for any layer. This code can be copied and pasted without harm, and you should try it and see what works and what the limitations are. For further information about MapML, and the Maps for HTML Community Group, please visit http://maps4html.org. diff --git a/doc/en/user/source/extensions/mapml/template.rst b/doc/en/user/source/extensions/mapml/template.rst new file mode 100644 index 00000000000..3d358dd2c06 --- /dev/null +++ b/doc/en/user/source/extensions/mapml/template.rst @@ -0,0 +1,178 @@ +Templates With FreeMarker +------------------------- + +MapML templates are written in `Freemarker `_ , a Java-based template engine. The templates below are feature type specific and will not be applied in multi-layer WMS requests. See :ref:`tutorial_freemarkertemplate` for general information about FreeMarker implementation in GeoServer. + +GetMap MapML Viewer Head Stylesheet Templating +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The viewer is returned when the format includes subtype=mapml. The viewer is an HTML document that includes a head section with a link to the stylesheet. The default viewer is a simple viewer that includes a link to the default stylesheet. +A template can be created to insert links to whole stylesheet or actual stylesheet elements. +We can do this by creating a file called ``mapml-head-viewer.ftl`` in the GeoServer data directory in the directory for the layer that we wish to append links to. For example we could create this file under ``workspaces/topp/states_shapefile/states``. To add stylesheet links and stylesheet elements, we enter the following text inside this new file: + +.. code-block:: html + + + + + + +This would result in a head section that would resemble: + +.. code-block:: html + + + World Map + + + + + + + + + + +GetMap XML Head Stylesheet Templating +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +MapML in XML format includes a map-head element that includes map-link elements to link to other resources, including map style variants. Additional map-link elements can be added to the map-head element by creating a mapml-head.ftl template in the GeoServer data directory in the directory for the layer we wish to append map-links to. For example we could create the head.ftl file under ``workspaces/tiger/poly_landmarks_shapefile/poly_landmarks``: + +.. code-block:: html + + + .polygon-r1-s1{stroke-opacity:3.0; stroke-dashoffset:4; stroke-width:2.0; fill:#AAAAAA; fill-opacity:3.0; stroke:#DD0000; stroke-linecap:butt} + + + +This would result in a map-head section that would resemble: + +.. code-block:: html + + + Manhattan (NY) landmarks + + + + + + + + + + .bbox {display:none} .polygon-r1-s1{stroke-opacity:1.0; stroke-dashoffset:0; stroke-width:1.0; fill:#AAAAAA; fill-opacity:1.0; stroke:#000000; stroke-linecap:butt} + + .polygon-r2-s2{stroke-opacity:3.0; stroke-dashoffset:4; stroke-width:2.0; fill:#AAAAAA; fill-opacity:3.0; stroke:#DD0000; stroke-linecap:butt} + + + + +GetMap Features Inline Style Class Templating +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +MapML in XML feature format (when the parameter format_options=mapmlfeatures:true is set) has a map-head element that includes map-style elements where the style classes are defined. +Within the map-body, map-feature elements include map-geometry with map-coordinates. +In addition, coordinates can be wrapped with span tags that define the style class. +The mapml-feature.ftl is a file can be used to insert map-style elements with the style class definitions into the map-head. Note that this section of the template adds the styles listed but does not remove any existing styles. +It also can be used to add style class identifiers to map-feature elements based on the feature identifier or to wrap groupings of map-coordinates with spans that specify the style class based on an index of coordinate order (zero based index that starts at the first coordinate pair of each feature). +This file is placed in the GeoServer data directory in the directory for the layer we wish to append style classes to. For example we could create the file under ``workspaces/tiger/poly_landmarks_shapefile/poly_landmarks``. The mapml-feature.ftl file would look like: + +.. code-block:: xml + + + .desired {stroke-dashoffset:3} + + + + <#if feature.featureId == "xyz"> + <#assign partIndex = 0> + <#list feature.geometry.parts as part> + + <#assign coordIndex = 0> + <#list part.coordinates as coordinate> + <#if partIndex == desiredPartIndex> + <#if coordIndex == 3> + + + ${coordinate} + <#if coordIndex == (part.coordinates?size - 1)> + + + <#else> + ${coordinate} + + <#assign coordIndex = coordIndex + 1> + + + <#assign partIndex = partIndex + 1> + + + + + + +This would result in a MapML feature output that would resemble: + +.. code-block:: xml + + + + poi + + + + + + .bbox {display:none} .polygon-r1-s1{stroke-opacity:1.0; stroke-dashoffset:0; stroke-width:1.0; fill:#AAAAAA; fill-opacity:1.0; stroke:#000000; stroke-linecap:butt} + .desired {stroke-dashoffset:3} + + + + + + -74.01043024 40.70938712 -74.01043216 40.70936761 -74.01043785 40.70934885 -74.01044709 40.70933156 -74.01045953 40.70931641 -74.01047468 40.70930397 -74.01049197 40.70929473 -74.01051073 40.70928904 -74.01053024 40.70928712 -74.01054975 40.70928904 -74.01056851 40.70929473 -74.0105858 40.70930397 -74.01060095 40.70931641 -74.01061339 40.70933156 -74.01062263 40.70934885 -74.01062832 40.70936761 -74.01063024 40.70938712 -74.01062832 40.70940663 -74.01062263 40.70942539 -74.01061339 40.70944267 -74.01060095 40.70945783 -74.0105858 40.70947026 -74.01056851 40.7094795 -74.01054975 40.7094852 -74.01053024 40.70948712 -74.01051073 40.7094852 -74.01049197 40.7094795 -74.01047468 40.70947026 -74.01045953 40.70945783 -74.01044709 40.70944267 -74.01043785 40.70942539 -74.01043216 40.70940663 -74.01043024 40.70938712 + + + + + + + + + + + + + + + + + + + + + + + + +
Property nameProperty value
NAMEart
THUMBNAILpics/22037856-Ti.jpg
MAINPAGEpics/22037856-L.jpg
+ + + + + +