decoration.rst 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200
  1. .. _wms_decorations:
  2. WMS Decorations
  3. ===============
  4. WMS Decorations provide a framework for visually annotating images from WMS with absolute, rather than spatial,
  5. positioning. Examples of decorations include compasses, legends, and watermarks.
  6. Configuration
  7. -------------
  8. To use decorations in a :ref:`wms_getmap` request, the administrator must first configure a decoration layout. These
  9. layouts are stored in a subdirectory called ``layouts`` in the :ref:`datadir` as XML files, one file per layout.
  10. Each layout file must have the extension ``.xml``. Once a layout ``foo.xml`` is defined, users can request it by
  11. adding ``&format_options=layout:foo`` to the request parameters.
  12. Layout files follow a very simple XML structure; a root node named layout containing any number of decoration elements.
  13. The order of the decoration elements is the order they are drawn so, in case they are overlapping, the first one will appear under the others.
  14. Each decoration element has several attributes:
  15. .. list-table::
  16. :widths: 20 80
  17. :header-rows: 1
  18. * - Attribute
  19. - Meaning
  20. * - ``type``
  21. - the type of decoration to use (see :ref:`wms_decoration_types`)
  22. * - ``affinity``
  23. - the region of the map image to which the decoration is anchored
  24. * - ``offset``
  25. - how far from the anchor point the decoration is drawn
  26. * - ``size``
  27. - the maximum size to render the decoration. Note that some decorations may dynamically resize themselves.
  28. Each decoration element may also contain an arbitrary number of option elements providing a parameter name and value::
  29. <option name="foo" value="bar"/>
  30. Option interpretation depends on the type of decoration in use.
  31. .. _wms_decoration_types:
  32. Decoration Types
  33. ----------------
  34. While GeoServer allows for decorations to be added via extension, there is a core set of decorations included in the
  35. default installation. These decorations include:
  36. The **image** decoration (``type="image"``) overlays a static image file onto the document. If height and width are
  37. specified, the image will be scaled to fit, otherwise the image is displayed at full size.
  38. .. list-table::
  39. :widths: 20 80
  40. :header-rows: 1
  41. * - Option Name
  42. - Meaning
  43. * - ``url``
  44. - provides the URL or file path to the image to draw (relative to the GeoServer data directory)
  45. * - ``opacity``
  46. - a number from 0 to 100 indicating how opaque the image should be.
  47. The **scaleratio** decoration (``type="scaleratio"``) overlays a text description of the map's scale ratio onto the
  48. document.
  49. .. list-table::
  50. :widths: 20 80
  51. :header-rows: 1
  52. * - Option Name
  53. - Meaning
  54. * - ``bgcolor``
  55. - the background color for the text. supports RGB or RGBA colors specified as hex values.
  56. * - ``fgcolor``
  57. - the color for the text and border. follows the color specification from bgcolor.
  58. * - ``format``
  59. - the number format pattern, specified using Java own `DecimalFormat <https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html>`_ syntax
  60. * - ``formatLanguage``
  61. - the language used to drive number formatting (applies only if also ``format`` is used), using a valid Java `Locale <https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html>`_
  62. The **scaleline** decoration (``type="scaleline"``) overlays a graphic showing the scale of the map in world units.
  63. .. list-table::
  64. :widths: 20 80
  65. :header-rows: 1
  66. * - Option Name
  67. - Meaning
  68. * - ``bgcolor``
  69. - the background color, as used in scaleratio
  70. * - ``fgcolor``
  71. - the foreground color, as used in scaleratio
  72. * - ``fontsize``
  73. - the size of the font to use
  74. * - ``transparent``
  75. - if set to true, the background and border won't be painted (false by default)
  76. * - ``measurement-system``
  77. - can be set to "metric" to only show metric units, "imperial" to only show imperial units, or "both" to show both of them (default)
  78. The **legend** decoration (``type="legend"``) overlays a graphic containing legends for the layers in the map.
  79. .. list-table::
  80. :widths: 20 80
  81. :header-rows: 1
  82. * - Option Name
  83. - Meaning
  84. * - ``legend_options``
  85. - the list of legend_options used as in `GetLegendGraphic <./get_legend_graphic/index.html#controlling-legend-appearance-with-legend-options>`_
  86. * - ``opacity``
  87. - the legend opacity with a value between 0 and 1
  88. The **text** decoration (``type="text"``) overlays a parametric, single line text message on top of the map. The
  89. parameter values can be fed via the ``env`` request parameter, just like SLD environment parameters.
  90. .. list-table::
  91. :widths: 20 80
  92. :header-rows: 1
  93. * - Option Name
  94. - Meaning
  95. * - ``message``
  96. - the message to be displayed, as plain text or Freemarker template that can use the ``env`` map contents to expand variables
  97. * - ``font-family``
  98. - the name of the font used to display the message, e.g., ``Arial``, defaults to ``Serif``
  99. * - ``font-size``
  100. - the size of the font to use (can have decimals), defaults to 12
  101. * - ``font-italic``
  102. - it ``true`` the font will be italic, defaults to ``false``
  103. * - ``font-bold``
  104. - if ``true`` the font will be bold, defaults to ``false``
  105. * - ``font-color``
  106. - the color of the message, in ``#RRGGBB`` or ``#RRGGBBAA`` format, defaults to black
  107. * - ``halo-radius``
  108. - the radius of a halo around the message, can have decimals, defaults to 0
  109. * - ``halo-color``
  110. - the halo fill color, in ``#RRGGBB`` or ``#RRGGBBAA`` format, defaults to white
  111. Example
  112. -------
  113. A layout configuration file might look like this:
  114. .. code-block:: xml
  115. <layout>
  116. <decoration type="image" affinity="bottom,right" offset="6,6" size="80,31">
  117. <option name="url" value="pbGS_80x31glow.png"/>
  118. </decoration>
  119. <decoration type="scaleline" affinity="bottom,left" offset="36,6"/>
  120. <decoration type="legend" affinity="top,left" offset="6,6" size="auto"/>
  121. </layout>
  122. Used against the states layer from the default GeoServer data, this layout produces an image like the following.
  123. .. figure:: img/decoration.png
  124. The default states layer, drawn with the decoration layout above.
  125. .. _wms_dynamic_decorations:
  126. Expressions in decoration attributes and options
  127. ------------------------------------------------
  128. Each decoration can have options to control its appearance, as well as attributes controlling
  129. its positioning. Option and attribute values are normally static strings specified in the decoration layout.
  130. However, it's also possible to make them dynamic using (E)CQL expressions,
  131. using the ``${cql expression}`` syntax. The expression can use functions, and in particular it can
  132. access ``env`` variables provided though the request.
  133. For example, this decoration layout:
  134. .. code-block:: xml
  135. <layout>
  136. <decoration type="scaleline" affinity="${env('sla', 'bottom,left')}">
  137. <option name="bgcolor" value="${env('bg', '#AAAAAA')}"/>
  138. </decoration>
  139. </layout>
  140. Would generate a scale line with:
  141. * A light gray background, with a GetMap request that does not contain the ``bg`` env variable.
  142. * A red background, if the request includes a env section like ``&env=bg:FF0000``.
  143. * A scaleline positioned on the top right, if the request includes a env section like ``&env=sla:top,right``.
  144. All options allow usage of expressions, with **one notable exception**: the ``message`` option in
  145. the ``text`` decoration. This one option cannot use expressions, as it would allow expansion, and
  146. evaluation, of user provided FreeMarker templates. The template can contain control structures,
  147. loops and other active elements, as such, allowing its value to be provided via WMS requests
  148. is deemed too risky.