<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.10 $ -->
<refentry xml:id='function.xslt-set-sax-handlers' xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>xslt_set_sax_handlers</refname>
  <refpurpose>Set the SAX handlers to be called when the XML document gets processed</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>void</type><methodname>xslt_set_sax_handlers</methodname>
   <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
   <methodparam><type>array</type><parameter>handlers</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>xslt_set_sax_handlers</function> registers the SAX
   <parameter>handlers</parameter> for the document, given a XSLT
   <parameter>processor</parameter> resource.
  </para>
  <para>
   Using <function>xslt_set_sax_handlers</function> doesn't look very different than
   running a SAX parser like <function>xml_parse</function> on the result of an
   <function>xslt_process</function> transformation.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>processor</parameter></term>
     <listitem>
      <para>
       The XSLT processor link identifier, created with
       <function>xslt_create</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>handlers</parameter></term>
     <listitem>
      <para>
       <parameter>handlers</parameter> should be an array in the following format:
        <informalexample>
        <programlisting role="php">
<![CDATA[
<?php

$handlers = array(

  "document" => array(
    "start_doc",
    "end_doc"),

  "element"  => array(
    "start_element",
    "end_element"),

  "namespace" => array(
    "start_namespace",
    "end_namespace"),

  "comment"   => "comment",

  "pi"        => "pi",

  "character" => "characters"

);
?>
]]>
        </programlisting>
       </informalexample>
       Where the functions follow the syntax described for the scheme handler
       functions.
      </para>
      <note>
       <para>
        The given array does not need to contain all of the different sax
        handler elements (although it can), but it only needs to conform to
        "handler" => "function" format described above.
       </para>
      </note>
      <para>
       Each of the individual SAX handler functions are in the format below:
       <itemizedlist>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>start_doc</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>end_doc</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>start_element</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
          <methodparam><type>string</type><parameter>name</parameter></methodparam>
          <methodparam><type>array</type><parameter>attributes</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>end_element</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
          <methodparam><type>string</type><parameter>name</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>start_namespace</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
          <methodparam><type>string</type><parameter>prefix</parameter></methodparam>
          <methodparam><type>string</type><parameter>uri</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>end_namespace</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
          <methodparam><type>string</type><parameter>prefix</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>comment</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
          <methodparam><type>string</type><parameter>contents</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>pi</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
          <methodparam><type>string</type><parameter>target</parameter></methodparam>
          <methodparam><type>string</type><parameter>contents</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
        <listitem>
         <para>
         <methodsynopsis>
          <methodname><replaceable>characters</replaceable></methodname>
          <methodparam><type>resource</type><parameter>processor</parameter></methodparam>
          <methodparam><type>string</type><parameter>contents</parameter></methodparam>
         </methodsynopsis>
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
 </refsect1>

 
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>xslt_set_sax_handlers</function> Example</title>
   <programlisting role="php">
<![CDATA[
<?php
// From ohlesbeauxjours at yahoo dot fr
// Here's a simple example that applies strtoupper() on
// the content of every <auteur> tag and then displays the
// resulting XML tree:

$xml='<?xml version="1.0"?>
<books>
 <book>
  <title>Mme Bovary</title>
  <author>Gustave Flaubert</author>
 </book>
 <book>
  <title>Mrs Dalloway</title>
  <author>Virginia Woolf</author>
 </book>
</books>';

$xsl='<?xml version="1.0"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="html" encoding="ISO-8859-1" indent="no" omit-xml-declaration="yes"/>
<xsl:template match="/">
 <xsl:for-each select="books/book">
  <livre>
   <auteur><xsl:value-of select="author/text()"/></auteur>
  </livre>
 </xsl:for-each>
</xsl:template>
</xsl:stylesheet>';

// Handlers :
function start_document()
{
  // start reading the document
}

function end_document()
{
  // end reading the document
}

function start_element($parser, $name, $attributes)
{
  global $result,$tag;
  $result .= "<". $name . ">";
  $tag = $name;
}

function end_element($parser, $name)
{
  global $result;
  $result .= "</" . $name . ">";
}

function characters($parser, $data)
{
  global $result,$tag;
  if ($tag == "auteur" ) {
    $data = strtoupper($data);
  }
  $result .= $data;
}

// Transformation :
$xh = xslt_create();
$handlers = array("document" => array("start_document","end_document"),
   "element" => array("start_element","end_element"),
   "character" => "characters");

xslt_set_sax_handlers($xh, $handlers);
xslt_process($xh, 'arg:/_xml', 'arg:/_xsl', NULL, array("/_xml"=>$xml, "/_xsl"=>$xsl));
xslt_free($xh);
?>
]]>
   </programlisting>
  </example>
  <para>
   You can also use <function>xslt_set_object</function> if you want to
   implement your handlers in an object.
  </para>
  <example>
   <title>Object oriented handler</title>
   <programlisting role="php">
<![CDATA[
<?php
// This is the object oriented version of the previous example
class data_sax_handler {

  var $buffer, $tag, $attrs;

  var $_xh;

  function data_sax_handler($xml, $xsl)
  {
      // our xslt resource
      $this->_xh = xslt_create();

      xslt_set_object($this->_xs, $this);

      // configure sax handlers
      $handlers = array(
        "document" => array('start_document', 'end_document'),
        "element" => array('start_element', 'end_element'),
        "character" => 'characters'
      );

      xslt_set_sax_handlers($this->_xh, $handlers);

      xslt_process($this->_xh, 'arg:/_xml', 'arg:/_xsl', NULL, array("/_xml"=>$xml, "/_xsl"=>$xsl));
      xslt_free($this->_xh);


  }

  function start_document()
  {
        // start reading the document
  }

  function end_document() {
        // complete reading the document
  }

  function start_element($parser, $name, $attributes) {
        $this->tag = $name;
        $this->buffer .= "<" . $name . ">";
        $this->attrs = $attributes;
  }

  function end_element($parser, $name)
  {
        $this->tag = '';
        $this->buffer .= "</" . $name . ">";
  }

  function characters($parser, $data)
  {
    if ($this->tag == 'auteur') {
          $data = strtoupper($data);
    }
    $this->buffer .= $data;
  }

  function get_buffer() {
    return $this->buffer;
  }

}

$exec = new data_sax_handler($xml, $xsl);

?>
]]>
   </programlisting>
   <para>
    Both examples will output:
   </para>
   <screen role="xml">
<![CDATA[
<livre>
   <auteur>GUSTAVE FLAUBERT</auteur>
</livre>
<livre>
   <auteur>VIRGINIA WOOLF</auteur>
</livre>
]]>
   </screen>
  </example>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->