Styles Legends¶

In WMTS and WMS services capabilities documents, styles can be associated with a <LegendURL> element that allows clients to retrieve an image representing the style legend. In the following example we can see the <LegendURL> element for rain style (WMS 1.1.0):

<Style>
  <Name>rain</Name>
  <LegendURL width="128" height="123">
    <Format>image/png</Format>
    <OnlineResource xlink:type="simple" xlink:href="http://localhost:8080/geoserver/ows?service=WMS&request=GetLegendGraphic&format=image/png&width=128&height=123&layer=topp:states&style=rain"/>
  </LegendURL>
</Style>

When using GeoWebCache integration with GeoServer, styles legends are automatically configured for GeoServer layers. Layers configured using a WMS capabilities document will also have their styles legends automatically configured.

When configuring a layer using the REST interface or through geowebcache.xml configuration file the user needs to configure the styles legends, otherwise no <LegendURL> elements will be included in WMS and WMTS services capabilities documents.

Both REST interface and geowebcache.xml configuration file use the same XML structure. A legend configuration is associated with a certain style in the context of a certain layer, follows a configuration example:

<wmsLayer>
   <name>topp:states</name>
   <parameterFilters>
     <stringParameterFilter>
       <key>STYLES</key>
       <defaultValue>population</defaultValue>
       <values>
         <string>population</string>
         <string>polygon</string>
         <string>pophatch</string>
       </values>
     </stringParameterFilter>
   </parameterFilters>
   <wmsUrl>
     <string>http://localhost:8080/geoserver/topp/wms</string>
   </wmsUrl>
   <legends defaultWidth="20" defaultHeight="20" defaultFormat="image/png">
     <legend style="population"/>
     <legend style="pophatch">
       <format>image/jpeg</format>
       <url>http://localhost:8020/geowebcache/wms</url>
     </legend>
     <legend style="polygon">
       <width>50</width>
       <height>100</height>
       <format>image/gif</format>
       <completeUrl>http://localhost/polygon.gif</completeUrl>
       <minScale>5000</minScale>
       <maxScale>10000</maxScale>
     </legend>
   </legends>
 </wmsLayer>

The following properties can be used to configure a legend info:

This properties can be provided in several ways using <legends> and <legend> elements. Default values for properties width, height and format can be configured using respectively attributes defaultWidth, defaultHeight and defaultFormat of <legends> element. The default values can be overridden using elements width, height and format inside <legend> elements.

The style property value needs to be provided using style attribute of <legend> elements. The url property is a little more complex, if nothing is say the WMS layer base URL will be used to build a WMS GetLegendGraphic request. Element <url> can be used to provide another base URL, and this one will be used instead of the layer base URL. Element <completeUrl> can be used to provide an URL that should be used as is to retrieve the legend image.

Properties minScale and maxScale can be provided using the <legend> element, this properties will only be used by WMTS service.

Looking at the example above, the legend configured for population style will produce the following legend URL for WMTS:

<LegendURL width="20" height="20" format="image/png"
  xlink:href="http://localhost:8080/geoserver/topp/wms?service=WMS&amp;request=GetLegendGraphic&amp;format=image/png&amp;width=20&amp;height=20&amp;layer=topp%3Astates&amp;style=population"/>

Note that the layer base URL was used as the base URL for the legend URL. In the example above a different base URL is provided for the legend associated with style pophatch using the <url> element. The produced legend URL will look like this for WMTS:

<LegendURL width="20" height="20" format="image/png"
  xlink:href="http://localhost:8020/geowebcache/wms?service=WMS&amp;request=GetLegendGraphic&amp;format=image/jpeg&amp;width=20&amp;height=20&amp;layer=topp%3Astates&amp;style=pophatch"/>

In some situations it may be useful to provide an already complete URL to the legend image (custom vendors parameters, a static image or different protocol). In the example above the legend URL for style polygon will use an already complete URL and will look like this for WMTS:

<LegendURL width="50" height="100" minScaleDenominator="5000" maxScaleDenominator="10000"
  format="image/gif" xlink:href="http://localhost/polygon.gif"/>

In WMS the legend URL element for polygon style will look like this:

<LegendURL width="50" height="100">
    <Format>image/gif</Format>
    <OnlineResource xlink:type="simple" xlink:href="http://localhost/polygon.gif"/>
</LegendURL>

WMS and WMTS legend URL elements have a different structure and different mandatory elements. In WMTS only properties format and url are mandatory. In WMS properties width, height, format and url are mandatory.