Case Book Formatters

A formatter provides new export options for case books. Using the plug-in architecture, formatters can be packaged in easy to install plug-in bundles.

How Format Selection Works

When the Export command is executed on a case book, the FormatterFactory is queried for a list of currently registered formatters. If there is only one class registered (the built-in FormatHTML formatter), it is chosen implicitly and the user is prompted to choose a file. If there are multiple classes registered, the user is presented with a list whose entries are based upon the names returned by getExportName(). Once an export format is selected, the user is prompted to choose a file based upon the extension returned by getExportFileExtension(). Finally, the selected formatter will be instantiated, used to format the case book, and then asked to write the results to an output stream created from the selected file.

Creating New Case Book Formatters

A case book formatter extends ca.cgjennings.apps.arkham.casebook.Formatter. To be used as a formatter for exports, the formatter must implement isExportFormatter() (to return true), as well as getExportName() and getExportFileExtension(), and it must override exportFormat( OutputStream out ). (It is exportFormat that is finally called to generate a data stream in the appropriate file format.)

If you can convert to the desired format from HTML, you may find it convenient to extend the built-in FormatHTML class. This class is already a valid export formatter, although you should still customize the name, and possibly the extension. Override the exportFormat method to call getHTML(), transform HTML as desired, and then write out the result. (You can also base an exporter on the FormatPrint class, which is used to print case books and uses the SE mark-up and layout engine directly without converting to HTML. Note, however, that it is not an export formatter, so you must add appropriate implementations of all of the above methods.)

In order for SE to be aware of your formatter, its class must be registered by calling FormatterFactory.register( MyFormatter.class ), where MyFormatter.class is the class for your formatter. Formatter registration can be automated for the user by writing a plug-in to register the class and packaging it as a plug-in (or extension) bundle. See Example 1 for details.

The queryBeginExport Method

Starting with version 2.00 beta 2, SE supports the creation of case book formatters that may require more control over the export process or that might not be able to export to an OutputStream. To provide this support, the export process has been modified to proceed as follows:

1. The user selects the Export command and chooses the Formatter class from the list of registered formatters.
2. SE creates an instance of the formatter and uses it to format the case book.
3. SE looks for a method in the formatter that matches the signature public boolean queryBeginExport(). If this method exists, Strange Eons calls the method. At this point the formatter can gather additional options or handle the format job without using an output stream. If the method returns false, then SE will assume that the user either cancelled the export request or that the formatter has already completed the export task and the export ends. If the method returns true, or if the method does not exist, then SE will proceed to step 4 as normal.
4.  The user is prompted to choose a file, and if they do so then an OutputStream for the file is created and the formatter's exportFormat method is called to complete the export.

Examples

Documentation Index