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.
