%META:TOPICINFO{author="PatrickDiamond" date="1099672794" format="1.0" version="1.21"}%
---++ XMLQuery TWiki Plugin

This Plugin enables the following XML data sources to be queried and transformed via XSLT
	1 TWiki Topics data on actions, tables and metadata. This data is parsed when a topic is saved and stored seperately as XML.
	1 TWiki XML attachments.
	1 URLs which export XML

---+++ <nop>%TOPIC% Settings
	* Short Description of the XMLQuery Plugin
		* Set SHORTDESCRIPTION = Apply XSLT queries to Topics, XML attachments & URL's

	* Directory where both XML versions of topics and query results are cached. This will need to be altered on a Windows machine e.g. c:/twiki_xml. Expect the size required by this to be around 1k multiplied  by the number of topics in your TWiki.
		* Set XMLDIR = /var/tmp/twiki_xml

	* The size limit on the results cache valid values are __number Kb|Mb|Gb__ . This is located under your XMLDIR
		* Set CACHESIZELIMIT = 100Mb

	* The time limit on the results cache valid values are  __now__, __never__, __number seconds|minutes|hours|days|weeks|months|years__ . This value can be overridden per query using the __cache__ attribute
		* Set CACHEEXPIRES = never

	* Debug this plugin: (See output in =data/debug.txt=)
		* Set DEBUG = 0

---+++ Syntax Rules

---++++ XSLTSTART tag: defining a stylesheet

The basic format of an XSLT query is as follows

%<nop>XSLTSTART{topic="^StartsWith.*"}%

__some XSLT, see recipts for example XSLT__

%<nop>XSLTEND%

| *Parameter*| *Comment* | *Default* |
|*web*| This a regular expression which can match multiple webs e.g. ^Work | current web |
|*topic*| This is a regular expression that matchs topics within the web(s) matched by the __web__ parameter | current topic |
|*attach*| This is a regular expression which is matched against attachments on already matched topics. The contents of these attachments is include in the XML parsed by this XSLT | |
|*url*| specify a url from which to extract XML. If specified this overrides the above XML sources | |
|*debug*| Accepts one of __on__ , __off__ or __full__ <br> __on__ lists the input XML, the XSLT being parsed, the raw output and plugin and cache settings <br> __off__ switches off debug out <br> __full__ by default the XML output in the debug is limited to the first 10k. This option will output it all. Browser beware | __off__ |
|*cache*| Override the plugin defaults on expiring result cache. <br/> Valid values are <ul><li> __never__ the cache is never expired</li><li> __now__ the cache is expired now</li><li> __x [seconds,minutes,hours,days,weeks,months,years]__ specify exactly how long the cache should live| __never__ |
|*anything*| Every other parameter specified is passed directly to the query as an XSLT paramter. This is the best way of inserting or passing TWiki content to an XSLT query.| |

---++++ XML Format

The XML created from Topic text has the following format. 

<verbatim>
<twiki>
	 <web name="Bla">
		  <topic name="BlaBla">
				<data topic="BlaBla" web="Bla" version="Bla">
					 <tables>
						  <table bla="bla">
								<row>
									 <field type="title">Bla</field>
									 <field type="data">Bla</field>
									 .... 
								</row>
								....
							</table>
							....
					  </tables>
					  <actions>
							<action bla="bla" ..../>
							.... 
					  </actions>
					  <metadata>
							<? bla="bla"..../>
					  </metadata>
					  <xmldata>
							....	
					  </xmldata>
				 </data>
			<attachments>
				 <attachment name="bla">
					  ....
				 </attachment>
				 ....
			</attachments>
			</topic>
	  </web>
</twiki> 
</verbatim>

Attachment data is only available if the attach parameter is used within the XSLTSTART tag. The table and action tag each contain the same arguments as specified within the TWiki text. This is a very useful way to pass metadata into the XML. The argument doesn't have to mean anything to the TWiki macro for it to be available. One use for this could be to create id and class parameters on these data sets.

Metadata is handled in a generic fashion where the metadata name/type becomes the tag name and every argument to the metadata becomes an argument to the XML element.

To view actual structure of any TWiki page reference it in a XSLTSTART tag and set debug = "on" or "full".

---++++ XMLSTART tag: defining XML content within a wiki page

If you need to specify XML data directly within a twiki page the XMLSTART/XMLEND tags can be used. 
For example.

%<nop>XMLSTART{display="hidden"}%

__some XML__

%<nop>XMLEND%

| *Parameter*| *Comment* | *Default* |
|*display*| This controls the display of the XML text <ul><li> __hidden__ The XML text is hidden from display but still available to XSLT queries</li><li> __verbatim__ The XML is displayed exactly as entered</li><li> __include__ the XML is included along with the rest of the TWiki text in the display</li></ul> | __hidden__ |


---+++ Plugin Installation Instructions

---++Requirements

The following Perl modules have to be installed before this Plugin

	* XML::LibXML
	* XML::LibXSLT
	* XML::Simple
	* Text::ParseWords
	* Cache::Cache
	* String::CRC

---++ Recipes

As XSLT has has a very powerful but complex syntax here are several (hopefully) useful examples. If you do create a query that could be useful to others and would like to share then please do create a Recipe similar to  the ones below and send to %TWIKIWEB%.PatrickDiamond.

	* [[XMLQueryPluginRecipe1][Recipe 1]]: List all Attachments in the current Web
	* [[XMLQueryPluginRecipe2][Recipe 2]]: Attachments Queried using parameters
	* [[XMLQueryPluginRecipe3][Recipe 3]]: Table Contents Filtered
	* [[XMLQueryPluginRecipe4][Recipe 4]]: Table Contents Restructured
	* [[XMLQueryPluginRecipe5][Recipe 5]]: Creating a unique sort list from the contents of a table column

---++Useful Tutorials

To learn more about XML and XSLT try the following online resources

	* [[http://www.vbxml.com/xsl/default.asp][TopXML]] XSLT Tutorials and References
	* [[http://www.w3schools.com/xml/default.asp][XML]] XML Tutorials
	* [[http://www.w3schools.com/xsl/default.asp][XSLT]] XSLT Tutorials
	* [[http://www.w3schools.com/xpath/default.asp][XPath]] XPATH Tutorials
	* [[http://www.exslt.org/][EXSLT]] Extensions to XSLT available in <nop>LibXSLT


---+++ Plugin Info

|  Plugin Author: | %TWIKIWEB%.PatrickDiamond |
|  Plugin Version: | 1.000  |
|  Change History: | 2 Nov 2004 : Initial version |
|  CPAN Dependencies: | XML::LibXML XML::LibXSLT XML::Simple Text::ParseWords Cache::Cache String::CRC |
|  Other Dependencies: | none |
|  Perl Version: | 5.6 |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins

