Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
211 lines (149 sloc) 6.97 KB
-----
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 <Parser> 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 ( <<<Parser parser = new AptParser();>>> )
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 <<Doxia 1.0>> 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 \<div\> block:
+----
sink.RawText( "<div style=\"cool\">" );
sink.text( "A text with a cool style." );
sink.rawText( "</div>" );
+----
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 <<Doxia 1.1>> 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 \<div\> 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!
<<In general, the rawText method should be avoided alltogether when emitting events into an arbitrary Sink.>>
* {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}}
[]