----- Doxia Developers Centre ----- Vincent Siveton ------ 2008-03-02 ------ ~~ 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. ~~ NOTE: For help with the syntax of this file, see: ~~ http://maven.apache.org/doxia/references/apt-format.html Using the Doxia Sink API %{toc|section=1|fromDepth=2|toDepth=2} * {Transforming documents} Doxia can be used to transform an arbitrary input document to any supported output format. The following snippet shows how to use a Doxia to transform an apt file to html: +---- File userDir = new File( System.getProperty ( "user.dir" ) ); File inputFile = new File( userDir, "test.apt" ); File outputFile = new File( userDir, "test.html" ); SinkFactory sinkFactory = (SinkFactory) lookup( SinkFactory.ROLE, "html" ); // Plexus lookup Sink sink = sinkFactory.createSink( outputFile.getParentFile(), outputFile.getName() ) ); Parser parser = (AptParser) lookup( Parser.ROLE, "apt" ); // Plexus lookup Reader reader = ReaderFactory.newReader( inputFile, "UTF-8" ); parser.parse( reader, sink ); +---- It is recommended that you use {{{http://plexus.codehaus.org/}Plexus}} to look up the parser. In principle you could instantiate the parser directly ( <<>> ) but then some special features like macros will not be available. You could also use the {{{http://maven.apache.org/doxia/doxia-tools/doxia-converter/index.html}Doxia Converter Tool}} to parse a given file/dir to another file/dir. * {Generating documents} The snippet below gives a simple example of how to generate a document using the Doxia Sink API. +---- /** * Generate a simple document and emit it * into the specified sink. The sink is flushed but not closed. * * @param sink The sink to receive the events. */ public static void generate( Sink sink ) { sink.head(); sink.title(); sink.text( "Title" ); sink.title_(); sink.author(); sink.text( "Author" ); sink.author_(); sink.date(); sink.text( "Date" ); sink.date_(); sink.head_(); sink.body(); sink.paragraph(); sink.text( "A paragraph of text." ); sink.paragraph_(); sink.section1(); sink.sectionTitle1(); sink.text( "Section title" ); sink.sectionTitle1_(); sink.paragraph(); sink.text( "Paragraph in section." ); sink.paragraph_(); sink.section1_(); sink.body_(); sink.flush(); } +---- A more complete example that also shows the 'canonical' order of events to use when generating a document, can be found in the Doxia {{{./doxia/doxia-core/xref-test/org/apache/maven/doxia/sink/SinkTestDocument.html}SinkTestDocument}} class. * {Passing attributes to Sink events} With Doxia 1.1 a number of methods have been added to the Sink API that allow to pass a set of attributes to many sink events. A typical use case would be: +---- SinkEventAttributeSet atts = new SinkEventAttributeSet(); atts.addAttribute( SinkEventAttributes.ALIGN, "center" ); sink.paragraph( atts ); +---- What kind of attributes are supported depends on the event and the sink implementation. The sink API specifies a list of suggested attribute names that sinks are expected to recognize, and parsers are expected to use preferably when emitting events. * {Avoid sink.rawText!} In <> it was a common practice to use sink.rawText() to generate elements that were not supported by the Sink API. For example, the following snippet could be used to generate a styled HTML \ block: +---- sink.RawText( "
" ); sink.text( "A text with a cool style." ); sink.rawText( "
" ); +---- This has a major drawback however: it only works if the receiving Sink is a HTML Sink. In other words, the above method will not work for target documents in any other format than HTML (think of the FO Sink to generate a pdf, or a LaTeX sink,...). In <> a new method unknown() was added to the Sink API that can be used to emit an arbitrary event without making special assumptions about the receiving Sink. Depending on the parameters, a Sink may decide whether or not to process the event, emit it as raw text, as a comment, log it, etc. The correct way to generate the above \ block is now: +---- SinkEventAttributeSet atts = new SinkEventAttributeSet(); atts.addAttribute( SinkEventAttributes.STYLE, "cool" ); sink.unknown( "div", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_START )}, atts ); sink.text( "A text with a cool style." ); sink.unknown( "div", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_END )}, null ); +---- Read the javadocs of the unknown() method in the {{{./doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}Sink}} interface and the {{{./doxia/doxia-core/apidocs/org/apache/maven/doxia/sink/XhtmlBaseSink.html}XhtmlbaseSink}} for information on the method parameters. Note that an arbitrary sink may be expected to ignore the unknown event completely! <> * {How to inject javascript code into HTML} Related to the above, here is the correct way of injecting a javascript snippet into a Sink: +---- // the javascript code is emitted within a commented CDATA section // so we have to start with a newline and comment the CDATA closing in the end // note that the sink will replace the newline by the system EOL String javascriptCode = "\n function javascriptFunction() {...} \n //"; SinkEventAttributeSet atts = new SinkEventAttributeSet(); atts.addAttribute( SinkEventAttributes.TYPE, "text/javascript" ); sink.unknown( "script", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_START )}, atts ); sink.unknown( "cdata", new Object[]{new Integer( HtmlMarkup.CDATA_TYPE ), javascriptCode }, null ); sink.unknown( "script", new Object[]{new Integer( HtmlMarkup.TAG_TYPE_END )}, null ); +---- * {References} * {{{../modules/index.html}Doxia Modules Guide}} * {{{../macros/index.html}Doxia Macros Guide}} * {{{../doxia/apidocs/index.html}Doxia API Reference}} * {{{../doxia-sitetools/apidocs/index.html}Doxia Sitetools API Reference}} []