1 <html xmlns="http://www.w3.org/1999/xhtml">
4 <basefont size="4" color="#2F4958" face="arial" />
6 <h1>Custom export filters</h1>
8 <p>JabRef allows you to define and
9 use your own export filters, in the same way as the standard
10 export filters are defined. An export filter is defined by one
11 or more <i>layout files</i>, which with the help of a
12 collection of built-in formatter routines specify the format of
13 the exported files. Your layout files must be prepared in a
14 text editor outside of JabRef.</p>
16 <h2>Adding a custom export filter</h2>
18 <p>The only requirement for
19 a valid export filter is the existence of a file with the
20 extension <b>.layout</b>. To add a new custom export filter,
21 open the dialog box <b>Options -> Manage custom exports</b>,
22 and click <b>Add new</b>. A new dialog box will appear,
23 allowing you to specify a name for the export filter (which
24 will appear as one of the choices in the File type dropdown
25 menu of the file dialog when you use the <b>File ->
26 Export</b> menu choice in the JabRef window), the path to the
27 <b>.layout</b> file, and the preferred file extension for the
28 export filter (which will be the suggested extension in the
29 file dialog when you use the export filter).</p>
31 <h2>Creating the export filter</h2>
33 <p>To see examples of how export filters are made, look for
34 the package containing the layout files for the standard
35 export filters on our download page.</p>
39 <p>Let us assume that we are creating an HTML export filter.</p>
41 <p>While the export filter only needs to consist of a single
42 <b>.layout</b> file, which in this case could be called
43 <i>html.layout</i>, you may also want to add two files called
44 <i>html.begin.layout</i> and <i>html.end.layout</i>. The former
45 contains the header part of the output, and the latter the
46 footer part. JabRef will look for these two files whenever the
47 export filter is used, and if found, either of these will be
48 copied verbatim to the output before or after the individual
49 entries are written.</p>
51 <p>Note that these files must reside in the same directory as
52 <i>html.layout</i>, and must be named by inserting
53 <b>.begin</b> and <b>.end</b>, respectively.</p>
55 <p>In our example export filter, these could look like the
58 <p><i>html.begin.layout</i>:<br />
59 <code><HTML><br />
60 <BODY> text="#275856"><br />
61 <basefont size="4" color="#2F4958"
62 face="arial"></code></p>
64 <p><i>html.end.layout</i>:<br />
65 <code></BODY><br />
66 </HTML></code></p>
68 <p>The file <i>html.layout</i> provides the <i>default</i>
69 template for exporting one single entry. If you want to use
70 different templates for different entry types, you can do this
71 by adding entry-specific <b>.layout</b> files. These must also
72 reside in the same directory as the main layout file, and are
73 named by inserting <b>.entrytype</b> into the name of the main
74 layout file. The entry type name must be in all lowercase. In
75 our example, we might want to add a template for book entries,
76 and this would go into the file <i>html.book.layout</i>. For a
77 PhD thesis we would add the file <i>html.phdthesis.layout</i>,
78 and so on. These files are similar to the default layout file,
79 except that they will only be used for entries of the matching
80 type. Note that the default file can easily be made general
81 enough to cover most entry types in most export filters.</p>
83 <h3>The layout file format</h3>
85 <p>Layout files are created using a
86 simple markup format where commands are identified by a
87 preceding backslash. All text not identified as part of a
88 command will be copied verbatim to the output file.</p>
90 <h3>Field commands</h3>
92 <p>An arbitrary word preceded by a backslash, e.g.
93 <code>\author</code>, <code>\editor</code>, <code>\title</code>
94 or <code>\year</code>, will be interpreted as a reference to
95 the corresponding field, which will be copied directly to the
98 <h3>Field formatters</h3>
100 <p>Often there will be a need for some preprocessing of the
101 field contents before output. This is done using a <i>field
102 formatter</i> - a java class containing a single method that
103 manipulates the contents of a field.</p>
105 <p>A formatter is used by inserting the <code>\format</code>
106 command followed by the formatter name in square braces, and
107 the field command in curly braces, e.g.:</p>
109 <p><code>\format[ToLowerCase]{\author}</code></p>
111 <p>You can also specify multiple formatters separated by
112 commas. These will be called sequentially, from left to right,
115 <p><code>\format[ToLowerCase,HTMLChars]{\author}</code></p>
117 <p>will cause the formatter <b>ToLowerCase</b> to be called
118 first, and then <b>HTMLChars</b> will be called to format the
119 result. You can list an arbitrary number of formatters in this
122 <p>The argument to the formatters, withing the curly braces,
123 does not have to be a field command. Instead, you can insert
124 normal text, which will then be passed to the formatters
125 instead of the contents of any field. This can be useful for
126 some fomatters, e.g. the CurrentDate formatter (described
129 <p>Some formatters take an extra argument, given in parentheses
130 immediately after the formatter name. The argument can be enclosed
131 in quotes, which is necessary if it includes the parenthesis characters.
132 For instance, <code>\format[Replace("\s,_")]{\journal}</code> calls
133 the <b>Replace</b> formatter with the argument <b>\s,_</b> (which results
134 in the "journal" field after replacing all whitespace by underscores).
137 <h2>Built-in export formatters</h2>
139 <p>JabRef provides the following set of formatters, some of
140 which depend on the others:</p>
144 <li><code>AuthorAbbreviator</code> or <code>AuthorLastFirstAbbreviator</code>
145 : abbreviates first and middle names of all authors. This formatter
146 returns names with the last name first. Follow this formatter with
147 AuthorFirstFirst to get abbreviated names with the initials first.</li>
149 <li><code>AuthorAndsCommaReplacer</code> : replaces "and"
150 between names with ",", and "&" between the last
153 <li><code>AuthorAndsReplacer</code> : replaces "and"
154 between names with ";", and "&" between the last
157 <li><code>AuthorFirstFirst</code> : formats author/editor
158 fields with the first names first.</li>
160 <li><code>AuthorFirstFirstCommas</code> or <code>AuthorFirstLastCommas</code>
161 : formats author/editor fields with the first names first, delimited by
162 commas, with "and" between the last two names.</li>
164 <li><code>AuthorFirstLastOxfordCommas</code> : similar
165 to <code>AuthorFirstLastCommas</code>, except that the "and"
166 between the last two names is preceded by a comma.</li>
168 <li><code>AuthorFirstAbbrLastCommas</code> : formats
169 author/editor fields with abbreviated first names first, delimited by
170 commas, with "and" between the last two names.</li>
172 <li><code>AuthorFirstAbbrLastOxfordCommas</code> : similar
173 to <code>AuthorFirstAbbrLastCommas</code>, except that the "and"
174 between the last two names is preceded by a comma.</li>
176 <li><code>AuthorLastFirst</code> : formats author/editor
177 fields with the last names first.</li>
179 <li><code>AuthorLastFirstAbbrCommas</code> : formats
180 author/editor fields with last names first and abbreviated first names
181 last, delimited by commas, with "and" between the last two names.</li>
183 <li><code>AuthorLastFirstAbbrOxfordCommas</code> : similar
184 to <code>AuthorLastFirstAbbrCommas</code>, except that the "and"
185 between the last two names is preceded by a comma.</li>
187 <li><code>AuthorLastFirstCommas</code> : formats
188 author/editor fields with the last names first, delimited by
189 commas, with "and" between the last two names.</li>
191 <li><code>AuthorLastFirstOxfordCommas</code> : similar
192 to <code>AuthorLastFirstCommas</code>, except that the "and"
193 between the last two names is preceded by a comma.</li>
195 <li><code>AuthorNatBib</code> : formats author names in
196 NatBib style, with last names only, separating names by
197 "and" if there are two authors, and giving the first author
198 followed by "et al." if there are more than two
201 <li><code>AuthorOrgSci</code> : first author is in "last,
202 first" all others in "first last". First names are
205 <li><code>CreateDocBookAuthors</code> : formats the author
206 field in DocBook style.</li>
208 <li><code>CreateDocBookEditors</code> : to be
211 <li><code>CurrentDate</code> : outputs the current date.
212 With no argument, this formatter outputs the current date
213 and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time
214 and time zone). By giving a different format string as
215 argument, the date format can be customized. E.g.
216 <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the
217 date only, e.g. 2005.11.30.</li>
219 <li><code>FileLink(filetype)</code> : if no argument is given, this formatter outputs
220 the first external file link encoded in the field. To work, the formatter must
221 be supplied with the contents of the "file" field.
222 <p>This formatter takes the name of an external file type as an optional argument,
223 specified in parentheses after the formatter name. For instance,
224 <code>\format[FileLink(pdf)]{\file}</code> specifies <code>pdf</code> as an
225 argument. When an argument is given, the formatter selects the first file
226 link of the specified type. In the example, the path to the first PDF link will
229 <li><code>FirstPage</code> : returns the first page from the "pages" field, if set.
230 For instance, if the pages field is set to "345-360" or "345--360",
231 this formatter will return "345".</li>
233 <li><code>FormatPagesForHTML</code> : replaces "--" with
236 <li><code>FormatPagesForXML</code> : replaces "--" with an
239 <li><code>GetOpenOfficeType</code> : returns the number used by the OpenOffice.org
240 bibliography system (versions 1.x and 2.x) to denote the type of this entry.</li>
242 <li><code>HTMLChars</code> : replaces TeX-specific special
243 characters (e.g. {\^a} or {\"{o}}) with their HTML
244 representations, and translates LaTeX commands \emph, \textit,
245 \textbf into HTML equivalents.</li>
247 <li><code>HTMLParagraphs</code> : interprets two
248 consecutive newlines (e.g. \n \n) as the beginning of a new
249 paragraph and creates paragraph-html-tags accordingly.</li>
251 <li><code>LastPage</code> : returns the last page from the "pages" field, if set.
252 For instance, if the pages field is set to "345-360" or "345--360",
253 this formatter will return "360".</li>
255 <li><code>NoSpaceBetweenAbbreviations</code> : spaces
256 between multiple abbreviated first names are removed.</li>
258 <li><code>RemoveBrackets</code> : removes all curly
259 brackets "{" or "}".</li>
261 <li><code>RemoveBracketsAddComma</code> : to be
264 <li><code>RemoveLatexCommands</code> : removes LaTeX
265 commands like <code>\em</code>, <code>\textbf</code>, etc.
266 If used together with <code>HTMLChars</code> or
267 <code>XMLChars</code>, this formatter should be called
270 <li><code>RemoveTilde</code> : replaces the tilde character
271 used in LaTeX as a non-breakable space by a regular space.
272 Useful in combination with the NameFormatter discussed in
273 the next section.</li>
275 <li><code>RemoveWhitespace</code> : removes all whitespace characters.</li>
277 <li><code>Replace(regexp,replacewith)</code> : does a regular expression replacement.
278 To use this formatter, a two-part argument must be given. The parts are
279 separated by a comma. To indicate the comma character, use an escape
280 sequence: \,<br> <br>
281 The first part is the regular expression to search for. The regular expression
282 is written normally, without extra escape sequences for backslashes. A description
283 of Java regular expressions can be found at:<br>
284 http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html
286 The second part is the text to replace all matches with.</li>
288 <li><code>RTFChars</code> : replaces TeX-specific special
289 characters (e.g. {\^a} or {\"{o}}) with their RTF
290 representations, and translates LaTeX commands \emph, \textit,
291 \textbf into RTF equivalents.</li>
293 <li><code>ToLowerCase</code> : turns all characters into
296 <li><code>ToUpperCase</code> : turns all characters into
299 <li><code>WrapContent</code> : This formatter outputs the input value after adding a
300 prefix and a postfix, as long as the input value is non-empty. If the input value
301 is empty, an empty string is output (the prefix and postfix are not output in this case).
302 The formatter requires an argument containing the prefix and postix separated
303 by a comma. To include the comma character in either, use an escape sequence
306 <li><code>WrapFileLinks</code> : See below.</li>
308 <li><code>XMLChars</code> : replaces TeX-specific special
309 characters (e.g. {\^a} or {\"{o}}) with their XML
310 representations.</li>
316 <h3>The <code>WrapFileLinks</code> formatter</h3>
318 This formatter iterates over all file links, or all file links of a specified
319 type, outputting a format string given as the first argument. The format string
320 can contain a number of escape sequences indicating file link information to
321 be inserted into the string.
323 This formatter can take an optional second argument specifying the name of a file
324 type. If specified, the iteration will only include those files with a file type
325 matching the given name (case-insensitively). If specified as an empty argument,
326 all file links will be included.
328 After the second argument, pairs of additional arguments can be added in order to
329 specify regular expression replacements to be done upon the inserted link information
330 before insertion into the output string. A non-paired argument will be ignored.
331 In order to specify replacements without filtering on file types, use an empty second
334 The escape sequences for embedding information are as follows:
336 \i : This inserts the iteration index (starting from 1), and can be useful if
337 the output list of files should be enumerated.<br>
338 \p : This inserts the file path of the file link.<br>
339 \f : This inserts the name of the file link's type.<br>
340 \x : This inserts the file's extension, if any.<br>
341 \d : This inserts the file link's description, if any.<br>
343 For instance, an entry could contain a file link to the file "/home/john/report.pdf"
344 of the "PDF" type with description "John's final report".
346 Using the WrapFileLinks formatter with the following argument:
348 \format[WrapFileLinks(\i. \d (\p))]{\file}
350 would give the following output:<br>
351 <pre>1. John's final report (/home/john/report.pdf)</pre>
353 If the entry contained a second file link to the file "/home/john/draft.txt" of the
354 "Text file" type with description 'An early "draft"', the output would be as follows:<br>
355 <pre>1. John's final report (/home/john/report.pdf)</pre>
356 <pre>2. An early "draft" (/home/john/draft.txt)</pre>
358 If the formatter was called with a second argument, the list would be filtered.
360 <pre>\format[WrapFileLinks(\i. \d (\p),,text file)]{\file}</pre>
362 would show only the text file:<br>
363 <pre>1. An early "draft" (/home/john/draft.txt)</pre>
365 If we wanted this output to be part of an XML styled output, the quotes in the
366 file description could cause problems. Adding two additional arguments to translate
367 the quotes into XML characters solves this:<br>
368 \format[WrapFileLinks(\i. \d (\p),,text file,",")]{\file}
370 would give the following output:<br>
371 <pre>1. An early "draft" (/home/john/draft.txt)</pre>
372 <p/>Additional pairs of replacements could be added.
375 <h3>Custom formatters</h3>
377 <p>If none of the available formatters can do what you want to
378 achieve, you can add your own by implementing the
379 <code>net.sf.jabref.export.layout.LayoutFormatter</code>
380 interface. If you insert your class into the
381 <code>net.sf.jabref.export.layout.format</code> package, you
382 can call the formatter by its class name only, like with the
383 standard formatters. Otherwise, you must call the formatter by
384 its fully qualified name (including package name). In any case,
385 the formatter must be in your classpath when running
388 <h2><a name="NameFormatter"
389 id="NameFormatter">Using Custom Name Formatters</a></h2>
391 <p>From JabRef 2.2, it is possible to define custom name
392 formatters using the bibtex-sty-file syntax. This allows
393 ultimate flexibility, but is a cumbersome to write</p>
395 <p>You can define your own formatter in the preference tab
396 "Name Formatter" using the following format and then use it
397 with the name given to it as any other formatter</p>
398 <code><case1>@<range11>@<format>@<range12>@<format>@<range13>...@@<br />
400 <case2>@<range21>@... and so on.</code>
402 <p>This format first splits the task to format a list of author
403 into cases depending on how many authors there are (this is
404 since some formats differ depending on how many authors there
405 are). Each individual case is separated by @@ and contains
406 instructions on how to format each author in the case. These
407 instructions are separated by a @.</p>
409 <p>Cases are identified using integers (1, 2, 3, etc.) or the
410 character * (matches any number of authors) and will tell the
411 formatter to apply the following instructions if there are a
412 number of less or equal of authors given.</p>
415 <code><integer>..<integer></code>,
416 <code><integer></code> or the character <code>*</code>
417 using a 1 based index for indexing authors from the given list
418 of authors. Integer indexes can be negative to denote them to
419 start from the end of the list where -1 is the last author.</p>
421 <p>For instance with an authorlist of "Joe Doe and Mary Jane
422 and Bruce Bar and Arthur Kay":</p>
425 <li>1..3 will affect Joe, Mary and Bruce</li>
427 <li>4..4 will affect Arthur</li>
429 <li>* will affect all of them</li>
431 <li>2..-1 will affect Mary, Bruce and Arthur</li>
434 <p>The <code><format></code>-strings use the Bibtex
435 formatter format:</p>
437 <p>The four letters v, f, l, j indicate the name parts von,
438 first, last, jr which are used within curly braces. A single
439 letter v, f, l, j indicates that the name should be
440 abbreviated. If one of these letters or letter pairs is
441 encountered JabRef will output all the respective names
442 (possibly abbreviated), but the whole expression in curly
443 braces is only printed if the name part exists.</p>
445 <p>For instance if the format is "{ll} {vv {von Part}} {ff}"
446 and the names are "Mary Kay and John von Neumann", then JabRef
447 will output "Kay Mary" (with two space between last and first)
448 and "Neuman von von Part John".</p>
450 <p>I give two examples but would rather point you to the bibtex
453 <p>Small example: <code>"{ll}, {f.}"</code> will turn
454 <code>"Joe Doe"</code> into <code>"Doe, J."</code></p>
456 <p>Large example:</p>
461 <p><code>"Joe Doe and Mary Jane and Bruce Bar and Arthur
466 <p><code>"Doe, J., Jane, M., Bar, B. and Kay,
471 <p><code>1@*@{ll}, {f}.@@2@1@{ll}, {f}.@2@ and {ll},
472 {f}.@@*@1..-3@{ll}, {f}., @-2@{ll}, {f}.@-1@ and {ll},
476 <p>If somebody would like to write a better tutorial about
477 this: Write a mail to one of the JabRef mailinglists!</p>
479 <h3>Conditional output</h3>
481 <p>Some static output might only make
482 sense if a specific field is set. For instance, say we want to
483 follow the editor names with the text <code>(Ed.)</code>. This
484 can be done with the following text:</p>
486 <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor}
489 <p>However, if the <code>editor</code> field has not been set -
490 it might not even make sense for the entry being exported - the
491 <code>(Ed.)</code> would be left hanging. This can be prevented
492 by instead using the <code>\begin</code> and <code>\end</code>
495 <p><code>\begin{editor}<br />
496 \format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)<br />
497 \end{editor}</code></p>
499 <p>The <code>\begin</code> and <code>\end</code> commands make
500 sure the text in between is printed if and only if the field
501 referred in the curly braces is defined for the ently being
504 <p><b>Note:</b> Use of the <code>\begin</code> and
505 <code>\end</code> commands is a key to creating layout files
506 that work well with a variety of entry types.</p>
508 <h3>Grouped output</h3>
510 <p>If you wish to separate your entries
511 into groups based on a certain field, use the grouped output
512 commands. Grouped output is very similar to conditional output,
513 except that the text in between is printed only if the field
514 referred in the curly braces has changed value.</p>
516 <p>For example, let's assume I wish to group by keyword. Before
517 exporting the file, make sure you have sorted your entries
518 based on keyword. Now use the following commands to group by
521 <p><code>\begingroup{keywords}New Category:
522 \format[HTMLChars]{\keywords}<br />
523 \endgroup{keywords}</code></p>
525 <h2>Sharing your work</h2>
527 <p>With external layout files, it's
528 fairly simple to share custom export formats between users. If
529 you write an export filter for a format not supported by
530 JabRef, or an improvement over an existing one, we encourage
531 you to post your work on our SourceForge.net page. The same
532 goes for formatter classes that you write. We'd be happy to
533 distribute a collection of submitted layout files, or to add to
534 the selection of standard export filters and formatters.</p>
536 <p>Starting with JabRef 2.4b1 you can also package your
537 ExportFormat or LayoutFormatter as a plug-in. If you do so,
538 you can provide a single zip-file to other user to make use
539 of your ExportFormat. For an example download the JabRef
540 source release and have a look at the directory
541 <code>src/plugins/</code>. Don't hesitate to stop by the
542 forums on Sourceforge, since we don't have extensive documentation, yet.</p>