[[TOC]]
[wiki:S3XRC] | [wiki:S3XRC/S3XML S3XML] | Transformation
= S3XML On-the-fly Transformation =

== At a glance ==

S3XRC can perform XSLT transformation of XML/JSON sources on-the-fly upon data export and import.

[[Image(s3xml.png)]]

The XSLT stylesheets to use for this transformation can be either (fallback cascade in this order):

  - a static file on the server or a web URL
  - a file attached to the request (at import)
  - an integrated stylesheet of Eden (folder static/xslt)

Note that formats *.xml and *.json will not be attempted to transform.

== Integrated Stylesheets ==

These will automatically used if no other stylesheet is specified (fallback). The integrated stylesheets reside in:

  - static/xslt/export for export transformation (S3XML into other format)
  - static/xslt/import for import transformation (other format into S3XML)

The name of the respective stylesheet must be <extension>.xsl, where <extension> is the file extension of the respective format, e.g.:

  - pfif.xsl transforms from/to *.pfif from *.xml

== XSLT Stylesheets on the Server ==

You can use the URL variable {{{?transform=}}} to specify a transformation stylesheet at a file location on the server, e.g.:

{{{
http://127.0.0.1:8000/vita/pr/person.pfif?transform=/use/share/stylesheets/export.pfif
}}}

...to use the stylesheet from {{{/use/share/stylesheets/export.pfif}}} for this export.

Note:
  - the web server must be permitted to access this location
  - you must not specify "xml" or "json" as data format of the resource, otherwise this will suppress any transformation attempt
  - this currently assumes that the data format is an XML format and not JSON (subject to change in the near future)
== XSLT Stylesheets on the Web ==

You can use the URL variable {{{?transform=}}} to specify a transformation stylesheet at a web URL to be used at import, e.g.:

{{{
http://127.0.0.1:8000/vita/pr/person.pfif?transform=http://vita.sahanafoundation.org/eden/static/xslt/export/pfif.xsl
}}}

...to use the stylesheet at {{{http://vita.sahanafoundation.org/eden/static/xslt/export/pfif.xsl}}} for this export.

Note:
  - you must not specify "xml" or "json" as data format of the resource, because that will suppress any transformation attempt
  - this currently assumes that the data format is an XML format and not JSON (subject to change in the near future).

== Attached XSLT Stylesheets ==

For data import, an XSLT stylesheet to transform foreign XML into S3XML can be attached to the request.

The filename of the attached stylesheet is expected to be {{{<resourcename>.xsl}}}, where {{{<resourcename>}}} is the name of the target resource (without application prefix, e.g. {{{person}}} or {{{hospital}}}).

Note:
  - {{{document()}}}, {{{xsl:include}}} and {{{xsl:import}}} will need absolute paths in this case (safer to avoid these)

----

DeveloperGuidelines