FOP is a print formatter for XSL formatting objects.
It can be used to render an XML file containing XSL formatting objects into a page layout. The main target is PDF but other rendering targets are supported, such as AWT, PCL, text and direct printing.
FOP provides both an application and a library that converts an XSL FO document into paginated output.
The FOP command line application can be directly used to transform XML into PDF, PostScript, PCL and other formats, there is also an AWT based viewer integrated.
The library can be used in servlets and other Java applications.
FOP is an acronym for Formatting Object Processor
FOP is distributed with Cocoon as a PDF serializer for XSL (FO) documents.
Batik can be used with FOP to transcode an SVG image into a PDF document.
XSL is a W3C standard concerned with publishing XML documents. It consists of two parts: XSLT and XSL-FO. The acronym expands to eXtensible Stylesheet Language.
XSLFO (aka XSL-FO) is an XML vocabulary that is used to specify a pagination and other styling for page layout output. The acronym “FO” stands for Formatting Objects. XSLFO can be used in conjunction with XSLT to convert from any XML format into a paginated layout ready for printing or displaying.
XSLFO defines a set of elements in XML that describes the way pages are set up. The contents of the pages are filled from flows. There can be static flows that appear on every page (for headers and footers) and the main flow which fills the body of the page.
Synonyms: XSL FO, XSL (FO), XSL:FO, XSL-FO, Formatting Objects
XSLT describes the transformation of arbitrary XML input into other XML (like XSLFO), HTML or plain text. The “T” comes from Transformation. For historical reasons, a transformation is often also called a “style sheet”.
Synonyms: XSL transformation, XSL:T, XSL style sheet.
The short answer is "Don't ask." For more details, see Understand FOP's Limitations.
When it's ready and the committers have enough time to go through the time-consuming process of creating a release. We released version 1.0 on 21 July 2010, and will release version 1.1 when we accumulated enough additions and bug fixes. If you want to speed up the process, consider contributing to FOP.
The code redesign of FOP was necessary in order to be able to adress following issues:
There are numerous ways that you can help. They are outlined in the Developer's Introduction page.
FOP was changed to be in accordance with the latest standard (see XSL standard).The page master for a fo:page-sequence is now referenced by the master-reference attribute. Replace the master-name attributes of your fo:page-sequence elements by master-reference attributes. You have to do this also for fo:single-page-master-reference, fo:repeatable-page-master-reference and fo:conditional-page-master-reference elements in you page master definitions.
Update your FO documents and style sheets.
This is typically a problem with your classpath.
If you are running FOP from the command line:
fop.bat, fop.cmd or fop.js on MS Windows, or fop on Unix/Linux from the FOP
distribution.
fop.bat file are in their
respective places.
If you run FOP embedded in your servlet, web application or other Java application, check the classpath of the application. Check the also the information pertaining to servlet engines for further hints.
If you downloaded the source distribution, or a snapshop from the repository, remember you have to build the FOP jars first.
This is usually caused by an older version of one of the FOP jars or old XML tools in the classpath. Check in particular for parser.jar, jaxp.jar, xml4j.jar or lotusxsl.jar.
Incompatible versions of Batik may also cause this problem. Use the version of Batik that comes with FOP. It is not always possible to use a more recent version of Batik.
See FOP Memory.
What you probably think of as "file names" are usually URLs, in
particular the src attribute of fo:external-graphic.
Because usage of URLs is growing, you should make yourself familiar with it. The relevant specification is RFC 2396.
In a nutshell, the correct syntax for an absolute file URL is
file:///some/path/file.ext on Unix and
file:///z:/some/path/file.ext on Windows systems. Note
the triple slash, and also that only forward slashes are used, even on
windows.
A relative file URL starts with anything but a slash, and doesn't have
the file: prefix, for example file.ext,
path/file.ext or ../file.ext. The string
file:path/file.ext is not a relative URL,
in fact, it isn't a valid URL at all. A relative URL is subject to a
resolving process, which transforms it into an absolute
URL.
This is often caused by an invalid FO document. Currently only very
common errors are intercepted and produce a comprehensible error
message. If you forgot container elements like fo:page-sequence or
fo:flow and put blocks and inline elements directly as children of
fo:root or fo:page-sequence, you'll only get a
NullPointerException. Check whether your FO file has a proper
structure. In some cases there are mandatory properties, like the
master-reference in fo:conditional-page-master-reference, check also
whether you got them right.
You may find it helpful to use the validation tools to validate your FO document. This will catch most problems, but should not be relied upon to catch all.
If you use XSLT, problems in your style sheet and in your source XML also can produce a NullPointerException. Run the transformation separately to check for this, usually you'll get a detailed error message from the XSLT processor.
If you turn on debugging with the "-d" option you may be able to
see more detailed information.
See FOP's Standards Compliance page.
The most likely reason is a known problem with the Java run time environment which is triggered by rendering SVGs. Suns JDK 1.4 does not have this problem. See also FOP does not exit if a SVG is included.
Another possibility is that FOP went into a non terminating loop. Usually this is indicated by lots of log messages of the form "[INFO]: [NNNN]" which indicate a new page has been started or box overflows. After some time, FOP will crash with an OutOfMemoryException.
If you called the FOP command line application from some other program, for example from Java using Runtime.exec(), it may hang while trying to write log entries to the output pipe. You have to read the FOP output regularly to empty the pipe buffer. It is best to avoid exec'ing FOP, use the library interface instead.
There is something too large to fit into the intended place, usually a large image, a table whose rows are kept together or a block with a space-before or space-after larger than the page size. Catch the first page showing this phenomenon and check it. If it is not obvious which element causes the trouble, remove stuff until the problem goes away. Decrease the dimensions of the offending element or property, or increase the dimension of the enclosing element or container, or remove keep-with-* properties.
The src attribute of the fo:external-graphics element requires a URI, not a file name. See External Resources for more information about specifying URIs.
Did you get: “Failed to read font metrics file C:\foo\arial.xml : File "C:\foo\arial.xml" not found”? The value for the metrics-file attribute in the user config file is actually an URL, not a file name. Use "file:///C:/foo/arial.xml" instead.
If you used a relative URL, make sure your application has the working directory you expect. Currently FOP does not use the baseDir for resolving relative URLs pointing to font metric files.
Try also setting the font-base configuration.
The full exception usually looks similar to this:
This exception is usually a follow-up error after another exception. Sometimes
the original exception gets swallowed by Xalan's default ErrorListener
(should be fixed in the latest Xalan release).
The work-around is to set an explicit ErrorListener on the
Transformer. The ErrorListener can be as simple as this:
This message is a warning that FOP failed to read from the Font cache. Which means any Font auto detection or Font directories will be re-scanned. So this failure doesn't break anything.
To avoid the warning you can simply delete the old Font Cache file, which lives in ${base}\conf\font.cache (see font-base configuration). Or you can disable Font Caching altogether using the option "use-cache."
Leaders still work, in fact they work better than ever
before. You'll just have to add text-align="justify" and/or
text-align-last="justify" to the block with the leader. Be
sure you haven't accidentally overridden the
leader-length.maximum="100%" default value.
Earlier versions of FOP used to expand a leader to fill the rest of the line unconditionally, anything following it, like page numbers in a TOC, was actually shifted beyond the right margin.
The new implementation uses leader-length.optimum to determine where to break the line, and expands the leader only further if the line should be filled, as indicated by the text-align and text-align-last properties.
Actually due to the fuzzyness of the specification both the old and the new method are conformant (although adding text after the expanded leader in the old variant never was).
If you want to have a longer ruler or space in a non-justified line, you have to increase the leader-length.optimum property.
This is because spec conformance has been improved.
The force-page-count
property controls how a FO processor pads page sequences in
order to get certain page counts or last page numbers. The default is
"auto". With this setting, if the next page sequence
begins with an odd page number because you set the
initial-page-number, and the current page sequence also ends with an
odd page number, the processor inserts a blank page to keep odd and
even page numbers alternating (similar for the case the current page
sequence ends with an even page number and the next page sequence
starts with an even page number).
If you don't want to have this blank page, use
force-page-count="no-force".
Most commonly, the external file is not being found by FOP. Check the following:
Other possibilities:
See FOP Graphics Formats for a list of supported graphics formats and related issues.
See Graphics Resolution.
Current FOP releases have extensive support for these properties. The current release, FOP 1.0, still supports the values "always" and "never" only, no numerical values. There may be a few places where keep-* still don't work, this should be very rare.
The concept is called “blind table”. The table is used for pure layout reasons and is not obvious in the output.
An example of an image and the image caption to be kept together:
Consider upgrading to the latest version which supports keeps.
Check for fo:table-body around the rows. Usually FOP will catch this problem.
Also, the fo:table-with-caption element is not implemented, tables
within such an element are dropped too. FOP generates an error
message for this problem. Older DocBook style sheets generate
fo:table-with-caption elements, so watch out.
Since the overflow property doesn't apply to table-cell, you
can wrap the cell content in a block-container and specify
overflow="hidden" there. Alternatively,
if you have long words overflowing table cells, try to
get them hyphenated. Artificial names like product identifications or
long numbers usually aren't hyphenated. You can try special processing
at XSLT level, like
Check the XSL FAQ and the XSL list archive for how to perform these tasks.
You probably have keep-together="always" set on the table cell. See next question.
keep-together="always"
is set on table cellsSupport for inline-level keeps has been added in FOP 0.95, and setting
keep-together="always" also implicitly sets
keep-together.within-line="always", which forbids FOP
to break the text into multiple lines. Set
keep-together.within-column="always" on table-cell instead. It’s a good idea
not to use the shorthand keep-together="always" at all!
This is usually caused by setting a "height" on a table-row or table-cell and when the content is higher than the specified height. By setting "height" (a so-called corresponding property) you implicitely set block-progression-dimension.minimum, block-progression-dimension.optimum and block-progression-dimension.maximum to the same value. You'll get some information about that in the warning message. Look for something like: "MinOptMax[min=opt=max=14000]".
Assuming you set the height on the table-row to 14pt and your content is 75pt high, a constraint (maximum=14pt) is violated. Normally, you just want to make sure with the "height" property that the row has a minimum height. If that is so, the right solution is to specify block-progression-dimension.minimum="14pt" instead of height="14pt".
This happens for fo:page-number-citation elements if the
citation occurs before FOP formatted the requested page,
usually in TOC or index pages. It is caused by the problem
that FOP has to guess how much space the yet unknown page
number will occupy, and usually the guesses are somewhat
off.
The most recent FOP releases should have this problem fixed. Check whether you can upgrade.
Make sure you have set the language and optionally the country attributes for an appropriate XSL-FO element (fo:page-sequence, fo:block or fo:character):
See Hyphenation Support for details and instructions on using hyphenation with FOP.
Explicitly enable hyphenation for an appropriate XSL-FO element (fo:block, fo:character):
No, although you might easily think so. The problem has to do
with property inheritance of the start-indent and end-indent
properties to which the margin properties are mapped. Apache
FOP strictly adheres to the XSL-FO specification here which many
other commercial FO implementations don't do to better meet end-user
expectations. You can make FOP behave like these if you set
setBreakIndentInheritanceOnReferenceAreaBoundary(true)
on the FOUserAgent. The better way is to reset start-indent
and end-indent to "0pt" on table-body or block-container.
For further details, please consult the
Wiki page on Indent Inheritance.
If you render the same document once to a PNG or TIFF and once into a PDF, the output may not be the same, i.e. line breaks are different or lines may have different heights. The reason for this: The Java2D-based renderers use the font subsystem of Java2D/AWT. The PDF and PS renderers use FOP's own font subsystem which provides much better font metrics than Java2D. These can lead to different layout decisions when the same document is rendered with different renderers. An alternative approach to fix this problem might be available but it hasn't been tested, yet. See also the notes on fonts in the various output formats.
See Using FOP in a Servlet.
See Using FOP in a Servlet with XSLT Transformation.
See Using FOP in a Servlet with XSLT Transformation.
Declare the fonts in the userconfig.xml file as usual.
See loading the user configuration file
for further details.
See Setting the Configuration Programmatically.
See Using a Configuration File in an Embedded App.
See Servlet Engines.
See Multithreading FOP.
See Placing SVG Text into PDF.
See FOP: Graphics (Batik).
Applies to older FOP versions and JDK 1.3 and older. That's because there is an AWT thread hanging around. The solution is to put a System.exit(0) somewhere.
This is really a "resolving relative URI" problem with some
twists. The problem is that the #stuff URL fragment
identifier is resolved within the current SVG document. So the
reference must be valid within the XML subset and it cannot
reference other SVG documents in the same XML file. Some options
to try:
fill="url(file:///c:/refstuff/grad.svg#PurpleToWhite)".
fill="url(grad.svg#PurpleToWhite)". This may be easier
to deploy.
In any case, the referenced stuff has to be pointed to by an URL. It doesn't necessarily have to be a file URL, HTTP should also work. Also, expect a performance hit in all cases, because another XML file has to be retrieved and parsed.
Ultimately, both FOP and especially Batik should be fixed to make your code work as expected, but this will not only take some time but also some effort by a standard committee in order to make the semantics of this kind of references in embedded SVG clearer.
See also MalformedURLException
See SVG Scaling.
This phenomenon is not a bug in FOP, but rather in the dependent packages: Apache Batik, Apache Xalan-J and SAXON. The bug in Apache Batik will be fixed in the next release. In the latest release of Apache Xalan-J, the bug is already fixed. It only occurs in the Xalan version bundled with Sun's JVM, because Sun uses a rather old version.
Bug description: In a namespace-enabled Level 3 DOM, an attribute in the default namespace must be set with
"null" as the value for the namespace URI. SAX, on the other side, uses an empty string ("") to designate
the default namespace. Many packages appear to not properly handle this difference in which case they still use the empty
string as the namespace URI parameter for org.w3c.dom.Element.setAttributeNS().
Work-around: Use the latest version of Apache Xalan-J. Note that starting with JDK 1.4 it's not enough to replace Xalan-J
on the normal application classpath and you need to override the Xalan-J version bundled with the Sun JVM using the
Endorsed Standards Override Mechanism, i.e.
you must place Xalan-J in the "lib/endorsed" directory of your JRE.
See the Fonts page for information about embedding fonts.
This usually means the selected font doesn't have a glyph for the character.
The standard text fonts supplied with Acrobat Reader have mostly glyphs for characters from the ISO Latin 1 character set. For a variety of reasons, even those are not completely guaranteed to work, for example you can't use the fi ligature from the standard serif font. Check the overview for the default PDF fonts.
If you use your own fonts, the font must have a glyph for the desired character. Furthermore the font must be available on the machine where the PDF is viewed or it must have been embedded in the PDF file. See embedding fonts.
For most symbols, it is better to select the symbol font explicitely, for example in order to get the symbol for the mathematical empty set, write:
The "#" shows up if the selected font does not define a glyph for the required character, for example if you try:
See PDF Post-processing.
See PDF Encryption. See also PDF Post-processing.
See Metadata.
See PDF Watermarks.
Check the paper size in Acrobat settings and the "fit to page" print setting. Contorted printing is often caused by a mismatched paper format, for example if the setting is "US Letter" but the PDF was made for A4. Sometimes also the printer driver interferes, check its settings too.
FOP supports the starting-state property of the XSL 1.1 fo:bookmark element which can be used for this. The color, font-style and font-weight properties on fo:bookmark-title are not yet supported, though.
This is a problem of Internet Explorer requesting the content several times. Please see the notes on Internet Explorer for more information.
It depends whether you mean "printing to a printer under control of the server" or "printing on the client's printer".
For the first problem, look at the print servlet in the FOP examples. You'll have to gather any printer settings in a HTML form and send it to the server.
For the second task, you can use some client side script to start Acrobat Reader in print mode, or use a Java applet based on the FOP print servlet. This depends heavily on the client installation and should not be relied on except in tightly controlled environments.
See also http://marc.theaimsgroup.com/?l=fop-dev&m=101065988325115&w=2
See XSL-FO Vertical Centering.
See XSL-FO Horizontal Centering (Tables).
See Recto/Verso Static Content Differences.
See Recto/Verso Static Content Differences.
See Making the First Page Special.
See Blank Pages.
See Special Characters.
See Preformatting Content.
See Total Document Pages.
See Aligning Regions.
See Drawing Lines.
See Validating XSL-FO.
.See XML Special Characters.
ü, which work in HTML. See XML Special Characters.
See Using HTML Character Names.
See XML Encoding Issues.
See Current Date and Time.
You will get better results if you transform your source XML directly into XSLFO. It is tempting to use the XML->XHTML->XSLFO approach, because this apparently means there's only one transformation to maintain, but XHTML and publishing grade PDF are dissimilar enough that an "generic" XHTML->XSLFO(PDF) usually wont cut it, because the XHTML already lacks information from the original XML. It may be worthwhile to go from the source XML to an intermediate custom XML which on one hand is close enough to representation to allow simple transformation to either XHTML or XSLFO for most of the structure, but on the other hand retains enough semantic from the original XML that elements which must be handled differently in the two representations can be handled differently. Setting this up requires experience and most likely extensive prototyping.
The FOP Resources page has links to a tool called html2fo which can be used to make such a transformation. In addition, there are tools on the Antenna House XSL-FO Tutorial and Sample page.
See FOP Doc Management. ;-)
See the Bugs page for information about bugs already reported and how to report new ones.