Custom export filters

JabRef allows you to define and use your own export filters, in the same way as the standard export filters are defined. An export filter is defined by one or more layout files, which with the help of a collection of built-in formatter routines specify the format of the exported files. Your layout files must be prepared in a text editor outside of JabRef.

Adding a custom export filter

The only requirement for a valid export filter is the existence of a file with the extension .layout. To add a new custom export filter, open the dialog box Options -> Manage custom exports, and click Add new. A new dialog box will appear, allowing you to specify a name for the export filter (which will appear in the File -> Custom export menu of the JabRef window), the path to the .layout file, and the preferred file extension for the export filter (which will be the suggested extension in the file dialog when you use the export filter).

Creating the export filter

To see examples of how export filters are made, look for the package containing the layout files for the standard export filters on our download page.

Layout files

Let us assume that we are creating an HTML export filter.

While the export filter only needs to consist of a single .layout file, which in this case could be called html.layout, you may also want to add two files called html.begin.layout and html.end.layout. The former contains the header part of the output, and the latter the footer part. JabRef will look for these two files whenever the export filter is used, and if found, either of these will be copied verbatim to the output before or after the individual entries are written.

Note that these files must reside in the same directory as html.layout, and must be named by inserting .begin and .end, respectively.

In our example export filter, these could look like the following:

html.begin.layout:
<HTML> <BODY> text="#275856"> <basefont size="4" color="#2F4958" face="arial">

html.end.layout:
</BODY> </HTML>

The file html.layout provides the default template for exporting one single entry. If you want to use different templates for different entry types, you can do this by adding entry-specific .layout files. These must also reside in the same directory as the main layout file, and are named by inserting .entrytype into the name of the main layout file. The entry type name must be in all lowercase. In our example, we might want to add a template for book entries, and this would go into the file html.book.layout. For a PhD thesis we would add the file html.phdthesis.layout, and so on. These files are similar to the default layout file, except that they will only be used for entries of the matching type. Note that the default file can easily be made general enough to cover most entry types in most export filters.

The layout file format

Layout files are created using a simple markup format where commands are identified by a preceding backslash. All text not identified as part of a command will be copied verbatim to the output file.

Field commands

An arbitrary word preceded by a backslash, e.g. \author, \editor, \title or \year, will be interpreted as a reference to the corresponding field, which will be copied directly to the output.

Field formatters

Often there will be a need for some preprocessing of the field contents before output. This is done using a field formatter - a java class containing a single method that manipulates the contents of a field.

A formatter is used by inserting the \format command followed by the formatter name in square braces, and the field command in curly braces, e.g.:

\format[ToLowerCase]{\author}

You can also specify multiple formatters separated by commas. These will be called sequentially, from left to right, e.g.

\format[ToLowerCase,HTMLChars]{\author}

will cause the formatter ToLowerCase to be called first, and then HTMLChars will be called to format the result. You can list an arbitrary number of formatters in this way.

JabRef provides the following set of formatters, some of which depend on the others:

HTMLChars : replaces TeX-specific special characters (e.g. {\^a} or {\"{o}}) with their HTML representations.
XMLChars : replaces TeX-specific special characters (e.g. {\^a} or {\"{o}}) with their XML representations.
CreateDocBookAuthors : formats the author field in DocBook style.
AuthorFirstFirst : formats author/editor fields with the first names first.
AuthorLastFirst : formats author/editor fields with the last names first.
FormatPagesForHTML : replaces "--" with "-".
FormatPagesForXML : replaces "--" with an XML en-dash.
RemoveBrackets : removes all curly brackets "{" or "}".
RemoveLatexCommands : removes LaTeX commands like \em, \textbf, etc. If used together with HTMLChars or XMLChars, this formatter should be called last.
ToLowerCase : turns all characters into lower case.

If none of the available formatters can do what you want to achieve, you can add your own by implementing the net.sf.jabref.export.layout.LayoutFormatter interface. If you insert your class into the net.sf.jabref.export.layout.format package, you can call the formatter by its class name only, like with the standard formatters. Otherwise, you must call the formatter by its fully qualified name (including package name). In any case, the formatter must be in your classpath when running JabRef.

Conditional output

Some static output might only make sense if a specific field is set. For instance, say we want to follow the editor names with the text (Ed.). This can be done with the following text:

\format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)

However, if the editor field has not been set - it might not even make sense for the entry being exported - the (Ed.) would be left hanging. This can be prevented by instead using the \begin and \end commands:

\begin{editor} \format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.) \end{editor}

The \begin and \end commands make sure the text in between is printed if and only if the field referred in the curly braces is defined for the ently being exported.

Note: Use of the \begin and \end commands is a key to creating layout files that work well with a variety of entry types.

Sharing your work

With external layout files, it's fairly simple to share custom export formats between users. If you write an export filter for a format not supported by JabRef, or an improvement over an existing one, we encourage you to post your work on our SourceForge.net page. The same goes for formatter classes that you write. We'd be happy to distribute a collection of submitted layout files, or to add to the selection of standard export filters and formatters.