Quixml: A PHP class to ease the XML + XSL development

Welcome to manual zone of Quixml.org.
I will try to explain as best as I can how you can use and leverage this library.

Index:

Quixml: A PHP class to ease the XML + XSL development

XML & XSL because...

... It's rock solid.
... It's allow a easier port of the interface to other devices (human or digital)
... It lighten your server work by making the browser compose the interface
... It lighten your bandwidth use by sending less data, just templates and multimedia files composing the interface
... It's the ultimate separation between your site's logic and visual presentation
... It allows you to have separate output for different device without touching the logic files, only a separate "rendering set" of XSL style sheets are needed.
... It's allow your developers to not worry about the designer messing the files, as the designer don't need to have access to the programmer files.

An instant in the life of your site...

There is a typical action triggered when a user wants to display a page via this class:

The user request the page
The server detect which browser and which operating system is used by the user.
The server determine which XSL style sheet should be used from instructions into the rendered page.
A XML file is generated and sent to the browser, with an URL to get the XSL style sheet.
The browser request the style sheet to the server
The browser uses it's XSLT engine to apply the visual styles defined into the XSL on the datas stored in the XML

Now, every browsers don't include a XSLT engine, but in those case, it would be detected automatically by the class, and the XML would be transformed on the server.

What is required for this class to work?

The requirements for this class are:

PHP 5.0
When upgrading from PHP 4 to PHP 5, the XML and XSL parts of the engine had nearly total rewrite, and they are not compatible. Thus, this class requires the PHP server to run PHP 5.0 at least.
The xmlWriter extension should be active.
This is intended to be dropped in the future, but right now, we are leveraging this extension methods to generate XML
The XSL extension should be active.
Otherwise, browser without support for a local XSLT engine would fail to display the page.

In addition, the XSL generation can do a caching of the style sheets generated.
If you choose to activate this cache, the generated sheets will be stored into a sqLite database, so your server should include those extensions as well:

The PDO database framework
The PDO::sqlite driver

Defined constants

This class relies on several constants to adapt it's behavior to your taste.
In the current state, those methods are contained into the /libs/prepend/prepend.php and /libs/globals/vars.php files.
Only the constant into vars.php should be modified, as the values in prepend.php are usually auto-detected and serve as a base for several vars.php constants.
Here is the list of the define you will see in the class code:

(prepend.php) DOC_ROOT
An alias to $_SERVER['DOCUMENT_ROOT']. It's the base used to determine every paths.
(vars.php) XSL_ROOT
The emplacement where the XL rendering sets and style sheets are stored.
Default: "DOC_ROOT/../xsl"
(vars.php) XSL_URL_PREFIX
When outputting the XML, is used to compose the XSL style sheet web path, for the browser XSL engine.
Default to "/xsl/"
(vars.php) XSL_OPEN
The default name of the prepended XSL style sheet. On every rendering set, a file named like XSL_OPEN will be prepended to the requested XSL style sheet.
Default: "open"
(vars.php) XSL_CLOSE
The default name of the appended XSL style sheet. Like for XSL_OPEN, but this file will be appended to the requested XSL style sheet.
Default: "close"
(vars.php) INCLUDE_TAG
The XSL generation process can include an XSL fragment into the current style sheet.
This is the tag to bee looking in the XSL files source to trigger an include.
Default: "<INCLUDE "
!!! Notice the space at the end !!!
Take care too that the class waits for the path and the tag closure to be concatened,
like this: "<INCLUDE org.sixop.include/>"
(vars.php) SQLITE_ROOT
The emplacement where to store sqLite db files.
Default: DOC_ROOT/../sqlite

Methods available

You have a set of available methods available to you to ease the output of the XML:

(boolean) setRendering( string $renderingSetName)
This function should be called first. It allows you to select a specific rendering set. If the rendering set you choose is not available, return FALSE.
Once a rendering set have been selected, it's stored in the user session and remembered. Simply call back this function if you want to change it.
(string) getRendering( void )
Return the current selected rendering set
(boolean) setXsl( string $xslName)
Check that the specified XSL style sheet exists, and associate it to the current XML document.
If the file is not found, return FALSE and add a comment in the XML saying that the style sheet could not be found
(void) start( void )
Start a new XML document and open the <ROOT> element. This should be called after setRendering() and setXsl()
(void) open( string $nodeName)
Open a node.
(void) close( void )
Close a previously opened node, or the XML document
(void) data( string $nodeName, mixed $nodeValue)
Add an element.
(void) att( string $attributeName, mixed $attributeValue)
Add an attribute to an element.
!!! Warning !!! At this point, an attribute can only be put on a opened node. An element added via data() is already closed, and cannot be modified anymore. This limitation is meant to be dropped at the same time as xmlWriter.
(void) general( void )
Create a <GENERAL /> node, with a predefined (to be customized by you) set of elements. It's meaning is to contain a set of informations that should not change much from pages to pages, like the status of the member, how many user active, which part of the site the user is browsing...
(string) generateXsl( string $xslName)
This method is used to generate the final XSL style sheet that will be sent to the browser. This method is public, but should be called by the PHP file serving the XSL to the browser.

For more detailed explanations, look in the class reference.

Basic XSL functions

Now that the XML is generated, and you have specified the name of the XSL style sheet to be used, you need to make it available.
The preferred and recommended method this site use to serve the XSL documents is via a simplified url "/xsl/filename".
The file name, in this case, is the one that you have specified in your xml, via setXsl().

If you want the XSL access path to be different, you will need to modify it both in the exemples below, and in the XSL_URL_PREFIX constant.

First, we have to tell the web browser that we want our XSL shortcut to point to the XSL generation php script.
This can be done either

In placing the file /libs/xml/xsl.php at the place you want it, and by specifying "/path_to/xsl.php?path=" as the value of XSL_URL_PREFIX
By creating a URL rewrite handler that will redirect the browsers request to our shortcut to the php script.
This is the recommended method, as it is more flexible.
Here is the rule used on this site, into a .htaccess file:
RewriteEngine On
RewriteBase /

#This point to the PHP file generating the XSL stylesheet
RewriteRule ^xsl/(.*)$ /libs/xml/xsl.php?path=$1 [NC,L]

And voilà...
Your XSL style sheets are now ready to be served.

Advanced XSL functions

The XSL parser have one advanced function that I'd like to present you.
It have the ability to include a fragment of XSL into the currently processed style sheet.
To trigger this functionality, you just need to add an
<INCLUDE org.quixml.example_include/>
Into your style sheet.
When this sheet will be queried for the first time, every include tags will be parsed, and if the specified file is to be found, it's content will replace the include request.
The value of the include trigger can be altered, by changing the INCLUDE_TAG constant value.
Take care of the case, an "<include org.quixml.example_include/>" will not trigger the inclusion mechanism.

XSL style sheets caching

To lighten the XSL generation process, as a file can have several includes, the class implement a local caching mechanism.
Local, because it uses a self contained file in sqlite format to store the parsed style sheet. The database file is stored into the directory specified by the constant SQLITE_ROOT
You can set the caching mechanism on/off and set the default time to live for the cached style sheet in the clXml class definition.
By default, the cache is enabled, and the time to live of the style sheets is 15 minutes.
Here is the default schema of the cache table:

CREATE TABLE xslCache(
md5 numeric not null,    /*MD5 of the XSL without the includes parsed*/
xsl text not null,             /*The parsed XSL style sheet*/
lang char(2) not null default 'en',     /*If the site is multi lingual, allow several versions of the same sheet in different languages to be saved*/
path text not null,            /*The file name specified to access the style sheet*/
creaDt numeric,            /*The unix timestamp of the insertion in this db*/
primary key(md5, path, lang)
);

As sqlite don't have a date/time data type, an numeric type is used, with a unix timestamp.
The "lang" field is here to allow several versions of the same style sheet to be stored in different languages.

The caching mechanism uses PDO and sqlite 3. If you would prefer to integrate the cache into an existing database, feel free to modify this section and the insert/delete queries.
The delete query is into the method clXml::cleanXslCache(), which is ran only when the cache is enabled, and when the expression rand(0,100)%3===0 is true.

And this conclude this manual...

If you would like to know the inner working of this class in a more detailed way, you can consult the class documentation browser.