|
|
@@ -1,169 +1,156 @@ |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
FOP: An Open-Source XSL Formatter and Renderer |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1) What is FOP? |
|
|
|
2) Compiling FOP |
|
|
|
3) Running FOP |
|
|
|
4) What's Implemented? |
|
|
|
5) Bugs |
|
|
|
6) FOP Relevant Specifications |
|
|
|
|
|
|
|
|
|
|
|
1) What is FOP? |
|
|
|
FOP is the world's first print formatter driven by XSL formatting |
|
|
|
objects. It is a Java 1.1 application that reads a formatting object |
|
|
|
tree and then turns it into a PDF document. The formatting object |
|
|
|
tree, can be in the form of an XML document (output by an XSLT engine |
|
|
|
like XT or Xalan) or can be passed in memory as a DOM Document or (in |
|
|
|
the case of XT) SAX events. |
|
|
|
|
|
|
|
|
|
|
|
FOP is part of Apache's XML project. The homepage of FOP is |
|
|
|
http:/xml.apache.org/fop (http:/xml.apache.org/fop) |
|
|
|
. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2) Compiling FOP |
|
|
|
|
|
|
|
1. Prerequisites |
|
|
|
|
|
|
|
a) Java 1.1.x or later |
|
|
|
|
|
|
|
|
|
|
|
FOP readme |
|
|
|
|
|
|
|
Content |
|
|
|
1. What is FOP? |
|
|
|
2. Downloading FOP |
|
|
|
3. Running FOP |
|
|
|
4. Features |
|
|
|
5. Limitations |
|
|
|
6. Compiling FOP |
|
|
|
7. Embedding FOP |
|
|
|
8. Getting involved |
|
|
|
9. FOP Relevant Specifications |
|
|
|
10. License |
|
|
|
|
|
|
|
1. What is FOP? |
|
|
|
FOP is the world's first print formatter driven by XSL formatting |
|
|
|
objects. It is a Java 1.1 application that reads a formatting object |
|
|
|
tree and then turns it into a PDF document. The formatting object |
|
|
|
tree, can be in the form of an XML document (output by an XSLT engine |
|
|
|
like XT or Xalan) or can be passed in memory as a DOM Document or (in |
|
|
|
the case of XT) SAX events. |
|
|
|
|
|
|
|
b) An XML parser |
|
|
|
An XML parser which supports DOM like |
|
|
|
Xerces-J (http://xml.apache.org/xerces-j/index.html) |
|
|
|
. |
|
|
|
|
|
|
|
|
|
|
|
c) XT from James Clark |
|
|
|
Some of the Java source code in FOP is generated from XML using |
|
|
|
XSLT. XT must be used to generate this code. |
|
|
|
XT is an XSL stylesheet processor written in java. At the moment you |
|
|
|
can't use any other processor, because the make file makes use of some |
|
|
|
proprietary features of Clark's xt which allow to write output in more |
|
|
|
then one document. You can find XT at |
|
|
|
James Clark's website (http://www.jclark.com/xml/xt.html) |
|
|
|
. You have to use XT version 19991105 or later. |
|
|
|
(Under windows you shouldn't use the prepackaged xt.exe but also the |
|
|
|
generic jar file, otherwise make won't work) |
|
|
|
|
|
|
|
XT relies on an sax parser like XP (also J. Clark), which can be |
|
|
|
downloaded at James |
|
|
|
Clark's Website (http://www.jclark.com/xml/xp/index.html) |
|
|
|
FOP is part of Apache's XML project. The homepage of FOP is |
|
|
|
http:/xml.apache.org/fop (http:/xml.apache.org/fop). |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
d) make |
|
|
|
Under windows it has been reported that the use of the cygnus solutions port |
|
|
|
of the GNU utilities works. You can find it at |
|
|
|
Cygnus Solutions (http://sourceware.cygnus.com/cygwin/) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2. Downloading FOP |
|
|
|
|
|
|
|
2.1. Downloading binaries |
|
|
|
You can download the latest release version FOP 0.12.0 |
|
|
|
(http://xml.apache.org/dist/fop_bin_0_12_0.jar). |
|
|
|
NOTE: you do not have to unjar or unzip this jar file. |
|
|
|
To run FOP from the command line, see Running FOP. If you are |
|
|
|
interested in embedding FOP in a Java application of your own, see |
|
|
|
Embedding FOP. |
|
|
|
|
|
|
|
2.2. Downloading source code |
|
|
|
You can also download the source code v. 0.12.0 |
|
|
|
(http://xml.apache.org/dist/fop_src_0_12_0.jar) as a jar file |
|
|
|
|
|
|
|
|
|
|
|
3. Running FOP |
|
|
|
|
|
|
|
3) Running FOP |
|
|
|
|
|
|
|
1) Prerequisites |
|
|
|
3.1. Prerequisites |
|
|
|
Following software must be installed: |
|
|
|
a) Java 1.1.x or later |
|
|
|
b) An XML parser which supports SAX and DOM like |
|
|
|
Xerces-J (http://xml.apache.org/xerces-j/index.html) |
|
|
|
. |
|
|
|
Xerces-J (http://xml.apache.org/xerces-j/index.html). |
|
|
|
c) If you have to produce the flow objects files, which are the input for FOP, |
|
|
|
you need a transformation utility to create this files from your xml files. |
|
|
|
Normally this is an XSLT stylesheet processor like |
|
|
|
XT (http://www.jclark.com/xml/xt.html) |
|
|
|
|
|
|
|
or XALAN (http://xml.apache.org/xalan/index.html) |
|
|
|
. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2) Starting FOP as an standalone application |
|
|
|
There are three ways of running FOP from the command line. |
|
|
|
a) Batch processing formatting object files: |
|
|
|
java org.apache.fop.apps.CommandLine fo-file pdf-file |
|
|
|
or XALAN (http://xml.apache.org/xalan/index.html). |
|
|
|
|
|
|
|
3.2. Starting FOP as an standalone application |
|
|
|
There are three ways to run FOP from the command line. |
|
|
|
a) Batch processing formatting objects (fo) files: |
|
|
|
java org.apache.fop.apps.CommandLine fo-file pdf-file |
|
|
|
b) Batch processing xml files (includes production of the fo-files): |
|
|
|
java org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file |
|
|
|
java org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file |
|
|
|
c) Previewing the fo-file: |
|
|
|
java org.apache.fop.apps.AWTCommandLine fo-file |
|
|
|
java org.apache.fop.apps.AWTCommandLine fo-file |
|
|
|
Each method uses next to the fop classes other packages. The following describes |
|
|
|
each method in detail. |
|
|
|
|
|
|
|
a) Method One |
|
|
|
|
|
|
|
3.2.1. Method One |
|
|
|
One is to first use an XSLT engine to produce the formatting object tree as an |
|
|
|
XML document and then running the class org.apache.fop.apps.CommandLine with the |
|
|
|
formatting object file name and PDF filename as arguments. You will need to include |
|
|
|
FOP, SAX and your SAX Parser in your classpath and so you might invoke |
|
|
|
XML document and then running the class org.apache.fop.apps.CommandLine with the |
|
|
|
formatting object file name and PDF filename as arguments. You need to set classpath |
|
|
|
and set the used sax parser according to your enviroment |
|
|
|
|
|
|
|
java -cp fop_x_xx_x.jar;sax.jar;xp.jar |
|
|
|
org.apache.fop.apps.CommandLine formatting-tree-file pdf-file |
|
|
|
If your SAX Parser is other than XP, you will need to set the property |
|
|
|
org.xml.sax.parser to the SAX Parser class to use. The following example shows |
|
|
|
the command line, if you use Xerces, the xml parser from xml.apache.org: |
|
|
|
Classpath settings: You will need to include FOP and your XML Parser |
|
|
|
in your classpath and so you might invoke FOP, if XP is your sax parser |
|
|
|
and Xerces-J your DOM parser: |
|
|
|
|
|
|
|
java -Dorg.xml.sax.parser=org.apache.xerces.parsers.SAXParser |
|
|
|
-cp fop_x_xx_x.jar;xerces.jar |
|
|
|
org.apache.fop.apps.AWTCommandLine formatting-tree-file pdf-file |
|
|
|
|
|
|
|
java -cp fop_bin_0_12_0.jar;xp.jar;xerces.jar |
|
|
|
org.apache.fop.apps.CommandLine fo-file pdf-file |
|
|
|
|
|
|
|
For historical reasons the standard sax parser for FOP is XP from James Clark. |
|
|
|
This will change in the future to Xerces-J, but at the moment you will need to |
|
|
|
set the property org.xml.sax.parser to any other SAX Parser class to use. |
|
|
|
The following example shows the command line, if you use Xerces-J: |
|
|
|
|
|
|
|
java -Dorg.xml.sax.parser=org.apache.xerces.parsers.SAXParser |
|
|
|
-cp fop_bin_0_12_0.jar;xerces.jar |
|
|
|
org.apache.fop.apps.CommandLine fo-file pdf-file |
|
|
|
|
|
|
|
b) Method Two |
|
|
|
3.2.2. Method Two |
|
|
|
Rather than performing transformation with an XSLT before invoking FOP, it is |
|
|
|
possible, if you use XT as your XSLT engine, to just call FOP and have it call |
|
|
|
XT for you. To do this, run the class org.apache.fop.apps.CommandLine with the |
|
|
|
source XML file name, XSL file name and PDF file name as arguments. You will |
|
|
|
need to include FOP, SAX, your SAX Parser and XT in your classpath and so you might |
|
|
|
invoke |
|
|
|
possible, if you use XT as your XSLT engine, to just call FOP and have it call |
|
|
|
XT for you. To do this, run the class org.apache.fop.apps.CommandLine with the |
|
|
|
source XML file name, XSL file name and PDF file name as arguments. You will |
|
|
|
need to include FOP, SAX, your SAX Parser and XT in your classpath and so you might |
|
|
|
invoke |
|
|
|
|
|
|
|
java -cp fop_x_xx_x.jar;sax.jar;xp.jar;xt.jar |
|
|
|
org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file |
|
|
|
java -cp fop_bin_0_12_0.jar;xt.jar;xp.jar;xerces.jar |
|
|
|
org.apache.fop.apps.CommandLine xml-file xsl-file pdf-file |
|
|
|
|
|
|
|
Again, if your SAX Parser is other than XP, you will need to set the property |
|
|
|
org.xml.sax.parser to the SAX Parser class to use. |
|
|
|
org.xml.sax.parser to the SAX Parser class to use. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
c) Method Three |
|
|
|
3.2.3. Method Three |
|
|
|
If you already produced the FO file, you can preview the results of your |
|
|
|
transformation without using any pdf viewer by invoking FOP with the viewer |
|
|
|
application. You will need to include FOP, SAX and your SAX Parser in your classpath |
|
|
|
transformation without using any pdf viewer by invoking FOP with the viewer |
|
|
|
application. You will need to include FOP and your XML Parser in your classpath |
|
|
|
|
|
|
|
java org.apache.fop.apps.AWTCommandLine formatting-tree-file |
|
|
|
java -cp fop_bin_0_12_0.jar;xp.jar;xerces.jar |
|
|
|
org.apache.fop.apps.AWTCommandLine fo-file |
|
|
|
|
|
|
|
The viewer uses the swing classes. |
|
|
|
|
|
|
|
Note: If you are using java 2 or later (i.e. jdk 1.2. or later) you can put all |
|
|
|
needed jar files into the subdirectory jdk1.2.x\jre\lib\ext (windows example). Then |
|
|
|
FOP can be started without classpath: |
|
|
|
needed jar files into the subdirectory jdk1.2.x\jre\lib\ext (windows example). Then |
|
|
|
FOP can be started without classpath: |
|
|
|
|
|
|
|
java org.apache.fop.apps.CommandLine fo-file pdf-file |
|
|
|
java org.apache.fop.apps.CommandLine fo-file pdf-file |
|
|
|
|
|
|
|
|
|
|
|
3.3. Running FOP on MacOS |
|
|
|
Ensure that you have a recent MRJ, and that you have downloaded and |
|
|
|
unpacked the XP and SAX distributions. The xp.jar and sax.jar files work |
|
|
|
as is on MacOS. |
|
|
|
|
|
|
|
Drag the FOP jarfile onto the JBindery icon. When the first dialog |
|
|
|
appears, type "org.apache.fop.apps.CommandLine" in the "Class name" field. |
|
|
|
Using UNIX syntax, type the names of the input formatting-object file and |
|
|
|
the output PDF in the "Optional parameters" field. |
|
|
|
|
|
|
|
Click on the Classpath icon. To add the xp.jar and sax.jar files, click |
|
|
|
the "Add .zip file" button, navigate to the file in question, and click |
|
|
|
Open. |
|
|
|
|
|
|
|
Once both are added (the FOP jarfile will already be in the list), click |
|
|
|
Run. A "stdout" window will appear and display FOP runtime messages. |
|
|
|
|
|
|
|
|
|
|
|
3.4. Problems |
|
|
|
If you have problems running FOP, please have a look at the |
|
|
|
FOP FAQ (faq-running.html). If you don't find a solution there, |
|
|
|
you can ask for help on the list fop-dev@xml.apache.org. Maybe it is a bug and |
|
|
|
maybe somebody is already working on it. |
|
|
|
|
|
|
|
|
|
|
|
4. Features |
|
|
|
|
|
|
|
4.1. What's Implemented? |
|
|
|
The following formatting objects and properties of the xsl-fo |
|
|
|
working draft are implemented. Please have also a look at the |
|
|
|
section on limitations (limitations.html) |
|
|
|
|
|
|
|
|
|
|
|
4) What's Implemented? |
|
|
|
Also see STATUS for what is being worked on. |
|
|
|
|
|
|
|
a) Formatting Objects |
|
|
|
|
|
|
|
root |
|
|
|
1) Formatting Objects |
|
|
|
root |
|
|
|
layout-master-set |
|
|
|
simple-page-master |
|
|
|
region-body |
|
|
@@ -192,11 +179,7 @@ |
|
|
|
table-row (minimal support) |
|
|
|
table-cell (minimal support) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
b) Properties |
|
|
|
|
|
|
|
2) Properties |
|
|
|
end-indent |
|
|
|
page-master-name |
|
|
|
page-master-first |
|
|
@@ -238,45 +221,282 @@ |
|
|
|
padding-left (only in conjunction with background color) |
|
|
|
padding-bottom (only in conjunction with background color) |
|
|
|
padding-right (only in conjunction with background color) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
5) Bugs |
|
|
|
see STATUS file |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
6) FOP Relevant Specifications |
|
|
|
5. Limitations |
|
|
|
Although FOP implements the above listed fo objects and properties, sometimes it does so |
|
|
|
only in a limited way. |
|
|
|
|
|
|
|
5.1. list-block |
|
|
|
The fo working draft allows describes two ways to markup lists.The list-block must |
|
|
|
have as children either: 1) pairs of fo:list-item-label and fo:list-item-body |
|
|
|
formatting objects, or 2) fo:list-item formatting objects. |
|
|
|
At the moment FOP only implements the second way. Therefore a list has a basic |
|
|
|
structure like this: |
|
|
|
<fo:list-block> |
|
|
|
<fo:list-item> |
|
|
|
<fo:list-item-label><fo:block></fo:block></fo:list-item-label> |
|
|
|
<fo:list-item-body><fo:block></fo:block></fo:list-item-body> |
|
|
|
</fo:list-item> |
|
|
|
</fo:list-block> |
|
|
|
|
|
|
|
5.2. Padding |
|
|
|
Padding works in conjunction with indents and spaces. It is only implemented |
|
|
|
for blocks. At the moment padding can't be used to make extra space (indents+spaces |
|
|
|
must be used), but only to control how much the background-color extends beyond |
|
|
|
the content rectangle. |
|
|
|
|
|
|
|
5.3. Tables |
|
|
|
There two limitations for tables: 1) FOP needs you to explicitly specify column widths |
|
|
|
2) Cells have to contain block-level FOs. They can't contain straight character data. |
|
|
|
|
|
|
|
A working basic example of a table looks like this: |
|
|
|
<fo:table> |
|
|
|
<fo:table-column column-width="150pt"/> |
|
|
|
<fo:table-column column-width="150pt"/> |
|
|
|
<fo:table-body font-size="10pt" font-family="sans-serif"> |
|
|
|
<fo:table-row> |
|
|
|
<fo:table-cell> |
|
|
|
<fo:block>text</fo:block> |
|
|
|
</fo:table-cell> |
|
|
|
<fo:table-cell> |
|
|
|
<fo:block>text</fo:block> |
|
|
|
</fo:table-cell> |
|
|
|
</fo:table-row> |
|
|
|
<fo:table-row> |
|
|
|
<fo:table-cell> |
|
|
|
<fo:block>text</fo:block> |
|
|
|
</fo:table-cell> |
|
|
|
<fo:table-cell> |
|
|
|
<fo:block>text</fo:block> |
|
|
|
</fo:table-cell> |
|
|
|
</fo:table-row> |
|
|
|
<fo:table-row> |
|
|
|
<fo:table-cell> |
|
|
|
<fo:block>text</fo:block> |
|
|
|
</fo:table-cell> |
|
|
|
<fo:table-cell> |
|
|
|
<fo:block>text</fo:block> |
|
|
|
</fo:table-cell> |
|
|
|
</fo:table-row> |
|
|
|
</fo:table-body> |
|
|
|
</fo:table> |
|
|
|
|
|
|
|
6. Compiling FOP |
|
|
|
|
|
|
|
6.1. Prerequisites |
|
|
|
6.1.1. Java 1.1.x or later |
|
|
|
If you use Java 1.1.x you must also seperately include the swing classes, which can |
|
|
|
be found at the Sun website (http://java.sun.com/products/jfc/#download-swing). From |
|
|
|
Java 1.2 on (aka Java 2) they are part of the standard distribution. |
|
|
|
|
|
|
|
6.1.2. An XML parser |
|
|
|
An XML parser which supports DOM like Xerces-J |
|
|
|
(http://xml.apache.org/xerces-j/index.html). |
|
|
|
|
|
|
|
6.1.3. XT from James Clark |
|
|
|
Some of the Java source code in FOP is generated from XML using |
|
|
|
XSLT. XT must be used to generate this code. |
|
|
|
XT is an XSL stylesheet processor written in java. At the moment you |
|
|
|
can't use any other processor, because the make file makes use of some |
|
|
|
proprietary features of Clark's xt which allow to write output in more |
|
|
|
then one document. You can find XT at James Clark's website |
|
|
|
(http://www.jclark.com/xml/xt.html). You have to use XT version 19991105 |
|
|
|
or later. (Under windows you shouldn't use the prepackaged xt.exe but also the |
|
|
|
generic jar file, otherwise make won't work) |
|
|
|
|
|
|
|
XT relies on an sax parser like XP (also J. Clark), which can be |
|
|
|
downloaded at James Clark's Website (http://www.jclark.com/xml/xp/index.html) |
|
|
|
|
|
|
|
6.1.4. make |
|
|
|
Under windows it has been reported that the use of the cygnus solutions port |
|
|
|
of the GNU utilities works. You can find it at |
|
|
|
Cygnus Solutions (http://sourceware.cygnus.com/cygwin/) |
|
|
|
|
|
|
|
6.2. Compiling FOP on MacOS |
|
|
|
We strongly recommend the use of Codewarrior Java. You will find |
|
|
|
a link to more information in the near future. |
|
|
|
|
|
|
|
|
|
|
|
7. Embedding FOP |
|
|
|
|
|
|
|
Instantiate org.apache.fop.apps.Driver. Once this class is |
|
|
|
instantiated, methods are called to set the |
|
|
|
Renderer to use, the (possibly multiple) ElementMapping(s) to |
|
|
|
use and the PrintWriter to use to output the results of the |
|
|
|
rendering (where applicable). In the case of the Renderer and |
|
|
|
ElementMapping(s), the Driver may be supplied either with the |
|
|
|
object itself, or the name of the class, in which case Driver will |
|
|
|
instantiate the class itself. The advantage of the latter is it |
|
|
|
enables runtime determination of Renderer and ElementMapping(s). |
|
|
|
|
|
|
|
Once the Driver is set up, the buildFOTree method |
|
|
|
is called. Depending on whether DOM or SAX is being used, the |
|
|
|
invocation of the method is either buildFOTree(Document) or |
|
|
|
buildFOTree(Parser, InputSource) respectively. |
|
|
|
|
|
|
|
A third possibility may be used to build the FO Tree, namely |
|
|
|
calling getDocumentHandler() and firing the SAX events yourself. |
|
|
|
|
|
|
|
Once the FO Tree is built, the format() and render() methods may be |
|
|
|
called in that order. |
|
|
|
|
|
|
|
Here is an example use of Driver from CommandLine.java: |
|
|
|
|
|
|
|
Driver driver = new Driver(); |
|
|
|
driver.setRenderer("org.apache.fop.render.pdf.PDFRenderer", version); |
|
|
|
driver.addElementMapping("org.apache.fop.fo.StandardElementMapping"); |
|
|
|
driver.addElementMapping("org.apache.fop.svg.SVGElementMapping"); |
|
|
|
driver.setWriter(new PrintWriter(new FileWriter(args[1]))); |
|
|
|
driver.buildFOTree(parser, fileInputSource(args[0])); |
|
|
|
driver.format(); |
|
|
|
driver.render(); |
|
|
|
|
|
|
|
8. Getting involved |
|
|
|
8.1. First steps |
|
|
|
1. Subscribe to fop-dev@xml.apache.org by sending an email |
|
|
|
to fop-dev-subscribe@xml.apache.org |
|
|
|
2. Read the archives to fop-dev to get an idea of the issues being |
|
|
|
discussed. |
|
|
|
3. Subscribe to fop-cvs@xml.apache.org by sending an email to |
|
|
|
fop-cvs-subscribe@xml.apache.org (it is important |
|
|
|
that you follow changes being made). |
|
|
|
4. Try :-) to wrap your head around the XSL working draft. |
|
|
|
5. Get CVS working on your system. |
|
|
|
6. Ask, on fop-dev, any questions you have at all about the code, design, etc. |
|
|
|
7. When you feel comfortable modifying the code, send diffs to |
|
|
|
fop-dev with your contributions. |
|
|
|
8. Have fun! |
|
|
|
|
|
|
|
8.2. The Ways of FOP |
|
|
|
The following shows an example use of FOP from org.apache.fop.apps.CommandLine.java: |
|
|
|
|
|
|
|
1) Driver driver = new Driver(); |
|
|
|
2) driver.setRenderer ("org.apache.fop.render.pdf.PDFRenderer", version); |
|
|
|
3) driver.addElementMapping ("org.apache.fop.fo.StandardElementMapping"); |
|
|
|
3) driver.addElementMapping ("org.apache.fop.svg.SVGElementMapping"); |
|
|
|
4) driver.setWriter (new PrintWriter(new FileWriter(args[1]))); |
|
|
|
5) driver.buildFOTree(parser, fileInputSource(args[0])); |
|
|
|
6) driver.format(); |
|
|
|
7) driver.render(); |
|
|
|
|
|
|
|
1. step: Initiate class Driver |
|
|
|
Driver is the primary class that drives overall FOP process. |
|
|
|
|
|
|
|
2. step: Set Renderer |
|
|
|
You set the renderer for the output format of your choice. At the moment 3 formats are |
|
|
|
supported: a) pdf (org.apache.fop.render.pdf.PDFRenderer) |
|
|
|
b) awt (org.apache.fop.render.awt.AWTRenderer) |
|
|
|
c) xml (org.apache.fop.render.xml.XMLRenderer) |
|
|
|
|
|
|
|
All renderers implement the interface Renderer which defines the methods an area |
|
|
|
needs to be laid out. |
|
|
|
|
|
|
|
The xml renderer is meant for debugging purposes. |
|
|
|
|
|
|
|
The interface Renderer takes a string as a version argument indicating the application |
|
|
|
that is producing the output. Many output formats like PDF allow the inclusion |
|
|
|
of a "Producer" string. |
|
|
|
|
|
|
|
|
|
|
|
3. step: Set Element Mapping |
|
|
|
By setting the element mapping you choose the dictionaries of elements which |
|
|
|
FOP can handle. At the moment two dictionaries are available: |
|
|
|
a) Standard xsl elements (org.apache.fop.fo.StandardElementMapping) |
|
|
|
b) Graphic elements described by SVG (org.apache.fop.svg.SVGElementMapping) |
|
|
|
|
|
|
|
All element mappings implement the interface ElementMapping. |
|
|
|
|
|
|
|
4. step: Set output destination |
|
|
|
Normally this will be a Printwriter of some sort. If you are just displaying the |
|
|
|
output on screen you can skip this step. |
|
|
|
|
|
|
|
5. step: Build FO Tree |
|
|
|
Builds the tree of formatting objects contained in the input source. Either walks |
|
|
|
the tree of the input document (DOM) or uses SAX events to build up the tree |
|
|
|
by looking up the definitions of the fo in the element mappings. Depending on |
|
|
|
whether DOM or SAX is being used, the invocation of the method is either |
|
|
|
buildFOTree(Document) or buildFOTree(Parser, InputSource) respectively. |
|
|
|
|
|
|
|
6. step: Build Area Tree from FO Tree |
|
|
|
By calling format() of the driver class the fo tree is written/formatted into |
|
|
|
a area tree. Every formatting object knows how to layout itself, that is every |
|
|
|
formatting object has a an layout method which is now called to produce an area. |
|
|
|
The setup of the font info for the renderer is also done in this step. |
|
|
|
|
|
|
|
7. step: Renderer renders Areas |
|
|
|
The renderer, which has been set in step 2, is given the area tree. It uses the |
|
|
|
layout information to output it in its specific format. Example: For the PDF |
|
|
|
renderer there is a set of methods to create a pdf file containing the FOP |
|
|
|
supported kind of layout features. |
|
|
|
|
|
|
|
-------------------------------------------------------------------------- |
|
|
|
If you want to extend the functionality of FOP by adding new formatting objects, |
|
|
|
you should do the following: |
|
|
|
|
|
|
|
1. FO Object: Write a class which contains the description of your formatting |
|
|
|
object and put it into the package fop.fo.flow, fop.fo.pagination (if it |
|
|
|
is a property it goes to fop.fo.properties. The classes in this package are |
|
|
|
generated via an xslt stylesheet located in codegen/properties.xml) |
|
|
|
2. Element Mapping: Add it to the list in fop.fo.StandardElementMapping (if it |
|
|
|
is a property you need to add it to fop.fo.PropertyListBuilder) |
|
|
|
3. Area: Either your need can be fulfilled within one of the existing classes |
|
|
|
in fop.layout, then just add the code to handle the new fo/property or you |
|
|
|
must write a new one. |
|
|
|
4. Renderer: Choose the renderer you are interested in. If you worked on an |
|
|
|
existing layout class you must add code to handle the new features to the |
|
|
|
already existing area specific method in the renderer class. Otherwise you |
|
|
|
have to add a new method. |
|
|
|
|
|
|
|
|
|
|
|
9. FOP Relevant Specifications |
|
|
|
|
|
|
|
XML Recommendation (http://www.w3.org/TR/REC-xml) |
|
|
|
|
|
|
|
XSL-FO Working Draft (http://www.w3.org/TR/WD-xsl/) |
|
|
|
|
|
|
|
XSLT Recommandation (http://www.w3.org/TR/xslt) |
|
|
|
|
|
|
|
XSLT Recommendation (http://www.w3.org/TR/xslt) |
|
|
|
PDF Documentation (http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf) |
|
|
|
|
|
|
|
Simple API for XML (SAX) (http://www.megginson.com/SAX/) |
|
|
|
|
|
|
|
Document Object Model (DOM) (http://www.w3.org/TR/REC-DOM-Level-1) |
|
|
|
|
|
|
|
Namespaces in XML Recommendation (http://www.w3.org/TR/REC-xml-names/) |
|
|
|
|
|
|
|
Java JDK 1.1 Documentation (http://java.sun.com/products/jdk/1.1/docs/index.html) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Version: 1.4 1999/11/29 19:45 - |
|
|
|
Contact: James Tauber (jtauber@jtauber.com) |
|
|
|
|
|
|
|
10. License |
|
|
|
|
|
|
|
The Apache Software License, Version 1.1 |
|
|
|
Copyright (C) 1999 The Apache Software Foundation. All rights reserved. |
|
|
|
Redistribution and use in source and binary forms, with or without modification, |
|
|
|
are permitted provided that the following conditions are met: |
|
|
|
1. Redistributions of source code must retain the above copyright notice, |
|
|
|
this list of conditions and the following disclaimer. |
|
|
|
2. Redistributions in binary form must reproduce the above copyright notice, |
|
|
|
this list of conditions and the following disclaimer in the documentation |
|
|
|
and/or other materials provided with the distribution. |
|
|
|
3. The end-user documentation included with the redistribution, if any, must |
|
|
|
include the following acknowledgment: "This product includes software |
|
|
|
developed by the Apache Software Foundation (http://www.apache.org/)." |
|
|
|
Alternately, this acknowledgment may appear in the software itself, if |
|
|
|
and wherever such third-party acknowledgments normally appear. |
|
|
|
4. The names "FOP" and "Apache Software Foundation" must not be used to |
|
|
|
endorse or promote products derived from this software without prior |
|
|
|
written permission. For written permission, please contact |
|
|
|
apache@apache.org. |
|
|
|
5. Products derived from this software may not be called "Apache", nor may |
|
|
|
"Apache" appear in their name, without prior written permission of the |
|
|
|
Apache Software Foundation. |
|
|
|
|
|
|
|
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, |
|
|
|
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND |
|
|
|
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE |
|
|
|
APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, |
|
|
|
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU- |
|
|
|
DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS |
|
|
|
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON |
|
|
|
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
|
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
|
|
|
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
|
|
|
|
|
|
This software consists of voluntary contributions made by many individuals |
|
|
|
on behalf of the Apache Software Foundation and was originally created by |
|
|
|
James Tauber <jtauber@jtauber.com>. For more information on the Apache |
|
|
|
Software Foundation, please see http://www.apache.org/ (http://www.apache.org/). |