This page describes all extension points inside FOP.

The Extension Points

Additional Renderers

Non-standard Renderers can be used by setting FOUserAgent.setRendererOverride(Renderer).

Future: Renderers will be discovered through the Service class and accessible through their supporting MIME type.

Additional FO Event Handlers

Non-standard FO Event Handlers can be used by setting FOUserAgent.setFOEventHandlerOverride(FOEventHandler).

Future: FOEventHandlers will be discovered through the Service class and accessible through their supporting MIME type.

Hyphenation Patterns

Compiled hyphenation pattern files will automatically be detected and available if they are in a /hyph directory inside a JAR that's in the classpath.

Foreign XML Extensions

Examples are SVG, MathML, Barcode4J. They define descendants of XMLObj in a special namespace. The foreign XML can be used inside fo:instream-foreign-object elements. The different XML elements supported by the extensions are exposed through an ExtensionElementMapping descendant which is discovered through the Service class.

Unlike in FOP 0.20.5 the extension cannot directly create areas which paint themselves with help of a renderer anymore. The extension element can only do direct conversions to SVG, for example. The current MathML and Plan extensions are good examples. The generated SVG will be available to the InstreamForeignObjectLM through the XMLObj descendant which then just transfers the DOM Document to an ForeignObject area (inline-level).

The actual painting/rendering of the foreign XML is handled by an XMLHandler descendant. PDFSVGHandler, for example, knows how to call Batik to paint SVG to the output format. So, instead of converting the foreign XML inside the extension element into SVG, the extension can provide an XMLHandler descendant which knows how to render the foreign XML to the output format with the help of the active renderer. The extension needs to provide one XMLHandler per output format. An example here would be Barcode4J which will be able to paint the barcode XML directly as EPS graphic for the PSRenderer which is much more performant than going through SVG/Batik.

Functionality Extensions to XSL-FO

Through the same basic mechanism as for foreign XML extensions it is possible to specify elements outside the XSL-FO namespace and outside an fo:instream-foreign-object. Until recently the PDF Outline extension used this facility. Now this is done directly through the support of the equivalent XSL 1.1 feature. For FOP Trunk we currently don't have any such extensions as examples. The problem with these extensions is that they are not really dynamically loadable extensions since support for them has to be hard-coded into the FOP source code, especially the FO tree. At least, that will be so in many cases.

It is theoretically possible to supply a special layout manager for an extension element. This can be done through FOUserAgent.setLayoutManagerMakerOverride(). It is unlikely, however, that anyone has used this facility, yet. If you have, please let us know.

ExtensionAttachment facility

This is a special case of an extension that provides elements outside the XSL-FO namespace and outside of fo:instream-foreign-object. An extension element working with this facility overrides the FONode.getExtensionAttachment(). The ExtensionAttachment objects returned will be attached to a special list on their parent formatting object. These objects can be used by layout managers (standard or custom) to provide additional functionality. The main idea, though, is that they get passed into the area tree where the renderers can access them and provide additional functionality without changing FOP's source code. An example of the first extension using this facility is found in ExtensionsForPostScript.

Another possible example that could be implemented is XMP (Extensible Metadata Platform) support for PDF. Metadata could be specified as child of the fo:declarations element. The metadata will not be processed by the layout managers but it would need to be attached to the area tree so a PDF Renderer could take this DOM Document and embed the metadata as XMP (Extensible Metadata Platform) stream in the PDF.

Validation can be performed in the extension elements to signal under which FO elements they are allowed.

Since there are not always 1:1 mappings between FO element, layout manager and area tree objects there will be certain restrictions to the overall facility. Please note, that the ability to pass ExtensionAttachments through the area tree is not implemented, yet.

Ideas for the future

Extension Attributes on existing FO Elements

We might want to support extension attributes for certain FO elements, thus extending the functionality of an existing XSL-FO element. An example could be fo:external-graphic and fo:instream-foreign-object on which we could allow an fox:rendering="as-bitmap" value. This could force the XMLHandler to render the foreign XML in bitmap format instead of rendering it in the native output format. This could also be done, at least partly, through the ExtensionAttachment facility described above.

Plug-ins into renderers

We could provide plug-in facilities into certain renderers, if subclassing them is not enough to fulfill the users' needs.

  • No labels