dotvoid.com » xsl http://www.dotvoid.com Experiments and thoughts in PHP and javascript Tue, 11 Oct 2011 12:49:15 +0000 http://wordpress.org/?v=2.9.2 en hourly 1 Putting XSL and PHP to work http://www.dotvoid.com/2002/08/putting-xsl-and-php-to-work/ http://www.dotvoid.com/2002/08/putting-xsl-and-php-to-work/#comments Wed, 14 Aug 2002 22:46:42 +0000 Danne http://www.commodi.com/?p=24

We all know PHP is great for web development. We also know that XSLT is a great way of formatting, or tranforming, XML data. Combine these technologies and we have a very powerful toolkit in developing large scale web sites where content is clearly separated from logic and presentation. This article will show you how to put the revamped XSLT API in PHP 4.1 to good use.

Introduction

The xslt api in php changed quite a bit in version 4.1. One of the major reasons is to make the xslt extension more loosely tied to the actual XSLT processor used. Still only Sablotron from Ginger Alliance is supported but plans are to support other libraries such as Xalan or libxslt at a later stage.

Among the more notable changes are the removal of the functions xslt_run() and xslt_output_begintransform(). When running configure you should now use the options –enable-xslt –with-xslt-sablot instead of the old option –with-sablot. If you use Sablotron with javascript-support you also need to specify –with-sablot-js. This last option is common to overlook.

A warning might be in place. This article is written on the assumption that you already know or at least have a basic understanding of both xslt and php.

Template and data

In most of the examples I will be using the xml and xslt below. Both are very simple and I will use a traditional example with books.

<?xml version='1.0'?>
<library>
  <book>
      <title>Lord of the Rings</title>
      <author>Tolkien</author>
      <description>A nice little tale about hobbits</description>
    </book>
    <book>
      <title>Soldier of the Mist</title>
      <author>Wolfe</author>
      <description>Sad story about a soldiers memory loss</description>
  </book>
</library>
<?xml version='1.0'?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:template match="/">
  <html>
  <head><title>Booklist</title></head>
  <body>
  <xsl:apply-templates />
  </body>
  </html>
</xsl:template>

<xsl:template match="library">
  <xsl:apply-templates />
</xsl:template>

<xsl:template match="book">
  <p>
  <xsl:apply-templates />
  </p>
</xsl:template>

<xsl:template match="title">
  <b><xsl:value-of select="." /></b><br />
</xsl:template>

<xsl:template match="author">
  <i><xsl:value-of select="." /></i><br />
</xsl:template>

<xsl:template match="description">
  <b><xsl:value-of select="." /></b><br />
</xsl:template>

</xsl:stylesheet>

Using static files

Lets assume that the examples above can be found in the two files mylibrary.xml and libraryhtml.xsl. To publish the xml in html format is then very straightforward. Remember to give the full path names to the xml and xsl files. (Because of the php-bug Bug #16228 XSLT file path issues\” some might need to prefix the file path with file://)

<?php
   $xp = xslt_create();
   $result = xslt_process($xp, 'mylibrary.xml', 'libraryhtml.xsl');
   echo $result;
   xslt_free($xp);
?>

That is it. Very simple. First we use the xslt_create() function to obtain a resource handle to a xslt processor. This resource handle must be given as the first parameter to all xslt api functions. The function xslt_process() takes the resource handle and the two file names as parameters and stores the result of the transformation in the variable $result. In this case we just echo the result to the client. The last thing we do is to clean up after ourselves by freeing the xslt processor using xslt_free().

If we wanted to, xslt_process could write the result into a file instead. It’s as easy as adding a fourth parameter with a filename.

<?php
   $xp = xslt_create();
   xslt_process($xp, 'mylibrary.xml', 'libraryhtml.xsl', 'library.html');
   xslt_free($xp);
?>

A more dynamic approach

Often the xml is generated dynamically in some way. Whether it comes from a database or some other data source we need to to feed xslt_process() with xml data stored in a variable.

<?php
$xml = get_xml_from_datasource();

$arguments = array(
  '/_xml' => $xml
);

$xp = xslt_create();
$result = xslt_process($xp, 'arg:/_xml', 'libraryhtml.xsl',
                       NULL, $arguments);
echo $result;
xslt_free($xp);
?>

Again not very complicated. We create an associative array for storing arguments to xslt_process(). You will see why an array is needed below. We tell xslt_process() that we want it too read the xml from the arguments by giving it ‘arg:/_xml’ as a second parameter instead of a filename of a xml file. The arguments array is given as a fifth parameter. The fourth, file result parameter, must then be set to NULL indicating that we want the result stored in a variable.

The arguments must be supplied in an array. Apart from the xml we could also supply the xslt as an argument instead of a file. This could be useful if we have a template library stored in database as might be the case in Content Management System.

<?php
$xml = get_xml_from_datasource();
$xsl = get_xsl_from_templatelibrary();

$arguments = array(
  '/_xml' => $xml,
  '/_xsl' => $xsl
);

$xp = xslt_create();
$result = xslt_process($xp, 'arg:/_xml', 'arg:/_xsl', NULL, $arguments);
echo $result;
xslt_free($xp);
?>

This is all nice and dandy but hardly enough. In more complex environments you would want proper error handling. When developing and debugging it could be useful to log results of transformations to a log file. Sometimes sending parameters to the xsl template might be needed. Luckily we can do all that.

Error handling and logging

When calling xslt_process() it always returns a result. Whether we want the result of the transformation in a variable or not the return value evaluates to false if something went wrong. If it is false we can use the functions xslt_errno() and xslt_error() to find out what went wrong. If something goes wrong warnings will often be echoed to the client. We should always avoid that by prepending @ to the function call.

In a live system it would not be very nice to just blurt out an error code with a cryptic error message. More proper would be to automatically send an alert via email to an administrator and redirect the user to an error page begging for his forgiveness. We do want our visitors to come back now, don’t we?

<?php
$xp = xslt_create();

$result = @xslt_process($xp, 'library.xml', 'libraryhtml.xsl');
if (!$result)
{
    $msg = "An error occurred on line " .__LINE__;
    $msg .= " in " .$_SERVER['PHP_SELF'] ."\n";
    $msg .= "Error no: " .xslt_errno($xp) ."\n";
    $msg .= "Error   : " .xslt_error($xp) ."\n";
    send_message_to_admin($msg);
    header('Location: http://www.dotvoid.com/error.php');
    exit(0);
}

echo $result;
xslt_free($xp);
?>

Even better would be to wrap this functionality in one function and make all errors go there. Easier to handle and cleaner code. We do that using the function xslt_set_error_handler(). The parameter $fields contain all the information we need.

<?php
function handle_xslt_error($xp, $errorno, $level, $fields)
{
    // Handle errors
    header('Location: http://www.dotvoid.com/error.php');
    exit(0);
}

$xp = xslt_create();
xslt_set_error_handler($xp, "handle_xslt_error");

$result = @xslt_process($xp, 'library.xml', 'libraryhtml.xsl');

echo $result;
xslt_free($xp);
?>

If we want to read the information stored in the $fields parameter we can use the following code.

$msg = '';
if(is_array($fields))
{
   while(list($key, $value) = each($fields))
    {
      $msg .= "$key => $value<br>\n";
    }
   echo $msg;
}

The function xslt_set_error_handler() makes it easy to put a custom error handler in an external library file. It keeps the code clean, robust and easier to maintain. But when we are developing or debugging an application we want to know what is going on all the time. Not only when errors occur. We need logging.

<?php

$xp = xslt_create();
xslt_set_log($xp, true);
xslt_set_log($xp, 'debug.log');

$result = @xslt_process($xp, 'library.xml', 'libraryhtml.xsl');
echo $result;

xslt_free($xp);
?>

The function xslt_set_log either takes a boolean or a string for the filename of a logfile. When we turn the logging on we first call xslt_set_log() with true and then we give it the path to the logfile. So if we would like to we could turn logging off by giving the function false as the second parameter. The logging facility tells us what files (or dynamically generated xml/xsl) are used in the transformation and in how many milliseconds it took.

Sending parameters

Sending parameters to the xsl template is easy. It is often needed in more serious applications. For example when passing the name of the logged in user, what locale is going to be used or just about any dynamica data nuggets not included in the xml. In the example below we send the currentLocale to the xsl template. First we change the libraryhtml.xsl a bit. We add the xsl:param element using en-us as default.

<?xml version='1.0'?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:param name="locale">en-us</xsl:param>

<xsl:template match="/">
  <html>
  <head><title>Booklist</title></head>
  <body>
  <xsl:apply-templates />
  </body>
  </html>
</xsl:template>

<xsl:template match="library">
  <xsl:choose>
    <xsl:when test="$locale = 'sv'">
       You speak Swedish<br />
    </xsl:when>
    <xsl:otherwise>
       You speak American English<br />
    </xsl:otherwise>
  </xsl:choose>

  <xsl:apply-templates />
</xsl:template>

<xsl:template match="book">
  <p>
  <xsl:apply-templates />
  </p>
</xsl:template>

<xsl:template match="title">
  <b><xsl:value-of select="." /></b><br />
</xsl:template>

<xsl:template match="author">
  <i><xsl:value-of select="." /></i><br />
</xsl:template>

<xsl:template match="description">
  <b><xsl:value-of select="." /></b><br />
</xsl:template>

</xsl:stylesheet>

We add the last parameter to xslt_process() which is an array of key-value pairs stored in an associative array. A small problem is that xslt_process() will not accept a NULL instead of the optional fifth argument. Just give it an empty array and all will be fine.

<?php
$params = array('locale' => 'sv');
$xp = xslt_create();

$result = xslt_process($xp, 'mylibrary.xml', 'libraryhtml.xsl',
                       NULL, array(), $params);
echo $result;

xslt_free($xp);
?>

Conclusion

The concept presented above in all its simplicity is suitable for even the largest projects. The logic to create and/or retrieve the data will be completely separated from the presentation layer. It would be easy to add code in the logic to detect the browser type and apply different xsl templates for wml or html.

PHP mixed with HTML is a bad choice when creating anything more complex than a very small web site. Some prefer to use FastTemplates or another template implementation in PHP, which might be good for some needs. However, both XHTML and WML are based on XML which makes XSLT an even more natural choice for the web. XSLT is rich in features and extremely powerful in transforming XML to other formats. Not to mention that XSLT is a standard.

]]> http://www.dotvoid.com/2002/08/putting-xsl-and-php-to-work/feed/ 0 Quick and dirty XSLT tutorial http://www.dotvoid.com/2002/08/quick-and-dirty-xslt-tutorial/ http://www.dotvoid.com/2002/08/quick-and-dirty-xslt-tutorial/#comments Fri, 02 Aug 2002 13:02:25 +0000 Danne http://www.commodi.com/?p=18

XSLT is a powerful way of getting data from an XML document into a HTML document, altough it is not the only use for it. This article will show you how to get started with XSLT using a simple example while explaining the basics of the language.

Explanation

The stylesheet above introduces many important concepts of XSLT and how it works. The first line is the XML declaration. The <xsl:stylesheet ...> and </xsl:stylesheet> marks the start and end of the stylesheet. Other than that there is for now no need to explain that further. Another thing that is important is that XSLT is XML. And thus needs to be wellformed. This means that all tags, whether HTML or XSLT, needs to be closed. This is done either by a start and end tag like <li>item</li> or by using a short form like <xsl:value-of select="title"/> (Note the forward slash in the end).

The stylesheet contain three templates, or rules. These match certain patterns like “item” or “news”. The first rule is special. It matches the root in the XML document. You can look at it as you are traversing a tree of nodes.

 root node (/)
     '- news
         +- source
         +- item
         |   +- title
         |   '- link
         '- item
             +- title
             '- link

The XSLT tag <xsl:apply-templates/> tell the processor to look at the XML and the template rules to find matches. So in the root node above we have <xsl:apply-templates select="news"/>. That tell the processor to look for news elements in the XML document.

Getting the information Four different ways of displaying information from the XML is used above. The normal way of getting the value of an XML tag is to use <xsl:value-of select="xml-node"/>. In the news template we use <xsl:value-of select="source"/> to get the value of “source” printed.

In the same template we also use a function to count the number of “item” found in the XML using the function count(). There are many such functions available in XSLT, for formatting, sorting, etc.

In the item template we want to create an html link using the value of the XML tag “link”. Since we cannot use <xsl:value-of ../> in html attributes, in this case HREF, we need to enclose the name of the node we want in curly braces {} and enter that as the value of HREF.

Last we want the value of the date. Date is an attribute of the XML tag “item”. To select the value of an attribute in the XML you put a @ in front of the name.

If you look at the tree above and think about the templates. I have used only the simple names of nodes to get their values. Since the XML really is a tree, like a directory structure, you can write full paths directly. Names are separated by forward slash. If you in the root node wanted the value of the XML tag “source” you could write the template like below.

<xsl:template match="/">
  <html>
  <head>
    <title>My news</title>
  </head>

  <body bgcolor="#ffffff">
    <xsl:value-of select="news/source"/>.
    <xsl:apply-templates select="news"/>
  </body>
  </html>
</xsl:template>

What is XSLT

Although people often only say XSL they usually refer to XSLT in conjunction with XPath. This tutorial won’t go into the details of these matters. Instead I will show you by example how to get started with XSLT to produce your HTML documents.

XSLT, however, stands for Extensible Stylesheet Language Transformation which was standardized by W3C in 1999. XSLT is a programming language and a stylesheet written in XSLT allow you to transform XML data into HTML or another text based format. Another way of looking at XSLT is that it is a way of extracting the information from XML data.

It is different than conventional languages in that XSLT is a rule driven language. You create template rules that match a certain pattern in XML data that is processed. Within the templates you define what output should be the result of the XML element.

A small example

Let us start with the XML document containing information and how we want that information displayed in a html document. Here is an XML document, more specifically a small list of news items.


<?xml version="1.0"?>
<news>
  <source>dotvoid.com</source>
  <item type="technology" date="20010323">
    <title>New tutorial</title>
    <link>http://www.dotvoid.com</link>
  </item>
  <item type="economy" date="20010322">
    <title>Nasdaq Hausse</title>
    <link>http://no.way.void</link>
  </item>
</news>

So we have a few news items which we now want to see nicely formatted on a web page. Lets begin with creating the end result of what we want. A simple but nicely formatted list of links to the news source.

<html>
  <head>
    <title>My news</title>
  </head>

  <body bgcolor="#ffffff">
    2 news items from dotvoid.com:

    <ul>
    <li><a HREF="http://www.dotvoid.com">New tutorial</a>
        (20010323)</li>
    <li><a HREF="http://no.way.void">Nasdaq Hausse</a>
        (20010333)</li>
    </ul>
  </body>
</html>

Creating the XSLT

The XSLT to create the web page above will then lool like this.

<?xml version="1.0"?>
<xsl:stylesheet
 xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     version="1.0">

<xsl:template match="/">
  <html>
  <head>
    <title>My news</title>
  </head>

  <body bgcolor="#ffffff">
    <xsl:apply-templates select="news"/>
  </body>
  </html>
</xsl:template>

<xsl:template match="news">
  <xsl:value-of select="count(item)"/>
  news items from
  <xsl:value-of select="source"/>:

  <ul>
     <xsl:apply-templates select="item"/>
  </ul>
</xsl:template>

<xsl:template match="item">
  <li>
    <a href="{link}"><xsl:value-of select="title"/></a>
    (<xsl:value-of select="@date"/>)
  </li>
</xsl:template>
</xsl:stylesheet>

How to run the examples

There are many, both free and commercial, XSLT processors available. I mostly use Sablotron from Ginger Alliance. Mainly because that is the one used in the PHP scripting language. It comes with a simple command line interface and is available for Linux, NT/2000, Solaris along with a few more unices. You can read more about it and download it at www.gingerall.com.

To test the examples above you save the XSL and XML into two files. For example news.xml and mypage.xsl. Then run it using

sabcmd mypage.xsl news.xml

Rounding off

I hope this is a good starter on how you can use XSLT and XML. XSLT can at an easy way of separating content from design. It can also be utilized in building complex systems that produce content for a multitude of devices such as mobile phones and PDA’s. Using XML and XSLT you produce content once and apply different stylesheets for different devices.

If you want to ask questions or discuss this article do so in XML/XSLT forum here on dotvoid.

]]> http://www.dotvoid.com/2002/08/quick-and-dirty-xslt-tutorial/feed/ 0