# Ten&Two XSLT Processor

**Contributors:** tenandtwo  
**Donate link:**  
**Tags:** xml, xsl, xslt, csv, shortcode  
**Requires at least:** 5.2  
**Tested up to:** 6.5  
**Requires PHP:** 7.4  
**Stable tag:** 1.0.7  
**License:** GPLv2 or later  
**License URI:** https://www.gnu.org/licenses/gpl-2.0.html  


Transform and display XML from local and remote sources using PHP's XSL extension.

[![](https://img.shields.io/wordpress/plugin/installs/tenandtwo-xslt-processor?style=flat-square)](https://wordpress.org/plugins/tenandtwo-xslt-processor/)


## Description

The Ten&Two XSLT Processor plugin brings the power of PHP's [XSL extension](https://www.php.net/manual/en/book.xsl.php) to Wordpress.  Once enabled, the plugin creates three (3) shortcodes - **`[xslt_transform_xml/]`**, **`[xslt_select_xml/]`**, and **`[xslt_select_csv/]`** - which can be used separately or in tandem to enrich your site with content from XML and CSV sources.  The plugin also enables two (2) custom post types - **`XSL Stylesheets`** and **`XML Documents`** - for managing and validating sources within WP Admin.

Detailed documentation and sample code can be found at [https://plugins.tenandtwo.com/](https://plugins.tenandtwo.com/)


### Custom Post Types

The XSLT Processor plugin provides two (2) custom post types for managing sources within Wordpress - **`XSL Stylesheets`** and **`XML Documents`**.  Both types include basic syntax validation.  XML Documents can be validated further using DTD, XSD, or RNG.  Both types are enabled in *Settings* > *XSLT Processor Settings* > *Activate Content Types*.


### Shortcode : [xslt_transform_xml/]

`[xslt_transform_xml/]` is the plugin's primary function.  This shortcode processes XML data using an XSL stylesheet, and then outputs the result as HTML, more XML, or as simple TEXT.

 - **`[xslt_transform_xml xsl="{file|url|id|slug}" xml="{file|url|id|slug}" /]`**
 - **`[xslt_transform_xml xsl="{file|url|id|slug}"]<DATA>...</DATA>[/xslt_transform_xml]`**

If either the `xsl` or `xml` parameter is left unspecified, defaults are used.  The default XML value is `<NODATA/>`.  The default XSL stylesheet prints all of the incoming data as HTML.  If extra attributes are specified in the shortcode - eg, `mykey="myval"` - those keys/values are passed along as parameters to the stylesheet - `<xsl:param name="mykey"/>`.


### Shortcode : [xslt_select_xml/]

`[xslt_select_xml/]` is a helper function.  It reads XML and returns a selection of the data, based on a supplied XPath expression.  There are two (2) options for specifying the XPath.  First, using the `select` attribute or, second, using the body of the shortcode.  Complex select statements with quotes, square brackets or other special syntax, should use the second pattern :

 - **`[xslt_select_xml xml="{file|url|id|slug}" select="{XPath}" /]`**
 - **`[xslt_select_xml xml="{file|url|id|slug}"]{XPath}[/xslt_select_xml]`**

If the XPath select parameter is left unspecified, the default `/` is used, which returns the entire document.  The default output is `format="xml"`.  If `format="json"` is specified, the result is encoded as a JSON string.


### Shortcode : [xslt_select_csv/]

`[xslt_select_csv/]` is a helper function for converting CSV file data to XML.  The result can be output directly as an HTML `<table>`, or the result can be passed to `[xslt_transform_xml/]` for further processing.

 - **`[xslt_select_csv csv="{file|url}" /]`**
 - **`[xslt_select_csv]{csv,data}[/xslt_select_csv]`**

Three (3) parameters - `separator`, `enclosure`, `escape` - control reading the input.  See PHP's [fgetcsv()](https://www.php.net/manual/en/function.fgetcsv.php) function for details.

 - **`[xslt_select_csv separator="," enclosure="\"" escape="\\" /]`**

Two (2) parameters - `key_row`, `col` - control writing columns to the output.  The `key_row` attribute is optional, but allows labels from that row to be used in `col` and `key_col`.

 - **`[xslt_select_csv key_row="{num}" col="{num|letter|label}+" /]`**

Three (3) parameters - `row`, `key_col`, `key` - control writing rows to the output.

 - **`[xslt_select_csv row="{num}+" /]`**
 - **`[xslt_select_csv key_col="{num|letter|label}" key="{val}+" /]`**


### Nested Shortcodes

Combine `[xslt_transform_xml]` with `[xslt_select_xml]` :

 - **`[xslt_transform_xml][xslt_select_xml/][/xslt_transform_xml]`**

Combine `[xslt_transform_xml]` with `[xslt_select_csv]` :

 - **`[xslt_transform_xml][xslt_select_csv/][/xslt_transform_xml]`**

Combine `[xslt_transform_xml]` with itself using `[/xslt_transform_alias]` (WP does not support nested shortcodes with identical names) :

 - **`[xslt_transform_alias][xslt_transform_xml/][/xslt_transform_alias]`**

Combine multiple shortcodes/sources to create a single `XML Document` (see Custom Post Types above) :

 - **`<DATA><PART1>[xslt_select_xml xml="f1.xml" /]</PART1><PART2>[xslt_select_xml xml="f2.xml" /]</PART2></DATA>`**


### Cache Parameters

When a shortcode specifies a remote file - `xml="{url}"` or `csv="{url}"` - that source is cached locally using WP Transients. The default cache duration is set in the *XSLT Processor Settings*.  To override the default, add `cache="{minutes}"` to the shortcode.

 - **`[xslt_transform_xml xml="{url}" cache="{minutes}" /]`**
 - **`[xslt_select_xml xml="{url}" cache="{minutes}" /]`**
 - **`[xslt_select_csv csv="{url}" cache="{minutes}" /]`**


### Namespace Parameters

Within `[xslt_select_xml/]` the plugin provides two (2) methods for handling XML containing namespaces.  The first is to add `strip-namespaces` to the shortcode.  The second method is to add the needed prefixes and namespace URIs using `xslns`.

 - **`[xslt_select_xml xml="{file}" strip-namespaces="yes" select="//node" /]`**
 - **`[xslt_select_xml xml="{file}" xmlns="ns1" ns1="{namespace-uri-1}" select="//ns1:node" /]`**
 - **`[xslt_select_xml xml="{file}" xmlns="ns1 ns2" ns1="{namespace-uri-1}" ns2="{namespace-uri-2}" select="//ns1:node/ns2:node" /]`**


### WP-CLI

All three (3) shortcodes have command-line equivalents. They can be used, for instance, to run quick tests. Or they can be used, by piping the outputs into files, to pre-generate results.

 *      wp xslt transform_xml
            --xsl='{file|url|id|slug}'
            --xml='{file|url|id|slug}'
            --cache='{minutes, if xsl|xml={url}}'
            --tidy='{yes|html}' or tidy or --tidy='xml'
            --{myparam}='{myvalue}'
            --outfile='{filepath}'
            --htmlentities or --htmlentities='yes'

 *      wp xslt select_xml
            --xml='{file|url|id|slug}'
            --cache='{minutes, if xml={url}}'
            --select='{xpath}'
            --root='{nodename|empty}'
            --tidy='{yes|html}' or tidy or --tidy='xml'
            --strip-namespaces='yes' or strip-namespaces
            --strip-declaration='no'
            --format='{xml|json}'
            --htmlentities or --htmlentities='yes'

 *      wp xslt select_csv
            --csv='{file|url}'
            --cache='{minutes, if csv={url}}'
            --separator=','
            --enclosure='\"'
            --escape='\\'
            --key_row='{row number for column labels}'
            --col='{return column number(s), letter(s), or label(s)}'
            --key_col='{col number, letter, or label for key matching}'
            --key='{value(s) for key_col matching}'
            --row='{return row number(s)}'
            --class='{css classname(s) for result <table>}'
            --htmlentities or --htmlentities='yes'


### XSL Stylesheets

The XSLT Processor plugin includes a number of useful XSL templates that you can include and use in your own projects. They are grouped into five files.

 - **date.xsl** : `date-format`, `date-microtime`
 - **file.xsl** : `file-exists-local`, `file-exists-remote`
 - **string.xsl** : `string-replace`, `string-upper`, `string-lower`, `string-title-case`, `string-trim`, `string-rtrim`, `string-ltrim`, `string-maxlength`, `string-maxwords`, `string-add-slashes`, `string-urlencode`, `string-strip-tags`, `string-nl2br`, `string-entity-decode`, `string-to-nodeset`
 - **util.xsl** : `util-bytsize`, `util-hash-data`, `util-print-nodes`, `util-print-node-names`, `util-super-global`
 - **wp.xsl** : `wp-select-xml`, `wp-select-csv`, `wp-post-item`, `wp-post-meta`, `wp-sanitize-title`, `wp-size-format`



## Installation

### WordPress installation

1. Go to *Plugins* > *Add New* > *Search* for "tenandtwo-xslt-processor"
1. Press **Install Now** for the "Ten&Two XSLT Processor" plugin
1. Press **Activate Plugin**

### WP-CLI installation

1. `wp plugin install tenandtwo-xslt-processor --activate`

### Manual installation

1. Download the latest archive from the [Plugin Homepage](https://wordpress.org/plugins/tenandtwo-xslt-processor)
1. Upload the `tenandtwo-xslt-processor` directory to your `/wp-content/plugins/` directory
1. Activate the plugin through the *Plugins* menu in WordPress

For more details on installation options, see [Manage Plugins](https://wordpress.org/documentation/article/manage-plugins/) at wordpress.org.

## Requirements

The Ten&Two XSLT Processor plugin relies upon PHP's [XSL extension](https://www.php.net/manual/en/book.xsl.php).  If the extension is installed, the *XSLT Processor Settings* screen will display a message similar to the first message below.  If `LIBXSLT_VERSION` is undefined, all plugin options are disabled automatically and the second message is displayed.

 - `PHP's XSL extension is available : XSLT v1.1.32, EXSLT v1.1.32, LIBXML v2.9.4`
 - `PHP's XSL extension is NOT available`

The XSL extension's requirements are detailed at [php.net](https://www.php.net/manual/en/book.xsl.php) :


> "This extension requires the libxml PHP extension. This means passing the **--with-libxml**, or prior to PHP 7.4 the **--enable-libxml**, configuration flag, although this is implicitly accomplished because libxml is enabled by default.
>
> This extension uses libxslt which can be found at » [http://xmlsoft.org/XSLT/](http://xmlsoft.org/XSLT/). libxslt version 1.1.0 or greater is required."


## Frequently Asked Questions


### Where are the plugin options?

In WordPress, go to *Settings* > *XSLT Processor Settings*.  There are four (4) sections :

 - **Activate Content Types**
 - **Activate Shortcodes**
 - **Cache Lifetime**
 - **Local File Search Paths**


### Where is the documentation?

For a quick reference to the shortcodes and their main parameters, go to *Settings* > *XSLT Processor Settings*.  The samples for each shortcode show common usage.

Full documentation and working examples are available at https://plugins.tenandtwo.com/.  There are four (4) main sections :

 - [**Getting Started**](https://plugins.tenandtwo.com/xslt-processor/getting-started)
 - [**Shortcodes**](https://plugins.tenandtwo.com/xslt-processor/shortcodes)
 - [**Stylesheets**](https://plugins.tenandtwo.com/xslt-processor/stylsheets)
 - [**How To**](https://plugins.tenandtwo.com/xslt-processor/how-to)