| <?xml version="1.0" standalone="no"?> |
| <!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd"> |
| <!-- |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| --> |
| <s1 title="&xslt4c; Basic usage patterns"> |
| <ul> |
| <li><link anchor="intro">Introduction</link></li> |
| <li><link anchor="xalantransformer">Basic usage pattern with the XalanTransformer C++ API</link></li> |
| <li><link anchor="stylepi">Using a stylesheet processing instruction</link></li> |
| <li><link anchor="params">Setting stylesheet parameters</link></li> |
| <li><link anchor="incremental">Processing output incrementally</link></li> |
| <li><link anchor="compiled">Performing a series of transformations</link></li> |
| <li><link anchor="dom">Working with DOM input and output</link></li> |
| <li><link anchor="xercesdomwrapperparsedsource">Using a Xerces DOM as the source for a Xalan transformation</link></li> |
| <li><link anchor="xpath">Working with XPath expressions</link></li> |
| <li><link anchor="tracelistener">Using the TraceListener</link></li> |
| <li><link anchor="icu">Using the International Components for Unicode (ICU)</link></li> |
| <li><link anchor="capi">Basic usage pattern with the XalanTransformer C API</link></li> |
| <li><link anchor="cvar">Variations with the XalanTransformer C API</link></li> |
| <li>See also: <link idref="extensions">Creating and using extension functions</link></li> |
| </ul> |
| |
| <anchor name="intro"/> |
| <s2 title="Introduction"> |
| <p>To perform a transformation, use one of the <jump href="apiDocs/classXalanTransformer.html">XalanTransformer |
| </jump> transform() methods. The transformation requires an XML source document and an XSL stylesheet. Both of these objects |
| may be represented by instances of <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource </jump>. You can construct |
| an XSLTInputSource with a string (the system ID for a file or URI), an input stream, or a DOM.</p> |
| <p>If you are using an XSL stylesheet to perform a series of transformations, you can improve performance by calling transform() |
| with a compiled stylesheet, an instance of <jump href="apiDocs/classXalanCompiledStylesheet.html">XalanCompiledStylesheet</jump>. |
| If you are transforming an XML source more than once, you should call transform() with a parsed XML source, an instance of |
| <jump href="apiDocs/classXalanParsedSource.html">XalanParsedSource</jump>. See <link anchor="compiled">Performing a series of |
| transformations</link>.</p> |
| <p>If you XML source document contains a stylesheet Processing Instruction (PI), you do not need to include a stylesheet object |
| when you call transform().</p> |
| <p>The transformation output is represented by an <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump>, which |
| you can set up to refer to an output stream, the system ID for a file or URI, or a Formatter for one of the various styles of |
| DOM output.</p> |
| <p>For detailed API documentation, see <jump href="apiDocs/index.html">&xslt4c; API</jump>. For an overview of the command-line |
| utility, see <link idref="commandline">Command-Line Utility</link>.</p> |
| |
| </s2> |
| <anchor name="xalantransformer"/> |
| <s2 title="Basic usage patten with the XalanTransformer C++ API"> |
| <p>Using <jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> and the C++ API, you can perform one or more |
| transformations as described in the following steps.</p> |
| <note>For a working sample that illustrates these steps, see the <link idref="samples" anchor="xalantransform">XalanTransform</link> |
| sample.</note> |
| |
| <s3 title="1. Include the required header files."> |
| <p>Always start with xalanc/Include/PlatformDefinitions.hpp, the &xslt4c; base header file. Also include xercesc/util/PlatformUtils.hpp, |
| xalanc/XalanTransformer/XalanTransformer.hpp, and any other header files your particular application requires.</p> |
| <source> |
| #include <xalanc/Include/PlatformDefinitions.hpp> |
| #include <xercesc/util/PlatformUtils.hpp> |
| #include <xalanc/XalanTransformer/XalanTransformer.hpp> |
| ... |
| </source> |
| </s3> |
| |
| <s3 title="2. Define namespaces"> |
| <p>As of version 1.5, &xslt4c; now uses C++ namespaces for those platforms which support them. A number of macros are provided to |
| make using the &xslt4c; (and &xml4c;) namespaces easier.</p> |
| <p>In the following example, the <em>XALAN_USING_XERCES</em> and <em>XALAN_USING_XALAN</em> macros are used to declare that the |
| program is using <em>XMLPlatformUtils</em> and <em>XalanTransformer</em> from the &xml4c; and &xslt4c; namespaces respectively.</p> |
| <source> |
| XALAN_USING_XERCES(XMLPlatformUtils) |
| XALAN_USING_XALAN(XalanTransformer) |
| </source> |
| |
| <p>These macros can be used immediately after the included header files (for global applicability in a given source file) or within |
| functions and methods for local applicability.</p> |
| <note>Whilst you can use the standard C++ namespace syntax directly, the &xml4c; and &xslt4c; namespaces are linked to the version |
| number. For example, the Xalan namespace is currently <em>xalanc_1_11</em>. The macros will automatically take care of this |
| when code is re-compiled against a new version of the libraries. Using the namespaces directly will require each namespace |
| related statement be updated by hand.</note> |
| </s3> |
| |
| <s3 title="3. Initialize Xerces and Xalan."> |
| <p>Use the static initializers to initialize the &xslt4c; and &xml4c; platforms. You must initialize &xml4c; once per process. You |
| may initialize and terminate &xslt4c; multiple times, but this is not recommended: it is inefficient and is not thread safe.</p> |
| <source> |
| XMLPlatformUtils::Initialize(); |
| XalanTransformer::initialize(); |
| </source> |
| </s3> |
| |
| <s3 title="4. Create a XalanTransformer."> |
| <source> |
| XalanTransformer theXalanTransformer; |
| </source> |
| </s3> |
| |
| <s3 title="5. Perform each transformation."> |
| <p>You can explicitly instantiate <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource</jump> objects for the XML |
| source document and XSL stylesheet, and an <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> object |
| for the output, and then call <jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> transform() with those |
| objects as parameters. For example:</p> |
| <source> |
| XSLTInputSource xmlIn("foo.xml"); |
| XSLTInputSource xslIn("foo.xsl"); |
| XSLTResultTarget xmlOut("foo-out.xml"); |
| int theResult = |
| theXalanTransformer.transform(xmlIn,xslIn,xmlOut) |
| </source> |
| |
| <p>Alternatively, you can call transform() with the strings (system identifiers), streams, and/or DOMs that the compiler needs |
| to implicitly construct the <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource</jump> and |
| <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> objects. For example:</p> |
| <source> |
| const char* xmlIn = "foo.xml"; |
| const char* xslIn = "foo.xsl"; |
| const char* xmlOut = "foo-out.xml"; |
| int theResult = |
| theXalanTransformer.transform(xmlIn,xslIn,xmlOut) |
| </source> |
| <p>Keep in mind that <jump href="apiDocs/classXSLTInputSource.html">XSLTInputSource</jump> and |
| <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> provide a variety of single-argument constructors that |
| you can use in this manner:</p> |
| <ul> |
| <li><code>XSLTInputSource(const char* systemID);</code></li> |
| <li><code>XSLTInputSource(const XMLCh* systemID);//Unicode chars</code></li> |
| <li><code>XSLTInputSource(istream* stream);</code></li> |
| <li><code>XSLTInputSource(XalanNode* node);</code><br/><br/></li> |
| <li><code>XSLTResultTarget(char* fileName);</code></li> |
| <li><code>XSLTResultTarget(XalanDOMString& fileName);</code></li> |
| <li><code>XSLTResultTarget(ostream* stream);</code></li> |
| <li><code>XSLTResultTarget(ostream& stream);</code></li> |
| <li><code>XSLTResultTarget(Writer* characterStream);</code></li> |
| <li><code>XSLTResultTarget(XalanDocument* document);</code></li> |
| <li><code>XSLTResultTarget(XalanDocumentFragment* documentFragment);</code></li> |
| <li><code>XSLTResultTarget(XalanElement* element);</code></li> |
| <li><code>XSLTResultTarget(FormatterListener& flistener);</code></li> |
| </ul> |
| <note>Each transform() method returns an integer code, 0 for success. If an error occurs, you can use the getLastError() method |
| to return a pointer to the error message.</note> |
| </s3> |
| |
| <s3 title="6. Shut down Xalan."> |
| <p>When you shut down Xalan, you may also want to shut down Xerces and ICU support (if enabled). Keep the following considerations |
| in mind:</p> |
| <ul> |
| <li>Once you have shut down Xerces, you can no longer make Xalan or Xerces calls in the current process.<br/><br/></li> |
| <li>Shut down ICU support if you have enabled it (see <link anchor="icusupport">enabling ICU support</link>) and if the |
| application is exiting or no longer requires the ICU. The <code>XMLPlatformUtils::Terminate()</code> call does nothing |
| if ICU support has not been enabled.</li> |
| <li>Ensure that there are no &xslt4c; or &xml4c; objects extant at the point of termination. Any deletion of objects after |
| termination could cause errors.</li> |
| </ul> |
| <p>Use the static terminators.</p> |
| <source> |
| XalanTransformer::terminate(); |
| XMLPlatformUtils::Terminate(); |
| XalanTransformer::ICUCleanUp(); |
| </source> |
| </s3> |
| |
| </s2> |
| <anchor name="stylepi"/> |
| <s2 title="Using a stylesheet processing instruction"> |
| <p>If you want to use the stylesheet referred to by a stylesheet processing instruction in the XML document, simply call |
| transform() without the second XSLTInputSource argument. For example:</p> |
| <source> |
| // foo.xml contains a stylesheet PI |
| const char* xmlIn = "foo.xml"; |
| const char* xmlOut = "foo-out.xml"; |
| int theResult = |
| theXalanTransformer.transform(xmlIn,xmlOut) |
| </source> |
| </s2> |
| |
| <anchor name="params"/> |
| <s2 title="Setting Stylesheet Parameters"> |
| |
| <p>An XSL stylesheet can include parameters that are set at run time before a transformation takes place. Traditionally, a top-level parameter value is of text string type. The Xalan library now supports three types of top-level parameters that can be set. One is a text string parameter. Another is a number parameter of floating point type double. The third is a nodeset (XalanNode *) parameter, usually implemented as a parsed document.</p> |
| |
| <p>Any XObject that is created outside of the transformation can be associated with a top-level parameter. The XalanTransformer has an XObject factory whereby top-level parameters can be owned by the XalanTransformer object.</p> |
| |
| <p>To set a stylesheet parameter, use the |
| <jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> setStylesheetParam() method. The setStylesheetParam() method takes two arguments: the parameter name and the value. The value can be a string type, a number double type, an (XalanNode *) pointer to a nodeset or parsed document, or any XObjectPtr returned from an XObject factory.</p> |
| |
| <p>Top level parameters are sticky. Once set to an instance of an XalanTransformer object, they can be used for multiple transformations. The XalanTransformer reset() method prepares a transformer for a new transformation. Use the clearStylesheetParams() method to release the top-level stylesheet parameters.</p> |
| |
| <p>The Xalan command line utility currently supports only a text string value for a top-level stylesheet parameter. The single quotes are required to identify a text string value.</p> |
| |
| <p><code>Xalan -p param1 "'string expression'"foo.xml foo.xsl</code></p> |
| |
| <p>If the string expression includes spaces or other characters that the shell intercepts, first enclose the string in single quotes so Xalan-C++ interprets it as a string expression, and then enclose the resulting string in double quotes so the shell interprets it as a single argument.</p> |
| |
| <p>The <link idref="samples" anchor="usestylesheetparam">UseStylesheetParam</link> sample application supports all three types of top-level stylesheet parameters.</p> |
| |
| <p>The 'C' language interface XalanCAPI also supports the three types of top-level parameters. The sample program TestCAPIparms.c shows how to use top-level parameters with 'C' language programs.</p> |
| |
| <note>The Xalan command line utility should be revised to accommodate the number and nodeset types of top-level stylesheet parameters. Only text string values are currently supported.</note> |
| |
| <p>Top-level stylesheet parameters of nodeset type (XalanNode *) are useful for the merging of multiple XML documents.</p> |
| </s2> |
| |
| <anchor name="incremental"/> |
| <s2 title="Processing output incrementally"> |
| <p><jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> provides a transform() method that sends the output in blocks |
| to a callback function, which enables you to begin processing the output while the transformation is still in process:</p> |
| <source> |
| int |
| transform(const XSLTInputSource& xmlIn, |
| const XSLTInputSource& xslIn, |
| void* theOutputHandle, |
| XalanOutputHandlerType theOutputHandler, |
| XalanFlushHanderType theFlushHandler = 0); |
| </source> |
| <p>For an example, see <link idref="samples" anchor="xalantransformercallback">XalanTransformerCallback</link>.</p> |
| </s2> |
| |
| <anchor name="compiled"/> |
| <s2 title="Performing a series of transformations"> |
| <p>Before Xalan performs a standard transformation, it must parse the XML document and compile the XSL stylesheet into binary |
| representations. If you plan to use the same XML document or stylesheet in a series of transformations, you can improve performance |
| by parsing the XML document or compiling the stylesheet once and using the binary representation when you call transform().</p> |
| <p><jump href="apiDocs/classXalanTransformer.html">XalanTransformer</jump> includes methods for creating compiled stylesheets and |
| parsed XML documents: the compileStylesheet() method returns a pointer to a <jump href="apiDocs/classXalanCompiledStylesheet.html"> |
| XalanCompiledStylesheet</jump>; the parseSource() method returns a pointer to a <jump href="apiDocs/classXalanParsedSource.html"> |
| XalanParsedSource</jump>.</p> |
| <note>In the case of failure, both methods return 0.</note> |
| <p>Example using a XalanCompiledStylesheet to perform multiple transformations:</p> |
| <source> |
| XalanCompiledStylesheet* compiledStylesheet = 0; |
| compiledStylesheet = theXalanTransformer.compileStylesheet("foo.xsl"); |
| assert(compiledStylesheet!=0); |
| theXalanTransformer.transform("foo1.xml", *compiledStylesheet, "foo1.out."); |
| theXalanTransformer.transform("foo2.xml", *compiledStylesheet, "foo2.out"); |
| ... |
| </source> |
| <p>For a working sample, see the <link idref="samples" anchor="compilestylesheet">CompileStylesheet</link> sample.</p> |
| <p>Example using a XalanParsedSource for multiple transformations:</p> |
| <source> |
| XalanParsedSource* parsedXML = 0; |
| parsedXML = theXalanTransformer.parseSource("foo.xml"); |
| assert(parsedXML!=0); |
| theXalanTransformer.transform(*parsedXML, "foo1.xsl", "foo-xsl1.out"); |
| theXalanTransformer.transform(*parsedXML, "foo2.xsl", "foo-xsl2.out"); |
| ... |
| </source> |
| <p>For a sample that uses both a parsed XML source and a compiled stylesheet, see <link idref="samples" anchor="threadsafe">ThreadSafe |
| </link>.</p> |
| </s2> |
| |
| <anchor name="dom"/> |
| <s2 title="Working with DOM input and output"> |
| <p>You can set up an <jump href="apiDocs/classXSLTResultTarget.html">XSLTResultTarget</jump> to produce a DOM when you perform a |
| transformation. You can also use a DOM as input for a transformation.</p> |
| <p>The following code fragment illustrates the procedures for working with DOM output :</p> |
| <source> |
| |
| // Use the Xerces DOM parser to create a DOMDocument. |
| |
| #include <xercesc/dom/DOMDocument.hpp> |
| #include <xercesc/dom/DOMImplementation.hpp> |
| |
| #include <xalanc/XMLSupport/FormatterToXML.hpp> |
| #include <xalanc/XMLSupport/XalanTransformer.hpp> |
| |
| XALAN_USING_XERCES(DOMDocument) |
| XALAN_USING_XERCES(DOMImplementation) |
| |
| XALAN_USING_XALAN(FormatterToXML) |
| XALAN_USING_XALAN(XalanTransformer) |
| |
| |
| // If you want to produce DOM output, create an empty Xerces Document |
| // to contain the transformation output. |
| |
| DOMDocument * theDOM = |
| DOMImplementation::getImplementation()->createDocument(); |
| |
| // Now create a FormatterListener which can be used by the transformer |
| // to send each output node to the new Xerces document |
| |
| FormatterToXercesDOM theFormatter(theDOM); |
| |
| // Now do the transform as normal |
| XalanTransformer theXalanTransformer |
| int theResult = theXalanTransformer.transform( |
| "foo.xml", |
| "foo.xsl", |
| theFormatter); |
| ... |
| |
| // After you perform the transformation, the DOMDocument contains |
| // the output. |
| </source> |
| <note>You can also follow the same process but use a <em>FormatterToDeprecatedXercesDOM</em> if you require a DOM_Document |
| output. However this is discouraged, as support for the deprecated DOM may be removed in future releases of &xslt4c;</note> |
| <p>If you want to use a Xerces DOM object as input for a transformation without wrapping the DOM in a XercesParserLiaison, see |
| <link anchor="xercesdomwrapperparsedsource">passing in a Xerces DOM</link>.</p> |
| |
| <s3 title="Limitations"> |
| <p>Performance is much better when &xslt4c; uses native source tree handling rather than interacting with the Xerces DOMParser.</p> |
| <p>If you are using the deprecated DOM, the Xerces DOMParser by default, creates a DOM_XMLDecNode in the DOM tree to represent |
| the XML declaration. The Xalan bridge for the Xerces DOM does not support this non-standard node type. Accordingly, you must |
| call DOMParser::setToCreateXMLDeclTypeNode(false) <em>before</em> you parse the XML file. If not, the behavior is undefined, |
| and your application may crash.</p> |
| </s3> |
| |
| <anchor name="xercesdomwrapperparsedsource"/> |
| <s3 title="Passing in a Xerces DOM to a transformation"> |
| <p>You may want to use a Xerces DOM that was created without using the XalanTransformer class. As the following code snippet |
| illustrates, you can use <jump href="apiDocs/classXercesDOMWrapperParsedSource.html">XercesDOMWrapperParsedSource</jump> to |
| pass in a Xerces DOM as the source for an XSL transformation.</p> |
| <source> |
| #include <xercesc/parsers/DOMParser.hpp> |
| #include <xalanc/XalanTransformer/XercesDOMWrapperParsedSource.hpp> |
| |
| void parseWithXerces(XalanTransformer &xalan, |
| const XSLTInputSource &xmlInput, |
| const XalanCompiledStylesheet* styleSheet, |
| const XSLTResultTarget &output, |
| XMLFileReporter &logFile) |
| { |
| XercesDOMParser theParser; |
| |
| // Turn on validation and namespace support. |
| theParser.setDoValidation(true); |
| theParser.setDoNamespaces(true); |
| |
| // Parse the document |
| |
| theParser.parse(xmlInput); |
| DOMDocument *theDOM = theParser.getDocument(); |
| theDOM->normalize(); |
| |
| XercesDOMSupport theDOMSupport; |
| XercesParserLiaison theParserLiaison; |
| |
| // Use the DOM to create a XercesDOMWrapperParsedSource, |
| // which you can pass to the transform method. |
| try |
| { |
| const XercesDOMWrapperParsedSource parsedSource( |
| theDOM, |
| theParserLiaison, |
| theDOMSupport, |
| XalanDOMString(xmlInput.getSystemId())); |
| |
| xalan.transform(parsedSource, stylesheet, output); |
| |
| } |
| catch (....) |
| { |
| ... |
| } |
| } |
| </source> |
| </s3> |
| </s2> |
| |
| <anchor name="xpath"/> |
| <s2 title="Working with XPath expressions"> |
| <p>XSL stylesheets use XPath expressions to select nodes, specify conditions, and generate text for the result tree. XPath |
| provides an API that you can call directly. For example, you may want to select nodes programmatically and do your own |
| processing without a stylesheet. &xslt4c; provides an XPathEvaluator interface to simplify the process of executing XPath |
| expressions.</p> |
| <p>For an example that executes XPath expressions against XML source files, see <link idref="samples" anchor="simplexpathapi"> |
| SimpleXPathAPI</link> (takes advantage of the XPathEvaluator interface) and <link idref="samples" anchor="xpathwrapper"> |
| XPathWrapper</link>.</p> |
| </s2> |
| |
| <anchor name="tracelistener"/> |
| <s2 title="Using TraceListener"> |
| <p>TraceListener is a debugging abstract base class implemented by TraceListenerDefault. You can use TraceListener to trace |
| any combination of the following:</p> |
| <ul> |
| <li>Calls to templates</li> |
| <li>Calls to template children</li> |
| <li>Selection events</li> |
| <li>Result tree generation events</li> |
| </ul> |
| <p>To construct a TraceListener with TraceListenerDefault, you need a PrintWriter and a boolean for each of these four |
| tracing options. You can then use the XSLTEngimeImpl setTraceSelects and addTraceListener methods to add the TraceListener |
| to an XSLTProcessor. See the <link idref="samples" anchor="tracelisten">TraceListen</link> sample application.</p> |
| <p>The TraceListen uses TraceListenerDefault to write events to the screen.</p> |
| </s2> |
| |
| <anchor name="icu"/> |
| <s2 title="Using the ICU"> |
| <p>You can use the <resource-ref idref="icu"/> to extend support for encoding, number formatting, and sorting.</p> |
| <ul> |
| <li><em>Encoding</em> |
| <br/> &xml4c; and &xslt4c; use UTF-16 encoding to work with Unicode data. If you integrate the ICU with &xml4c;, both |
| &xml4c; and &xslt4c; use ICU support for input and output transcoding.<br/><br/></li> |
| <li><em>format-number()</em> |
| <br/>This XSLT function includes two or three arguments (the third is optional): number, format pattern, and decimal-format |
| name. &xslt4c; ignores the format pattern and optional decimal-format name. If you install ICU support for format-number(), |
| this function is fully supported with all its arguments.<br/><br/></li> |
| <li><em>xsl:sort</em> |
| <br/>If you install ICU support for xml:sort, &xslt4c; implements Unicode-style collation.</li> |
| </ul> |
| |
| <p>If you choose to build Xalan with ICU, you will need to rebuild Xerces with ICU as well.</p> |
| <p>To get the ICU:</p> |
| <ol> |
| <li>Download and unzip the <resource-ref idref="icu-download"/> from the IBM developerWorks open source zone.<br/><br/></li> |
| <li>Do an ICU build -- see the Windows NT or Unix build instructions in the build_instruct.html that accompanies the download.<br/> |
| <em>Important</em> For Windows, define the environment variable ICUROOT and then restart Visual C++ or Visual Studio .NET. |
| in order for the ICUROOT variable to take effect.<br/><br/></li> |
| </ol> |
| |
| <anchor name="icusupport"/> |
| <s3 title="Enabling ICU support for encoding"> |
| <p>If you want to enable ICU support for encoding, you must integrate ICU with your &xml4c; build. &xml4c; uses ICU for input |
| encoding. See <resource-ref idref="xerces-build-icu"/>.</p> |
| <p>Once you have integrated the ICU with &xml4c;, &xslt4c; automatically uses ICU support for output encoding (the xsl:output |
| encoding attribute).</p> |
| </s3> |
| |
| <s3 title="Enabling ICU support for number formatting and sorting"> |
| <p>If you only want to use the ICU to support number formatting and sorting, you do not need to integrate the ICU with &xslt4c;, |
| but you must do the following in the application where you want to enable ICU support:</p> |
| <ol> |
| <li>Define the environment variable ICUROOT.<br/><br/></li> |
| <li>Substitute ICU support for format-number(), xsl:number, and/or xsl:sort.<br/><br/></li> |
| <li>Rebuild the Xalan library to include the ICUBridge.</li> |
| </ol> |
| <p><em>ICUBridge</em></p> |
| <p>All &xslt4c; references to ICU are centralized in the ICUBridge module, which supplies the infrastructure for enabling ICU |
| support for number formatting and sorting.</p> |
| <source> |
| #include <xalanc/ICUBridge/ICUBridge.hpp> |
| #include <xalanc/ICUBridge/FunctionICUFormatNumber.hpp> |
| #include <xalanc/ICUBridge/ICUXalanNumberFormatFactory.hpp> |
| #include <xalanc/ICUBridge/ICUBridgeCollationCompareFunctor.hpp> |
| </source> |
| <p>For Windows, do a clean build of the Xalan library using the "XalanICU.dsw" workspace (for Visual C++ users) or |
| "XalanICU.sln" solution (for Visual Studio .NET users).</p> |
| <p>For UNIX:</p> |
| <ol> |
| <li>Define the XALAN_USE_ICU environment variable.<br/><br/></li> |
| <li>Set the XALANROOT environment variable to the path to to the ICU root (unless you have copied the ICU library to |
| /usr/lib).<br/><br/></li> |
| <li><link idref="buildlibs" anchor="unixbldenv">Rebuild the Xalan library</link> (&xslt4c-linuxlib; for Linux, &xslt4c-aixlib; for AIX, |
| &xslt4c-hplib; for HP-UX 11, and &xslt4c-solarislib; for Solaris).<br/><br/></li> |
| <li>Be sure the Xalan library is on the library path (LD_LIBRARY_PATH for Red Hat Linux, LIBPATH for AIX, SHLIB_PATH for |
| HP-UX 11, LD_LIBRARY_PATH for Solaris).</li> |
| </ol> |
| <note>The command you use for setting environment variables depends on the shell you are using.<br/> |
| For Bourne Shell, K Shell, or Bash use <em>export</em> ENVAR="val"<br/> |
| For C Shell, use <em>setenv</em> ENVAR "val"<br/> |
| where ENVAR is the environment variable name and val is the environment variable |
| setting. You can check the setting of an environment variable with <em>echo</em> $ENVAR<br/>To define XALAN_USE_ICU, |
| set its value to "1". |
| </note> |
| <p><em>Number formatting</em></p> |
| <p>To enable ICU support for the XSLT format-number() function, do the following:</p> |
| <source> |
| // Install ICU support for the format-number() function. |
| FunctionICUFormatNumber::FunctionICUFormatNumberInstaller theInstaller; |
| </source> |
| |
| <p><em>Sorting</em></p> |
| <p>To enable ICU support for xsl:sort, do the following:</p> |
| <source> |
| // Set up a StylesheetExecutionContextDefaultobject |
| // (named theExecutionContext in the following fragment), |
| // and install the ICUCollationCompareFunctor. |
| ICUBridgeCollationCompareFunctortheICUFunctor; |
| theExecutionContext.installCollationCompareFunctor(&theICUFunctor); |
| </source> |
| </s3> |
| </s2> |
| |
| <anchor name="capi"/> |
| <s2 title="Basic XalanTransformer usage pattern with the C API"> |
| <p>We also include a simple C interface for using the XalanTransformer class. See <jump href="apiDocs/XalanCAPI_8h.html"> |
| XalanTransformer/XalanCAPI.h</jump>. The <link idref="samples" anchor="apachemodulexslt">ApacheModuleXSLT</link> sample |
| illustrates the use of this C API.</p> |
| <p>Basic strategy:</p> |
| |
| <s3 title="1. Include the XalanTransformer C API header"> |
| <source>#include <XalanTransformer/XalanCAPI.h></source> |
| </s3> |
| <s3 title="2. Initialize Xalan and Xerces"> |
| <source>XalanInitialize();</source> |
| </s3> |
| <s3 title="3. Create a Xalan transformer"> |
| <source> |
| XalanHandle xalan = NULL; |
| xalan = CreateXalanTransformer(); |
| </source> |
| </s3> |
| <s3 title="4. Perform each transformation"> |
| <p> For example:</p> |
| <source> |
| const char * xmlfilename = "foo.xml"; |
| const char* xslfilename = "foo.xsl"; |
| const char* outfilename = "foo.out"; |
| int theResult = 0; |
| theResult = XalanTransformToFile(xmlfilename, |
| xslfilename, |
| outfilename, |
| xalan); |
| </source> |
| <note>If the XML input file contains a stylesheet processing instruction that you want to use, use an empty XSLTInputSource |
| for the stylesheet argument.</note> |
| </s3> |
| |
| <s3 title="5. Shut down Xalan"> |
| <source>XalanTerminate();</source> |
| </s3> |
| </s2> |
| |
| <anchor name="cvar"/> |
| <s2 title="Variations with the XalanTransformer C API"> |
| <p>The <jump href="apiDocs/XalanCAPI_8h.html">Xalan C API</jump> supports approximately the same set of options as the C++ API. |
| In particular, you can</p> |
| <ul> |
| <li>Use stylesheet processing instructions (PI) to indicate the URI of the stylesheet. Supply NULL for the stylesheet argument.<br/><br/></li> |
| <li>Set stylesheet parameters. Use the SetStylesheetParam() function.<br/><br/></li> |
| <li>Compile stylesheets. Use the CompileStylesheet() method to compile a stylesheet, and the TransformToFileCSS() or TransformToDataCSS() function to use the compiled stylesheet in a transformation.<br/><br/></li> |
| <li>Parse XML sources. Use the XalanParseSource() or XalanParseSouceUseXalan() method.<br/><br/></li> |
| <li>Place the transformation output in a character array. Use the TransformToData() or TransformToDataCSS() function. After you perform the transformation, use the XalanFreeData() function to free memory allocated for the output data.<br/><br/></li> |
| <li>Send the output to a callback function to process blocks of output data as they arrive.</li> |
| </ul> |
| <p>For a sample that sends output in blocks to a callback function, see <link idref="samples" anchor="apachemodulexslt"> |
| ApacheModuleXSLT</link>.</p> |
| </s2> |
| |
| </s1> |