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

== At a glance ==

The S3 framework 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/formats)

'''Note:'''
  - formats *.xml and *.json will not be attempted to transform
  - PDF, CSV and XLS formats do not (yet) support on-the-fly transformation (subject to change in future versions)

== Integrated Stylesheets ==

Eden comes with a number of integrated XSLT stylesheets for various formats. These will be automatically used if no other stylesheet is specified (fallback). The integrated stylesheets reside in:

  - static/formats/<format>/export.xsl for export transformation (S3XML into other format)
  - static/formats/<format>/import.xsl for import transformation (other format into S3XML)

e.g.
  - pfif/import.xsl transforms from *.pfif
  - pfif/export.xsl transforms to *.pfif

If the HTTP content type of the respective format is not {{{application/xml}}}, then it must be configured in {{{models/00_settings.py}}} (see there).

As of version S3XRC-2.2.0, internal stylesheets still have to be configured in {{{models/00_settings.py}}} in order to be properly applied. This is subject to change in future versions.
== 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/eden/pr/person.pfif?transform=/user/stylesheets/export.pfif
}}}

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

Note:
  - the Eden 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, e.g.:

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

...to use the stylesheet at {{{http://demo.eden.sahanafoundation.org/eden/static/formats/pfif/export.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).

This feature is especially useful to create custom feeds to integrate into remote sites, e.g. RSS:

  - create your own {{{rss.xsl}}} to transform S3XML into RSS
  - place it on a public (e.g. your own) web server, say {{{http://www.mysite.org/eden-access/rss.xsl}}}
  - provide a link to Eden resources using your RSS stylesheet:
    - {{{http://edensite.org/eden/hms/hospital.rss?transform=http://www.mysite.org/eden-access/rss.xsl}}}

Basically that means, that a remote site do not need to implement their own XSLT transformation engine in order to integrate with Eden. They just need to have the XSLT stylesheet, and then let the Eden engine transform the data from/into the format they want/have.

Of course this does work with other formats as well, e.g. KML (if you want to provide a map rather than a feed link) etc
== 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)

== See Also ==
* DeveloperGuidelines
* XsltTemplates