1 <html xmlns="http://www.w3.org/1999/xhtml">
8 <h1>Custom export filters</h1>
10 <p>JabRef allows you to define and
11 use your own export filters, in the same way as the standard
12 export filters are defined. An export filter is defined by one
13 or more <i>layout files</i>, which with the help of a
14 collection of built-in formatter routines specify the format of
15 the exported files. Your layout files must be prepared in a
16 text editor outside of JabRef.</p>
18 <h2>Adding a custom export filter</h2>
20 <p>The only requirement for
21 a valid export filter is the existence of a file with the
22 extension <b>.layout</b>. To add a new custom export filter,
23 open the dialog box <b>Options -> Manage custom exports</b>,
24 and click <b>Add new</b>. A new dialog box will appear,
25 allowing you to specify a name for the export filter (which
26 will appear as one of the choices in the File type dropdown
27 menu of the file dialog when you use the <b>File ->
28 Export</b> menu choice in the JabRef window), the path to the
29 <b>.layout</b> file, and the preferred file extension for the
30 export filter (which will be the suggested extension in the
31 file dialog when you use the export filter).</p>
33 <h2>Creating the export filter</h2>
35 <p>To see examples of how export filters are made, look for
36 the package containing the layout files for the standard
37 export filters on our download page.</p>
41 <p>Let us assume that we are creating an HTML export filter.</p>
43 <p>While the export filter only needs to consist of a single
44 <b>.layout</b> file, which in this case could be called
45 <i>html.layout</i>, you may also want to add two files called
46 <i>html.begin.layout</i> and <i>html.end.layout</i>. The former
47 contains the header part of the output, and the latter the
48 footer part. JabRef will look for these two files whenever the
49 export filter is used, and if found, either of these will be
50 copied verbatim to the output before or after the individual
51 entries are written.</p>
53 <p>Note that these files must reside in the same directory as
54 <i>html.layout</i>, and must be named by inserting
55 <b>.begin</b> and <b>.end</b>, respectively.</p>
57 <p>In our example export filter, these could look like the
60 <p><i>html.begin.layout</i>:<br />
61 <code><HTML><br />
62 <BODY> text="#275856"><br />
63 <basefont size="4" color="#2F4958"
64 face="arial"></code></p>
66 <p><i>html.end.layout</i>:<br />
67 <code></BODY><br />
68 </HTML></code></p>
70 <p>The file <i>html.layout</i> provides the <i>default</i>
71 template for exporting one single entry. If you want to use
72 different templates for different entry types, you can do this
73 by adding entry-specific <b>.layout</b> files. These must also
74 reside in the same directory as the main layout file, and are
75 named by inserting <b>.entrytype</b> into the name of the main
76 layout file. The entry type name must be in all lowercase. In
77 our example, we might want to add a template for book entries,
78 and this would go into the file <i>html.book.layout</i>. For a
79 PhD thesis we would add the file <i>html.phdthesis.layout</i>,
80 and so on. These files are similar to the default layout file,
81 except that they will only be used for entries of the matching
82 type. Note that the default file can easily be made general
83 enough to cover most entry types in most export filters.</p>
85 <h3>The layout file format</h3>
87 <p>Layout files are created using a
88 simple markup format where commands are identified by a
89 preceding backslash. All text not identified as part of a
90 command will be copied verbatim to the output file.</p>
92 <h3>Field commands</h3>
94 <p>An arbitrary word preceded by a backslash, e.g.
95 <code>\author</code>, <code>\editor</code>, <code>\title</code>
96 or <code>\year</code>, will be interpreted as a reference to
97 the corresponding field, which will be copied directly to the
100 <h3>Field formatters</h3>
102 <p>Often there will be a need for some preprocessing of the
103 field contents before output. This is done using a <i>field
104 formatter</i> - a java class containing a single method that
105 manipulates the contents of a field.</p>
107 <p>A formatter is used by inserting the <code>\format</code>
108 command followed by the formatter name in square braces, and
109 the field command in curly braces, e.g.:</p>
111 <p><code>\format[ToLowerCase]{\author}</code></p>
113 <p>You can also specify multiple formatters separated by
114 commas. These will be called sequentially, from left to right,
117 <p><code>\format[ToLowerCase,HTMLChars]{\author}</code></p>
119 <p>will cause the formatter <b>ToLowerCase</b> to be called
120 first, and then <b>HTMLChars</b> will be called to format the
121 result. You can list an arbitrary number of formatters in this
124 <p>The argument to the formatters, withing the curly braces,
125 does not have to be a field command. Instead, you can insert
126 normal text, which will then be passed to the formatters
127 instead of the contents of any field. This can be useful for
128 some fomatters, e.g. the CurrentDate formatter (described
131 <p>Some formatters take an extra argument, given in parentheses
132 immediately after the formatter name. The argument can be enclosed
133 in quotes, which is necessary if it includes the parenthesis characters.
134 For instance, <code>\format[Replace("\s,_")]{\journal}</code> calls
135 the <b>Replace</b> formatter with the argument <b>\s,_</b> (which results
136 in the "journal" field after replacing all whitespace by underscores).
139 <p>JabRef provides the following set of formatters, some of
140 which depend on the others:</p>
143 <li><code>HTMLChars</code> : replaces TeX-specific special
144 characters (e.g. {\^a} or {\"{o}}) with their HTML
145 representations, and translates LaTeX commands \emph, \textit,
146 \textbf into HTML equivalents.</li>
148 <li><code>HTMLParagraphs</code> : interprets two
149 consecutive newlines (e.g. \n \n) as the beginning of a new
150 paragraph and creates paragraph-html-tags accordingly.</li>
152 <li><code>XMLChars</code> : replaces TeX-specific special
153 characters (e.g. {\^a} or {\"{o}}) with their XML
154 representations.</li>
156 <li><code>CreateDocBookAuthors</code> : formats the author
157 field in DocBook style.</li>
159 <li><code>CreateDocBookEditors</code> : to be
162 <li><code>CurrentDate</code> : outputs the current date.
163 With no argument, this formatter outputs the current date
164 and time in the format "yyyy.MM.dd hh:mm:ss z" (date, time
165 and time zone). By giving a different format string as
166 argument, the date format can be customized. E.g.
167 <code>\format[CurrentDate]{yyyy.MM.dd}</code> will give the
168 date only, e.g. 2005.11.30.</li>
170 <li><code>AuthorFirstFirst</code> : formats author/editor
171 fields with the first names first.</li>
173 <li><code>AuthorFirstFirstCommas</code> or <code>AuthorFirstLastCommas</code>
174 : formats author/editor fields with the first names first, delimited by
175 commas, with "and" between the last two names.</li>
177 <li><code>AuthorFirstLastOxfordCommas</code> : similar
178 to <code>AuthorFirstLastCommas</code>, except that the "and"
179 between the last two names is preceded by a comma.</li>
181 <li><code>AuthorFirstAbbrLastCommas</code> : formats
182 author/editor fields with abbreviated first names first, delimited by
183 commas, with "and" between the last two names.</li>
185 <li><code>AuthorFirstAbbrLastOxfordCommas</code> : similar
186 to <code>AuthorFirstAbbrLastCommas</code>, except that the "and"
187 between the last two names is preceded by a comma.</li>
189 <li><code>AuthorLastFirst</code> : formats author/editor
190 fields with the last names first.</li>
192 <li><code>AuthorAbbreviator</code> or <code>AuthorLastFirstAbbreviator</code>
193 : abbreviates first and middle names of all authors. This formatter
194 returns names with the last name first. Follow this formatter with
195 AuthorFirstFirst to get abbreviated names with the initials first.</li>
197 <li><code>AuthorLastFirstCommas</code> : formats
198 author/editor fields with the last names first, delimited by
199 commas, with "and" between the last two names.</li>
201 <li><code>AuthorLastFirstOxfordCommas</code> : similar
202 to <code>AuthorLastFirstCommas</code>, except that the "and"
203 between the last two names is preceded by a comma.</li>
205 <li><code>AuthorLastFirstAbbrCommas</code> : formats
206 author/editor fields with last names first and abbreviated first names
207 last, delimited by commas, with "and" between the last two names.</li>
209 <li><code>AuthorLastFirstAbbrOxfordCommas</code> : similar
210 to <code>AuthorLastFirstAbbrCommas</code>, except that the "and"
211 between the last two names is preceded by a comma.</li>
213 <li><code>AuthorAndsReplacer</code> : replaces "and"
214 between names with ";", and "&" between the last
217 <li><code>AuthorAndsCommaReplacer</code> : replaces "and"
218 between names with ",", and "&" between the last
221 <li><code>AuthorOrgSci</code> : first author is in "last,
222 first" all others in "first last". First names are
225 <li><code>AuthorNatBib</code> : formats author names in
226 NatBib style, with last names only, separating names by
227 "and" if there are two authors, and giving the first author
228 followed by "et al." if there are more than two
231 <li><code>NoSpaceBetweenAbbreviations</code> : spaces
232 between multiple abbreviated first names are removed.</li>
234 <li><code>FileLink(filetype)</code> : if no argument is given, this formatter outputs
235 the first external file link encoded in the field. To work, the formatter must
236 be supplied with the contents of the "file" field.
237 <p>This formatter takes the name of an external file type as an optional argument,
238 specified in parentheses after the formatter name. For instance,
239 <code>\format[FileLink(pdf)]{\file}</code> specifies <code>pdf</code> as an
240 argument. When an argument is given, the formatter selects the first file
241 link of the specified type. In the example, the path to the first PDF link will
244 <li><code>FormatPagesForHTML</code> : replaces "--" with
247 <li><code>FormatPagesForXML</code> : replaces "--" with an
250 <li><code>Replace(regexp,replacewith)</code> : does a regular expression replacement.
251 To use this formatter, a two-part argument must be given. The parts are
252 separated by a comma. To indicate the comma character, use an escape
253 sequence: \,<br> <br>
254 The first part is the regular expression to search for. The regular expression
255 is written normally, without extra escape sequences for backslashes. A description
256 of Java regular expressions can be found at:<br>
257 http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html
259 The second part is the text to replace all matches with.</li>
261 <li><code>RemoveBrackets</code> : removes all curly
262 brackets "{" or "}".</li>
264 <li><code>RemoveBracketsAddComma</code> : to be
267 <li><code>RemoveWhitespace</code> : removes all whitespace characters.</li>
269 <li><code>RemoveLatexCommands</code> : removes LaTeX
270 commands like <code>\em</code>, <code>\textbf</code>, etc.
271 If used together with <code>HTMLChars</code> or
272 <code>XMLChars</code>, this formatter should be called
275 <li><code>RemoveTilde</code> : replaces the tilde character
276 used in LaTeX as a non-breakable space by a regular space.
277 Useful in combination with the NameFormatter discussed in
278 the next section.</li>
280 <li><code>ToLowerCase</code> : turns all characters into
283 <li><code>ToUpperCase</code> : turns all characters into
286 <li><code>GetOpenOfficeType</code> : returns the number used by the OpenOffice.org
287 bibliography system (versions 1.x and 2.x) to denote the type of this entry.</li>
289 <li><code>RTFChars</code> : replaces TeX-specific special
290 characters (e.g. {\^a} or {\"{o}}) with their RTF
291 representations, and translates LaTeX commands \emph, \textit,
292 \textbf into RTF equivalents.</li>
296 <p>If none of the available formatters can do what you want to
297 achieve, you can add your own by implementing the
298 <code>net.sf.jabref.export.layout.LayoutFormatter</code>
299 interface. If you insert your class into the
300 <code>net.sf.jabref.export.layout.format</code> package, you
301 can call the formatter by its class name only, like with the
302 standard formatters. Otherwise, you must call the formatter by
303 its fully qualified name (including package name). In any case,
304 the formatter must be in your classpath when running
307 <h2><a name="NameFormatter"
308 id="NameFormatter">Using Custom Name Formatters</a></h2>
310 <p>With JabRef 2.2 it is now possible to define custom name
311 formatters using the bibtex-sty-file syntax. This allows
312 ultimate flexibility, but is a cumbersome to write</p>
314 <p>You can define your own formatter in the preference tab
315 "Name Formatter" using the following format and then use it
316 with the name given to it as any other formatter</p>
317 <code><case1>@<range11>@<format>@<range12>@<format>@<range13>...@@<br />
319 <case2>@<range21>@... and so on.</code>
321 <p>This format first splits the task to format a list of author
322 into cases depending on how many authors there are (this is
323 since some formats differ depending on how many authors there
324 are). Each individual case is separated by @@ and contains
325 instructions on how to format each author in the case. These
326 instructions are separated by a @.</p>
328 <p>Cases are identified using integers (1, 2, 3, etc.) or the
329 character * (matches any number of authors) and will tell the
330 formatter to apply the following instructions if there are a
331 number of less or equal of authors given.</p>
334 <code><integer>..<integer></code>,
335 <code><integer></code> or the character <code>*</code>
336 using a 1 based index for indexing authors from the given list
337 of authors. Integer indexes can be negative to denote them to
338 start from the end of the list where -1 is the last author.</p>
340 <p>For instance with an authorlist of "Joe Doe and Mary Jane
341 and Bruce Bar and Arthur Kay":</p>
344 <li>1..3 will affect Joe, Mary and Bruce</li>
346 <li>4..4 will affect Arthur</li>
348 <li>* will affect all of them</li>
350 <li>2..-1 will affect Mary, Bruce and Arthur</li>
353 <p>The <code><format></code>-strings use the Bibtex
354 formatter format:</p>
356 <p>The four letters v, f, l, j indicate the name parts von,
357 first, last, jr which are used within curly braces. A single
358 letter v, f, l, j indicates that the name should be
359 abbreviated. If one of these letters or letter pairs is
360 encountered JabRef will output all the respective names
361 (possibly abbreviated), but the whole expression in curly
362 braces is only printed if the name part exists.</p>
364 <p>For instance if the format is "{ll} {vv {von Part}} {ff}"
365 and the names are "Mary Kay and John von Neumann", then JabRef
366 will output "Kay Mary" (with two space between last and first)
367 and "Neuman von von Part John".</p>
369 <p>I give two examples but would rather point you to the bibtex
372 <p>Small example: <code>"{ll}, {f.}"</code> will turn
373 <code>"Joe Doe"</code> into <code>"Doe, J."</code></p>
375 <p>Large example:</p>
380 <p><code>"Joe Doe and Mary Jane and Bruce Bar and Arthur
385 <p><code>"Doe, J., Jane, M., Bar, B. and Kay,
390 <p><code>1@*@{ll}, {f}.@@2@1@{ll}, {f}.@2@ and {ll},
391 {f}.@@*@1..-3@{ll}, {f}., @-2@{ll}, {f}.@-1@ and {ll},
395 <p>If somebody would like to write a better tutorial about
396 this: Write a mail to one of the JabRef mailinglists!</p>
398 <h3>Conditional output</h3>
400 <p>Some static output might only make
401 sense if a specific field is set. For instance, say we want to
402 follow the editor names with the text <code>(Ed.)</code>. This
403 can be done with the following text:</p>
405 <p><code>\format[HTMLChars,AuthorFirstFirst]{\editor}
408 <p>However, if the <code>editor</code> field has not been set -
409 it might not even make sense for the entry being exported - the
410 <code>(Ed.)</code> would be left hanging. This can be prevented
411 by instead using the <code>\begin</code> and <code>\end</code>
414 <p><code>\begin{editor}<br />
415 \format[HTMLChars,AuthorFirstFirst]{\editor} (Ed.)<br />
416 \end{editor}</code></p>
418 <p>The <code>\begin</code> and <code>\end</code> commands make
419 sure the text in between is printed if and only if the field
420 referred in the curly braces is defined for the ently being
423 <p><b>Note:</b> Use of the <code>\begin</code> and
424 <code>\end</code> commands is a key to creating layout files
425 that work well with a variety of entry types.</p>
427 <h3>Grouped output</h3>
429 <p>If you wish to separate your entries
430 into groups based on a certain field, use the grouped output
431 commands. Grouped output is very similar to conditional output,
432 except that the text in between is printed only if the field
433 referred in the curly braces has changed value.</p>
435 <p>For example, let's assume I wish to group by keyword. Before
436 exporting the file, make sure you have sorted your entries
437 based on keyword. Now use the following commands to group by
440 <p><code>\begingroup{keywords}New Category:
441 \format[HTMLChars]{\keywords}<br />
442 \endgroup{keywords}</code></p>
444 <h2>Sharing your work</h2>
446 <p>With external layout files, it's
447 fairly simple to share custom export formats between users. If
448 you write an export filter for a format not supported by
449 JabRef, or an improvement over an existing one, we encourage
450 you to post your work on our SourceForge.net page. The same
451 goes for formatter classes that you write. We'd be happy to
452 distribute a collection of submitted layout files, or to add to
453 the selection of standard export filters and formatters.</p>
455 <p>Starting with JabRef 2.4b1 you can also package your
456 ExportFormat or LayoutFormatter as a plug-in. If you do so,
457 you can provide a single zip-file to other user to make use
458 of your ExportFormat. For an example download the JabRef
459 source release and have a look at the directory
460 <code>src/plugins/</code>. Don't hesitate to stop by the
461 forums on Sourceforge, since we don't have extensive documentation, yet.</p>