Dynamic WMS styling with GeoServer: SLD and library mode
today I want to delve a bit in the dynamic styling abilities that GeoServer provides.
GeoServer fully supports a client’s ability to specify a custom SLD 1.0 style instead of a built-in named style, this can be done in different ways:
- adding a reference to a internet accessible sld file via the &sld=url parameter
- specifying the full SLD, url-encoded, in the request URL via the
- POST-ing a GetMap XML document, as defined by the SLD 1.0 spec
- POST-ing the usual GET request, where each KVP parameter is sent over as a form parameter (this is a GeoServer extension)
Let’s have a look at case 3) since it’s a bit different than the others. In that case you need to post a XML document just like in WFS/WCS requests, the document looks as follows:
As you can see it’s pretty much the usual GetMap request, but expressed in XML format, with the ability to embed UserStyle objects in it, which make it fully dynamic.
Ways 1, 3 and 4 rely on most of the usal GET parameters, and allow you to specify a custom SLD file, but the way the SLD file it’s interpreted is radically different depending on whater you did specify the layers and styles param in your request, or not.
The simpler behavior is obtained if you don’t specify layers and styles: the NamedLayer objects refer to layers in the server, the NameStyles to styles in the server, and UserStyle allow you to specify your custom style. Each layer is rendered with the style associated to it, and that’s it.
However, if you specify layers in the request, the SLD document is downgraded to a “style library”, this is known as library mode. Here is how this works:
- each layer in the layers parameter is drawn in order
- for each layer, if styles is present the name of the style is picked, otherwise the “default” style is looked for (same happens if you don’t specify the style name for that layer)
- given the layer name and the style name, a layer is searched in the SLD file that has the same name, and the styles inside it are searched for a style with the specified name. If none is found, the server is searched, if the style is not even there, an error is thrown
- given a layer name and the indication to search the default style, a layer is searched in the SLD file that has the same name, and the user styles inside it are searched for one that has the 1 element making it the default style. If none is found the default style defined on the server side is picked instead, ignoring the SLD file contents.
Given the fact that the library mode is certainly more complex, and that you need to line up layer and style names properly, it is of course recommended not to specify the layers parameter and fall back on the simpler mode.
However, the library mode comes in handy if you are making a complex request, with many layers, and you want to provide a custom style for just a few of them: you just need to add the styles for those few in the SLD file, all the others will fall back to use the server side styles instead.