[[PageOutline(2-5,Contents,pullout)]]

= XSL-Transformation Macro

== Description

The XsltMacro allows you to embed the result of an XSL-transformation in a page. It takes two parameters, a stylesheet and a document to transform. These can be an attachment on any wiki-page or ticket, any page from the htdocs area, any file in the repository, or any url. These options are similar to those for Trac's native [t:wiki:WikiMacros#AvailableMacros ImageMacro].
 
For more details see the documentation in the macro.

With this macro call:

{{{
[[Xslt(format.xsl, info.xml)]]
}}}

The following table is produced:

{{{#!html
<table border="1">
<tr>
<th>Name</th>
<th>Address</th>
<th>Email</th>
</tr>
  <tr>
<td>John Smith</td>
<td>42 Easy St</td>
<td>johns@cool.com</td>
</tr>
  <tr>
<td>Mary Francis</td>
<td>1 Heavenly Way</td>
<td>maryf@hot.com</td>
</tr>
</table>
}}}

Here's how you would tell it to use an iframe:
{{{
[[Xslt(format.xsl, info.xml, use_iframe, if_height=500)]]
}}}

For the full docs see the WikiMacros page after installing this macro.

The macro can either be installed as a simple macro or as a plugin; the ''use_iframe'' and ''use_object'' options (see below) only work when installed as a plugin.

This macro requires that [http://xmlsoft.org/ libxml2], [http://xmlsoft.org/ libxslt], and their python bindings are installed.

=== IFrames/Objects

Because a macro's output is embedded in the html of the wiki page, the xsl-stylesheet must not produce a full html page. As an alternative, you can pass the ''use_iframe'' or ''use_object'' option to the macro; this will cause the macro put an <iframe> or <object> tag (respectively) into the page instead of the results from the stylesheet. The stylesheet can (and must) then generate a complete html page.

The downside of iframes/objects is that you need to know the height of the result in order to set the height of the iframe/object; otherwise you will either get extra space at the bottom or you'll have to scroll through the frame. The macro generates some javascript to automatically set this height, but that only works if the user has javascript enabled of course.

== Bugs/Feature Requests

Existing bugs and feature requests for XsltMacro are 
[report:9?COMPONENT=XsltMacro here].

If you have any issues, create a 
[/newticket?component=XsltMacro new ticket].

[[TicketQuery(component=XsltMacro&group=type,format=progress)]]

== Download

Download the zipped source from [export:xsltmacro here].

== Source

You can check out XsltMacro from [/svn/xsltmacro here] using Subversion, or [source:xsltmacro browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Recent Changes

[[ChangeLog(xsltmacro, 3)]]

== Author/Contributors

'''Author:''' [wiki:roadrunner] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:''' wuxxin at gmail.com