IncludeXML

Summary: Include processed XML into PmWiki 2.2 pages
Version: 20070621
Status: Beta
Prerequisites: pmwiki-2.2, PHP 4.x (php_domxml, php_xslt) or PHP 5.x (php_xsl) and the Linked Resource Extras recipe
Maintainer: Dfaure
Categories: Includes
Discussion: IncludeXML-Talk?

Notes

This recipe takes advantage of XML and XSL functions provided by PHP and its associated modules to let you apply a XSL transformation on XML data and display the results into a wiki page.

A basic sample usage may be to syndicate your PmWiki site to other feeders (and display their datas).

Installation

Before all, XML and XSL support must enabled for your PHP installation. You may check this by temporary setting $EnableDiag = 1 in your config-file and using ?action=phpinfo as described in AvailableActions.

According to the PHP version, the recipe needs the following extensions enabled:

  • PHP 4.x: php_domxml, php_xslt
  • PHP 5.x: php_xsl

You may refer to your ISP and the PHP documentation for more details on extensions availability and how to enable it.

As usual, download and copy includexml.phpΔ to your cookbook/ directory and enable it in your LocalCustomizations file.

Usage

Once installed, the following markups are available:

(:includexml xml=DATA_SOURCE xsl=STYLESHEET_SOURCE OPTIONS:)
Renders an external xml DATA_SOURCE using the external xsl STYLESHEET_SOURCE.
(:xsl xml=DATA_SOURCE OPTIONS:)...STYLESHEET_DATA...(:xslend:)
Renders an external xml DATA_SOURCE using the enclosed xsl definition.
Options
(:xslend:) is not required when using (:xsl ...:) [=...=].
(:xml xsl=STYLESHEET_SOURCE OPTIONS:)...XML_DATA...(:xmlend:)
Renders enclosed xml data using an external xsl STYLESHEET_SOURCE.
Options
(:xmlend:) is not required when using (:xml ...:) [=...=].

Parameters and options

xml=DATA_SOURCE, xsl=STYLESHEET_SOURCE
Respectively, the XML data source to process and the XSL stylesheet data source to use for the transformation.
This could be either:
  • an Uploaded attachement: Attach:some_data.xml,
  • an Intermap? link: InterMap:something/somewhere/else.xsl,
  • or a fully qualified external link: http://host/my/external/resource.rss.
The link target specification is handled by the Linked Resource Extras recipe. See there for syntaxic details and usage options.
The parameter src=DATA_SOURCE is equivalent to xml=DATA_SOURCE for the (:includexml ...:) markup.
-markup
Disables PmWiki Markup formatting of processed datas (useful when generating xhtml).
+debug
Disables most of output formatting (for development phases).

The expected XSL transformation should generate a plain text stream decorated with PmWiki markup. Nevertheless, with the -markup option, you may use appropriate stylesheet to generate (x)html directly.

The markup parameters are filtered and all +... and -... unhandled options are silently discarded. All other parameters are forwarded to the XSL stylesheet, including xml=... and xsl=... as global parameters (according to the triggering markup, the xml=... and xsl=... values may only be available as '-' for the relevant stylesheet).

The includexml-samples.zipΔ provides samples stylesheets to apply on rss feeds. As an usage example, the following directive (on a single line) would retrieve the 7 last PmWiki-users mailing-list messages:

(:includexml
    xml=http://rss.gmane.org/gmane.comp.web.wiki.pmwiki.user
    xsl=Attach:rdf2pm.xsl
    count=7:)

Technical hints

The following configuration variables may be helpful to suit the recipe to your needs:

$IncludeXMLOptions
Maintains the different parameters such as include_path options and stream context data useful when fetching external datas (auth, proxy,...). You may refer to the PHP documentation for more details.
$IncludeXMLDecodeFunc
Gives the name of the character decoding function processing the transformation result before returning it to PmWiki.

Release Notes

2007-06-21
Fixed trimming bug of (:xsl:)...(:xslend:) and (:xml:)...(:xmlend:).
2007-05-31
Major rewrite.
2006-03-07
Cleaned code, merging unreleased enhancements. Updated licensing terms.
2005-11-04
Enabled wiki link convention.
2005-05-27
Tidy up code and parameters forwarding.
2005-05-24
First public release.

See Also

Contributors

Comments

See discussion at IncludeXML-Talk?

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.