<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
  <header>
    <title>Instructions for the Xalan extension</title>
    <authors>
      <person id="jmaerki" name="Jeremias Märki" email="jmaerki@users.sourceforge.net"/>
    </authors>
  </header>
  <body>
    <section>
      <title>Introduction</title>
      <p>
        This page describes how to generate barcodes in 
        <jump href="ext:svg">SVG format</jump> within an XSLT stylesheet that is 
        processed with <fork href="ext:xalan">Apache Xalan-J</fork>.
      </p>
    </section>
    <section>
      <title>Using the barcode extension for Apache Xalan</title>
      <p>This package contains an extension for <jump href="ext:xalan">Apache Xalan</jump> for 
        generating barcodes in SVG format.
      </p>
      <p>To make to barcode extension available in your XSLT stylesheets, do the following:</p>
      <ul>
        <li>Add <code>barcode4j.jar</code> to the classpath.</li>
        <li>Add the following namespace declaration to the root element of your XSLT stylesheet: 
          <strong><code>xmlns:barcode="org.krysalis.barcode4j.xalan.BarcodeExt"</code></strong>
        </li>
        <li>Add the barcode namespace prefix to the extension element prefixes:
          <strong><code>extension-element-prefixes="barcode"</code></strong>
        </li>
      </ul>
      <p>Here's an example:</p>
      <source><![CDATA[
<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
    xmlns:fo="http://www.w3.org/1999/XSL/Format" 
    xmlns:barcode="org.krysalis.barcode4j.xalan.BarcodeExt" 
    extension-element-prefixes="barcode">]]></source>
    </section>
    <section id="ext-func">
      <title>Using the "generate" function</title>
      <p>To generate a barcode use the <strong><code>barcode:generate(NodeList, String)</code></strong> function:</p>
      <ol>
        <li>NodeList: the barcode configuration (See example below and the <link href="barcode-xml.html">Barcode XML format</link>).</li>
        <li>String: the message to be encoded</li>
      </ol>
      <p>Here's an example:</p>
      <source><![CDATA[
  <fo:block>
    <fo:instream-foreign-object>
      <xsl:variable name="barcode-cfg">
        <barcode>
          <code128>
            <height>8mm</height>
          </code128>
        </barcode>
      </xsl:variable>
      <xsl:copy-of select="barcode:generate($barcode-cfg, '0123456789')"/>
    </fo:instream-foreign-object>
  </fo:block>]]></source>
    </section>
    <section id="ext-elem">
      <title>Using the barcode extension element</title>
      <warning>    
        Xalan has a <fork href="http://issues.apache.org/jira/browse/XALANJ-1706">bug</fork>
        that causes a NullPointerException in FOP. Please use the extension function above until 
        a new Xalan version is release. The bug is fixed in the codebase but no release has
        happened since.
      </warning>
      <p>
        To generate a barcode, simply put a barcode element in the namespace declared above 
        into your stylesheet. The barcode element currently takes one attribute: 
        <strong>message</strong>.
      </p>
      <p>Here's an example:</p>
      <source><![CDATA[
  <fo:block>
    <fo:instream-foreign-object>
      <barcode:barcode message="0123456789" orientation="90">
        <barcode:code128>
          <barcode:height>8mm</barcode:height>
        </barcode:code128>
      </barcode:barcode>
    </fo:instream-foreign-object>
  </fo:block>]]></source>
      <p>
        The XML syntax used within the barcode element is the <link href="barcode-xml.html">Barcode XML</link>.
      </p>
      <p>
        The attribute "orientation" specifies the orientation of the barcode in degrees. The 
        attribute is optional and if set must be one of the following values:
        0, 90, -90, 180, -180, 270, -270.
      </p>
    </section>
  </body>
</document>
