Apache FOP™: Ant task
Apache FOP™ provides an Ant task for automating the document build process.
Description
The FOP Ant task will convert XSL-FO documents to PDF, PS, PCL etc. output (see Output formats for available formats).
To call FOP tasks within Ant, first add a FOP task definition to your Ant build file. One method of defining the task is as follows:
<property name="fop.home" value="....path to your FOP HOME directory..."/>
<taskdef name="fop"
classname="org.apache.fop.tools.anttasks.Fop">
<classpath>
<fileset dir="${fop.home}/lib">
<include name="*.jar"/>
</fileset>
<fileset dir="${fop.home}/build">
<include name="fop.jar"/>
<include name="fop-hyph.jar" />
</fileset>
</classpath>
</taskdef>
Then create FOP tasks within your Ant build file, using the FOP task parameters listed below.
Parameters for FOP Ant task
Parameters specified as attributes
| Attribute |
Description |
Required |
| fofile |
XSL-FO file to be rendered |
Yes, if no fileset nested element is used |
| xmlfile |
XML input file |
Yes, if no fofile is specified |
| xsltfile |
XSLT input file |
Yes, if no fofile is specified |
| outfile |
Output filename |
Yes, when fofile is used. (This attribute is not valid for filesets.) |
| format |
Possible output formats:
application/X-fop-awt-preview
application/X-fop-print
application/X-fop-areatree
application/pdf
application/postscript
application/mif
application/rtf, text/richtext, text/rtf
application/x-pcl, application/vnd.hp-PCL
application/x-afp, application/vnd.ibm.modcap
text/plain
image/svg+xml
image/gif
image/png
image/tiff
|
No, defaults to application/pdf |
| outdir |
Output directory |
Required if a fileset is used to specify the files to render; optional for fofile. (Can alternatively specify the full path in the fofile value.) |
| force |
Recreate target files, even if they are newer than their corresponding source files. Note: This attribute is available in post-0.20.5 versions (0.20.x nightly build and 1.0dev) only; target files are always generated (i.e., force=true) in 0.20.5 release. |
No, default is false |
| basedir |
Base directory to resolve relative references (e.g., graphics files) within the FO document. |
No, for single FO File entry, default is to use the location of that FO file. |
| relativebase |
For fileset usage only. A value of true specifies using the location of each .fo file as the base directory for resolving relative file references located within that .fo file. A value of false specifies using the value of basedir for all files within the fileset, or just the current working directory if basedir is not specified. |
No, default is false. |
| userconfig |
User configuration file (same as the FOP "-c" command line option). |
No |
| messagelevel |
Logging level
Possible values: error, warn, info, verbose, debug. Currently doesn't work in FOP Trunk!!! |
No, defaults to verbose |
| logFiles |
Controls whether the names of the files that are processed are logged (true) or not (false). Currently doesn't work in FOP Trunk!!! |
No, default is true |
| throwexceptions |
Controls whether or not an exception is thrown if an error occurs during rendering. |
Default is true |
Parameters specified as nested elements
| Attribute |
Description |
Required |
| fileset |
FileSets are used to specify multiple XSL-FO files to be rendered. |
Yes, if no fofile attribute is supplied |
Examples
The following example converts a single XSL-FO file to a PDF document:
<target name="generate-pdf" description="Generates a single PDF file">
<fop format="application/pdf"
fofile="c:\working\foDirectory\foDocument.fo"
outfile="c:\working\pdfDirectory\pdfDocument.pdf" />
</target>
This example converts all XSL-FO files within an entire directory to PostScript:
<target name="generate-multiple-ps"
description="Generates multiple PostScript files">
<fop format="application/postscript"
outdir="${build.dir}" messagelevel="debug">
<fileset dir="${fo.examples.dir}">
<include name="*.fo"/>
</fileset>
</fop>
</target>
The following example transforms and converts a single XML and XSLT file to an AFP document:
<target name="generate-afp-from-transform" description="Generates a single AFP file from an XSLT stylesheet">
<fop format="application/x-afp"
xmlfile="c:\working\foDirectory\Document.xml"
xsltfile="c:\working\foDirectory\Document.xslt"
outfile="c:\working\afpDirectory\Document.afp" />
</target>
This example transforms and converts all XML files within an entire directory to PostScript:
<target name="generate-multiple-ps-from-transform" description="Generates multiple PostScript files using an XSLT stylesheet">
<fop format="application/postscript"
xsltfile="c:\working\foDirectory\Document.xslt"
outdir="${build.dir}" messagelevel="debug">
<fileset dir="${test.dir}">
<include name="*.xml"/>
</fileset>
</fop>
</target>