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:

../../_images/default.png

Default rendering

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

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

the result is instead:

../../_images/triangles.png

Rendering with variables supplied