| Title: Apache(tm) FOP: Ant task |
| |
| #Apache™ FOP: Ant task |
| |
| |
| Apache™ FOP provides an Ant task for automating the document build process. |
| |
| ## Description { #basics} |
| |
| The FOP Ant task will convert XSL-FO documents to PDF, PS, PCL etc. output (see [Output formats](output.html) 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: |
| |
| :::xml |
| <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} |
| |
| <caption>Parameters specified as attributes</caption> |
| |
| | 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:<br></br> `application/X-fop-awt-preview` <br></br> `application/X-fop-print` <br></br> `application/X-fop-areatree` <br></br> `application/pdf` <br></br> `application/postscript` <br></br> `application/mif` <br></br> `application/rtf`, `text/richtext`, `text/rtf` <br></br> `application/x-pcl`, `application/vnd.hp-PCL` <br></br> `application/x-afp`, `application/vnd.ibm.modcap` <br></br> `text/plain` <br></br> `image/svg+xml` <br></br> `image/gif` <br></br> `image/png` <br></br> `image/tiff` <br></br> | 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<br></br>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` | |
| |
| <br/> |
| |
| <caption>Parameters specified as nested elements</caption>| Attribute | Description | Required | |
| |-----------|-------------|----------| |
| | fileset | [FileSets](https://ant.apache.org/manual/Types/fileset.html) are used to specify multiple XSL-FO files to be rendered. | Yes, if no fofile attribute is supplied | |
| |
| ## Examples { #examples} |
| |
| The following example converts a single XSL-FO file to a PDF document: |
| |
| :::xml |
| <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: |
| |
| :::xml |
| <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: |
| |
| :::xml |
| <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: |
| |
| :::xml |
| <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> |