Yawd website


Migrate to Keystone 5

If you want to upgrade your old Keystone TKL digital library and exploit the fast performance that Keystone 5 offers, here's what you most likely need to change. Please note that since PHP5 differs significantly over PHP4, you should also modify your custom PHP code, especially if it involves XML/DOM manipulation to work with PHP5.

Handler calls

Keystone 5 provides two concrete mechanisms for calling php handlers (php code snippets):

a) Traditional calls: tkl-handler://path/?args. This is still available for backwards-compatibility reasons. However, old handler calls must be slightly transformed so that the call string is a valid uri path. To achieve this, one might need the 'urlencode' php function. E.g.:


Please note that for handler that take no argument (e.g. 'tkl-user'), a random keyword must be appended to the string so that the call is a valid URI


b) Php functions: Now that php5 uses libsxlt we are able to directly call php functions using the 'php' namespace and the 'function' or 'functionString' methods. E.g:
namespace declaration:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    exclude-result-prefixes="php exsl" 

function call - arguments processed as strings:

 select="php:functionString('neo_hier_del', $hier_delete)/neo-hier-del" 

function call - no arguments or arguments processed as nodes:


Handler definitions

Keystone 5 will also load any user-defined php functions declared inside a 'php-handlers' directory that should be placed under your portal's original 'lib' handler directory. Please note that your file should have a '.php' extension for Keystone 5 to load it. Consider the following file structure:

              |--- dom_tools.php

Keystone 5 will load the neo-zebra folder as it contains an old-style handler. It will then register all php functions included in the 'dom_tools.php' and 'other_tools.php' files but not those in 'helpers.inc'.


Custom php handlers can use any number of arguments, and no naming scheme is required anymore. If you need your PHP function to return xml that the XSL stylesheet will be able to parse use DOMDocument's loadXML method.

//example handler function
function tkl_date() {
        $final_xml = "<date>Test date.</date>";
    $dom = new DOMDocument();
    return $dom;

XSL variables

Libxslt parses XSLT stylesheets in a slightly different way than Sablotron used to do. One of these parsers' incompatibilities is the way they process the xsl:variable. When the variable's content is defined between the xsl:variable starting and closing tags and not provided by the select attribute, libxslt processes the variable as string. For example, the following variable can be processed as xml in Sablotron, while in Libxslt it is a plain string.

<xsl:variable name="user">
<name>Pantelis Petridis</name>

In sablotron we could do something like this:

<xsl:value-of select="$user/profile/name"/>

Now with Libxslt this is not possible since $user is evaluated as string. However there is a workaround using the exslt.org's node-set function. First, make sure the exsl namespace is declared.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 

Then modify the 'user' variable from the example above as follows:

<xsl:variable name="user-string">
<name>Pantelis Petridis</name>
<xsl:variable name="user" select="exsl:node-set($user-string)" />

Customized xform

Import handler

If you have your own customized xform, to call the xform handler use the following:

<xsl:import href="xform-handler://xsl"/>

instead of <xsl:import href="xform-xsl:"/> that you probably used untill now

Portal root

To access your portal root inside your customized xform stylesheet - i.e. to add extra js or css:

<xsl:param name="portal_root"/>

Extra media

To add extra css, you must define the 'extra-css' template. To add extra js, define the 'extra-javascript' template. To override default xform media, use 'load-css' or 'load-javascript'.


Published: Aug. 5, 2011
Word Count: 679

Follows Up On

Comments powered by Disqus