.. _xslt: XSLT WFS output format module ============================= The ``xslt`` module for GeoServer is a WFS output format generator which brings togheter a base output, such as GML, and a XSLT 1.0 style sheet to generate a new textual output format of user choosing. The configuration for this output format can be either performed directly on disk, or via a REST API. Manual configuration -------------------- All the configuration for the output resides in the ``$GEOSERVER_DATA_DIR/wfs/transform`` folder, which is going to be created on startup when missing if the XSLT output format has been installed in GeoServer. Each XSLT transformation must be configured with its own xml file in the ``$GEOSERVER_DATA_DIR/wfs/transform`` folder, which in turn points to a xslt file for the transformation. While the names can be freeform, it is suggested to follow a simple naming convention: * .xml for the xml config file * .xslt for the xslt tile Transformations can be either global, and thus applicable to any feature type, or type specific, in which case the transformation knows about the specific attributes of the transformed feature type. Global transformation example ----------------------------- Here is an example of a global transformation setup. The ``$GEOSERVER_DATA_DIR/wfs/transform/global.xml`` file will look like: .. code-block:: xml text/xml; subtype=gml/2.1.2 HTML text/html html global.xslt Here is an explanation of each element: * ``sourceFormat`` (mandatory): the output format used as the source of the XSLT transformation * ``outputFormat`` (mandatory): the output format generated by the transformation * ``outputMimeType`` (optional): the mime type for the generated output. In case it's missing, the ``outputFormat`` is assumed to be a mime type and used for the purpose. * ``fileExtension`` (optional): the file extension for the generated output. In case it's missing ``txt`` will be used. * ``xslt`` (mandatory): the name of XSLT 1.0 style sheet used for the transformation The associated XSLT file will be ``$GEOSERVER_DATA_DIR/wfs/transform/global.xslt`` folder, and it will be able to transform any GML2 input into a corresponding HTML file. Here is an example: .. code-block:: xml

Attribute	Value

Type specific transformations ----------------------------- Type specific transformations can refer to a specific type and leverage its attributes directly. While not required, it is good practice to setup a global transformation that can handle any feature type (since the output format is declared in the capabilities document as being general, not type specific) and then override it for specific feature types in order to create special transformations for them. Here is an example of a transformation declaration that is type specific, that will be located at ``$GEOSERVER_DATA_DIR/wfs/transform/html_bridges.xml`` .. code-block:: xml text/xml; subtype=gml/2.1.2 HTML text/html html html_bridges.xslt cite:Bridges The extra ``featureType`` element associates the transformation to the specific feature type The associated xslt file will be located at ``$GEOSERVER_DATA_DIR/wfs/transform/html_bridges.xslt`` and will leveraging knowlegde about the input attributes: .. code-block:: xml

Bridges

ID:
FID:
Name:

.. note:: While writing the XSLT always remember to declare all prefixes used in the sheet in the ``stylesheet`` element, otherwise you might encounter hard to understand error messages A specific feature type can be associated to multiple output formats. While uncommon, the same xslt file can also be associated to multiple feature types by creating multiple xml configuration files, and associating a different feature type in each. Rest configuration ------------------ Transformations can be created, updated and deleted via the REST api (normally, this requires administrator privileges). Each transformation is represented with the same XML format used on disk, but with two variants: * a new ``name`` attribute appears, which matches the XML file name * the ``featureType`` element contains also a link to the resource representing the feature type in the REST config tree For example: .. code-block:: xml test text/xml; subtype=gml/2.1.2 text/html html test-tx.xslt tiger:poi Here is a list of resources and the HTTP methods that can be used on them. ``/rest/services/wfs/transforms[.]`` .. list-table:: :header-rows: 1 * - Method - Action - Return Code - Formats - Default Format - Parameters * - GET - List all available transforms - 200 - HTML, XML, JSON - HTML - * - POST - Add a new transformation - 201, with ``Location`` header - XML, JSON - - name, sourceFormat, outputFormat, outputMimeType * - PUT - Update global settings - 200 - XML, JSON - - * - DELETE - - 405 - - - The ``POST`` method can be used to create a transformation in two ways: * if the content type used is ``application/xml`` the server will assume a ```` definition is being posted, and the XSLT will have to be uploaded separately using a ``PUT`` request with content type ``application/xslt+xml`` against the transformation resource * if the content type used is ``application/xslt+xml`` the server will assume the XSLT itself is being posted, and the ``name``, ``sourceFormat``, ``outputFormat``, ``outputMimeType`` query parameters will be used to fill in the transform configuration instead ``/rest/services/wfs/transforms/[.]`` .. list-table:: :header-rows: 1 * - Method - Action - Return Code - Formats - Default Format * - GET - Returns the transformation - 200 - HTML, XML, XSLT - HTML * - POST - - 405 - - * - PUT - Updates either the transformation configuration, or its XSLT, depending on the mime type used - 200 - XML, XSLT - * - DELETE - Deletes the transformation - 200 - - The PUT operation behaves differently depending on the content type used in the request: * if the content type used is ``application/xml`` the server will assume a ```` definition is being sent and will update it * if the content type used is ``application/xslt+xml`` the server will assume the XSLT itself is being posted, as such the configuration won't be modified, but the XSLT associated to it will be overwritten instead