Variable substitution in SLD¶

Variable substitution in SLD is a GeoServer extension (starting in version 2.0.2) that allows passing values from WMS requests into SLD styles. This allows dynamically setting values such as colors, fonts, sizes and filter thresholds.

Variables are specified in WMS GetMap requests by using the env request parameter followed by a list of name:value pairs separated by semicolons:

...&env=name1:value1;name2=value2&...

In an SLD the variable values are accessed using the env function. The function retrieves a substitution variable value specified in the current request:

<ogc:Function name="env">
   <ogc:Literal>size</ogc:Literal>
</ogc:Function>

A default value can be provided. It will be used if the variable was not specified in the request:

<ogc:Function name="env">
   <ogc:Literal>size</ogc:Literal>
   <ogc:Literal>6</ogc:Literal>
</ogc:Function>

The env function can be used in an SLD anywhere an OGC expression is allowed. For example, it can be used in CSSParameter elements, in size and offset elements, and in rule filter expressions. It is also accepted in some places where full expressions are not allowed, such as in the Mark/WellKnownName element.

Predefined Variables¶

GeoServer has predefined variables which provide information about specific properties of the request output. These are useful when SLD parameters need to depend on output dimensions. The predefined variables are:

Name	Type	Description
`wms_bbox`	`ReferencedEnvelope`	the georeferenced extent of the request output
`wms_crs`	`CoordinateReferenceSystem`	the definition of the output coordinate reference system
`wms_srs`	`String`	the code for the output coordinate reference system
`wms_width`	`Integer`	the width (in pixels) of the output image
`wms_height`	`Integer`	the height (in pixels) of the output image
`wms_scale_denominator`	`Integer`	the denominator of the output map scale
`kmlOutputMode`	Either `vector` or empty	this variable gets set to `vector` when the kml generator is writing out vector features as placemarks, as opposed to ground overlays

Example¶

The following SLD symbolizer has been parameterized in three places, with default values provided in each case:

<PointSymbolizer>
  <Graphic>
    <Mark>
      <WellKnownName><ogc:Function name="env">
            <ogc:Literal>name</ogc:Literal>
            <ogc:Literal>square</ogc:Literal>
         </ogc:Function>
      </WellKnownName>
      <Fill>
        <CssParameter name="fill">
          #<ogc:Function name="env">
            <ogc:Literal>color</ogc:Literal>
            <ogc:Literal>FF0000</ogc:Literal>
         </ogc:Function>
        </CssParameter>
      </Fill>
    </Mark>
    <Size>
       <ogc:Function name="env">
          <ogc:Literal>size</ogc:Literal>
          <ogc:Literal>6</ogc:Literal>
       </ogc:Function>
    </Size>
  </Graphic>
</PointSymbolizer>

Download the full SLD style

When no variables are provided in the WMS request, the SLD uses the default values and renders the sample sf:bugsites dataset as shown:

Default rendering

If the request is changed to specify the following variable values:

&env=color:00FF00;name:triangle;size:12

the result is instead:

Rendering with variables supplied