---
title: "XSLT macro"
canonical: "https://support.appfire.com/space/HTML/70617219/XSLT%20macro"
format: markdown
---
> Macro (aura-html)
## Features
- Uses XSLT to transform XML to HTML, XHTML, or wiki markup. Supports XSLT 1.0.
- It supports working with XSL parameters, but it is only available with the *wiki* output format. See the [Passing parameters to the XSLT engine](#transformerParameters) section.
- Supports security restrictions as described in [Macro Security for Confluence](https://appfire.atlassian.net/wiki/x/CIAEB).
- Supports capabilities for including data similar to other scripting macros.
- Supports find and replace for adjusting the resulting output.
> ℹ️ - The macro works with valid, downloadable XML and XSLT files only.
> ℹ️ - If you want to specify a URL in the *Location* parameters, make sure that only a raw URL is provided. A raw URL is defined as the part of the URL following the domain information and includes the query string, if present. For example, in the URL string `http://www.contoso.com/articles/recent.aspx`, the raw URL is `/articles/recent.aspx`.
## Parameters
| **Macro browser label** | **Default** | **Description** | **Macro parameter** |
| --- | --- | --- | --- |
| *Transformed output format* | *html* | Specify how the output is treated. The options are as follows:
- *html* - transformed output is standard HTML.
- *xhtml* - transformed output is treated as XHTML and rendered with the Confluence XHTML renderer.
- *wiki* - transformed output is treated as wiki markup and rendered with the Confluence wiki renderer. | output |
| *Profile* | | Enter the profile name to access the files to be transformed. Profiles contain a basic set of parameters used to access a remote location, such as the type of URL, user credentials, and so on. Refer to the [profiles configuration](https://appfire.atlassian.net/wiki/x/l4E1B#html_57_config_profiles) to learn more about profiles and see [tutorials](https://appfire.atlassian.net/wiki/x/2IE1B).
> ⚠️ - Contact your Confluence administrator for further information about the profiles available in your instance.
> ⚠️ - If a profile is specified, it is recommended to provide the relative path to the location of the XML file to be rendered. | profile |
| *Location of XML code* | macro body | Enter the location of the XML data. By default, the macro transforms the code entered in the macro body.
- *#filename* - Data is read from the file located in Confluence `home/script/filename` directory. Subdirectories can be specified.
- *global page template name* - Data is read from a global page template. Special note: [How to deal with templates on Confluence 4.3 and later](https://appfire.atlassian.net/wiki/spaces/info/pages/86120194).
- *space:page template name* - Data is read from a space template.
- *#http://...* - Data is read from the URL specified. May require user name and password as well.
> ℹ️ If a *Profile* is specified, the pound (#) sign is optional; that is, the URL is processed regardless of the pound (#) sign before the URL.
- *^attachment* - Data is read from an attachment to the current page.
- *page^attachment* - Data is read from an attachment to the page name provided.
- *space:page^attachment* - Data is read from an attachment to the page name provided in the space indicated.
> ⚠️ *Precedence in URL handling*
> ⚠️
> ⚠️ URLs are processed using a fixed precedence explained as follows:
> ⚠️
> ⚠️ 1. If the given URL is linked to a specific application like Bitbucket, GitLab, or GitHub, the macro does not require any user credentials and processes and renders the given file. Refer to [application links](https://appfire.atlassian.net/wiki/x/14Q1B) for information.
> ⚠️ 2. If *Profile* is specified, the macro appends the URL given here with the URL specified in the profile configuration and accesses the location to render the required file.
> ⚠️ 3. Lastly, if no application links or profiles were given, the URLs are processed as-is and the required file is rendered. | source |
| *Location of XSL code* | macro body | Enter the location of the XSL code. This field becomes mandatory if source XML code is entered in the macro body. By default, though, the XSL content in the macro body is considered.
- *#filename* - Data is read from the file located in Confluence `home/script/filename` directory. Subdirectories can be specified.
- *global page template name* - Data is read from a global page template. Special note: [How to deal with templates on Confluence 4.3 and later](https://appfire.atlassian.net/wiki/spaces/info/pages/86120194).
- *space:page template name* - Data is read from a space template.
- *#http://...* - Data is read from the URL specified. May require user name and password as well.
> ℹ️ If a *Profile* is specified, the pound (#) sign is optional, that is, the URL is processed regardless of the pound (#) sign before the URL.
- *^attachment* - Data is read from an attachment to the current page.
- *page^attachment* - Data is read from an attachment to the page name provided.
- *space:page^attachment* - Data is read from an attachment to the page name provided in the space indicated. | style |
| *Find regex patterns* | | Enter a comma-separated list of regex patterns to repair and modify XML prior to processing by the XSLT processor with find and replace logic. Read more about [regular expressions](https://appfire.atlassian.net/wiki/x/JIE1B).
Example: `(google\.dtd)` | find |
| *Replacement strings* | | Enter a comma-separated list of positions to search for patterns in the output content. Note that the positions are indexed beginning at "1". If a comma is a part of an entry, use single quotes around it.
Example: `http://www.google.com/$1` | replace |
| *Include head section HTML* | false | Enable this option to retain all the other tags from the header section and treat them as regular body content. This is useful for retaining style information in particular. By default, the head tag is always removed. | head |
| *Show error message panel* | false | Displays the XSL transformer generated warning and errors in a panel even if the transformation is not terminated with an error. Terminating errors automatically generate an error panel. | showErrors |
| *Error level* | *NONE* | Specify the level at which the data processing fails. The selected level determines how the XSLT macro handles data processing errors. The options are:
- *NONE* - No action is to be taken.
- *WARNING* - Display a warning about the data process; processing does not stop.
- *ERROR* - Display an error and further processing is halted.
- *FATAL* - Stops any further data processing. | |
| *File encoding* | system default | Specify the encoding for an external file, if different from the system default handling.
Example: `UTF-8` | encoding |
| *Timeout in milliseconds* | | Enter the time in milliseconds to wait until the URL connection times out before getting data. Use this to increase the time needed for slow connections. Note that if a zero is given, the connection may wait indefinitely. | timeout |
| *Disable secure processing feature* | false | Enable this option to disable secure processing of XML and XSL files.
If authorized by your Confluence administrator to change this setting, more powerful capabilities are available. See > Macro (jira)
for details. Administrators can use [Macro Security for Confluence](https://appfire.atlassian.net/wiki/x/CIAEB) to enable these more powerful capabilities. | disableSecureProcessing |
| *XSLT Version* | *1.0* | Select the version based on your style (XSLT) input document. This drop-down contains the XSLT versions that the macro is compatible with. It has been available since version 5.4.0. | xsltVersion |
> ℹ️ *About profiles:*
> ℹ️
> ℹ️ - Administrators create profiles to connect to remote locations. A profile contains the basic information required to access a remote location and usually contains the base URLs of the location. In the macro editor, you must specify the relative URL in the *Location of XML data* parameter. The macro combines these paths to create an absolute URL. If any part of this URL is incorrect or the URL itself is invalid, the macro generates an error. To get more information about profiles, select the relevant article specified in the [Helpful resources](#XSLTmacro-#html_57_helpfulResources) section.
> ℹ️ - If you get an error message, "Security restricted macro with parameter 'profile' is not allowed. An edit restriction is required that matches the macro authorization list.", it means that the *Macro Security* macro has restricted the use of profiles in the macro. Ask your administrator to add the following entries in **Macro Security for Confluence Configuration **> **Secured macros**:
> ℹ️ - Key: *xslt.profile.**
> ℹ️ Value: **ANY*
> ℹ️ - Key: *xslt*
> ℹ️ Value: **ANY*
## Usage
Download a copy of the *cdcatalog.xsl* from [https://www.w3schools.com/xml/cdcatalog.xsl](https://www.w3schools.com/xml/cdcatalog.xsl) and attach it to your page.
```
{xslt:style=^cdcatalog.xsl}
Empire Burlesque
Bob Dylan
USA
Maggie May
Rod Stewart
UK
{xslt}
```
```
{xslt:source=^cdcatalog.xml|style=#http://www.w3schools.com/xsl/cdcatalog.xsl}
{xslt}
```
```
{xslt:source=xslt - basic^cdcatalog.xml|style=#http://www.w3schools.com/xsl/cdcatalog.xsl}
{xslt}
```
> Macro (anchor)
### Passing parameters to the XSLT engine
Parameters not interpreted by the *XSLT* macro are passed through to XSLT. You must use wiki syntax to take advantage of this.
The following example is provided by Johan Nagels:
```
{xslt:output=wiki|source=Home^snippets.xml|winnersOnly=lala}
no
The value of winnersOnly is ""
{xslt}
```
The output of the code is: *The value of winnersOnly is "lala"*
If you omit the parameter tag, the output shown is: *The value of winnersOnly is "no"*
## > Macro (anchor)
Helpful resources
- [Profiles](https://appfire.atlassian.net/wiki/x/l4E1B#Configuration-html_57_config_profiles) in the Configuration screen
- [Key concepts](https://appfire.atlassian.net/wiki/x/voU1B) to understand how to link and render XML content from other sources
## Gallery
