The Apache FOP Project

The Apache™ FOP Project

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>