src/help/CustomImports.html

   1 <HTML>
   2
   3 <BODY text="#275856">
   4 <basefont size="4" color="#2F4958" face="arial">
   5
   6 <H1>Custom import filters</H1>
   7
   8 <p>JabRef allows you to define and use your own importers, in very much the same way as the
   9 standard import filters are defined. An import filter is defined by one or more
  10 Java <i>classes</i>, which parse the contents of a file from an input stream
  11 and create BibTex-Entries. So with some basic Java programming you can add an importer
  12 for your favorite source of references or register a new, improved version of an existing
  13 importer. Also, this allows you to add compiled custom importers that you might
  14 have obtained e.g. from SourceForge without rebuilding JabRef (see "Sharing your work").</p>
  15
  16 <p>Custom importers take precedence over standard importers. This way, you can override
  17 existing importers for the Autodetect and Command Line features of JabRef. Custom importers
  18 are ordered by name.</p>
  19
  20 <H2>Adding a custom import filter</H2>
  21
  22 <p>Make sure, you have a compiled custom import filter (one or more <code>.class</code> files
  23 as described below) and the class files are in a directory structure according to
  24 their package structure. To add a new custom import filter, open the dialog box
  25 <b>Options -> Manage custom imports</b>, and click <b>Add from folder</b>.
  26 A file chooser will appear, allowing you to select the classpath of your importer,
  27 i.e. the directory where the top folder of the package structure of your importer
  28 resides. In a second file chooser you select your importer
  29 class file, which must be derived from <code>ImportFormat</code>. By clicking
  30 <b>Select new ImportFormat Subclass</b>, your new importer will appear in the list
  31 of custom import filters. All custom importers will appear in the <b>File -> Import ->
  32 Custom Importers</b> and <b>File -> Import and Append -> Custom Importers</b> submenus
  33 of the JabRef window.</p>
  34
  35 <p>Please note that if you move the class to another directory you will have to
  36 remove and re-add the importer. If you add a custom importer under a name that
  37 already exists, the existing importer will be replaced. Although in some cases
  38 it is possible to update an existing custom importer without restarting JabRef
  39 (when the importer is not on the classpath), we recommend restarting JabRef
  40 after updating an custom-importer. You can also register importers
  41 contained in a ZIP- or JAR-file, simply select the Zip- or Jar-archive, then the
  42 entry (class-file) that represents the new importer.</p>
  43
  44 <H2>Creating an import filter</H2>
  45
  46 For examples and some helpful files on how to build your own importer, please check
  47 our download page.
  48
  49 <H3>A simple example</H3>
  50
  51 <p>Let us assume that we want to import files of the following form:
  52 <pre>
  53 1936;John Maynard Keynes;The General Theory of Employment, Interest and Money
  54 2003;Boldrin & Levine;Case Against Intellectual Monopoly
  55 2004;ROBERT HUNT AND JAMES BESSEN;The Software Patent Experiment
  56 </pre></p>
  57
  58 <p>In your favorite IDE or text editor create a class derived from <code>ImportFormat</code>
  59 that implements methods <code>getFormatName()</code>, <code>isRecognizedFormat</code>
  60 and <code>importEntries()</code>. Here is an example:
  61 <pre>
  62 import java.io.*;
  63 import java.util.*;
  64 import net.sf.jabref.*;
  65 import net.sf.jabref.imports.ImportFormat;
  66 import net.sf.jabref.imports.ImportFormatReader;
  67
  68 public class SimpleCsvImporter extends ImportFormat {
  69
  70   public String getFormatName() {
  71     return "Simple CSV Importer";
  72   }
  73
  74   public boolean isRecognizedFormat(InputStream stream) throws IOException {
  75     return true; // this is discouraged except for demonstration purposes
  76   }
  77
  78   public List importEntries(InputStream stream) throws IOException {
  79         ArrayList bibitems = new ArrayList();
  80     BufferedReader in = new BufferedReader(ImportFormatReader.getReaderDefaultEncoding(stream));
  81
  82     String line = in.readLine();
  83     while (line != null) {
  84       if (!"".equals(line.trim())) {
  85         String[] fields = line.split(";");
  86         BibtexEntry be = new BibtexEntry(Util.createNeutralId());
  87         be.setType(BibtexEntryType.getType("techreport"));
  88         be.setField("year", fields[0]);
  89         be.setField("author", fields[1]);
  90         be.setField("title", fields[2]);
  91         bibitems.add(be);
  92         line = in.readLine();
  93       }
  94     }
  95         return bibitems;
  96   }
  97 }
  98 </pre></p>
  99
 100 <p>Note that the example is in the default package. Suppose you have saved it
 101 under <code>/mypath/SimpleCsvImporter.java</code>. Also suppose the JabRef-2.0.jar is in the
 102 same folder as <code>SimpleCsvImporter.java</code> and Java is on your command path.
 103 Compile it using a JSDK 1.4 e.g. with
 104 <pre>
 105 javac -classpath JabRef-2.0.jar SimpleCsvImporter.java
 106 </pre>
 107 Now there should be a file <code>/mypath/SimpleCsvImporter.class</code>.</p>
 108
 109 <p>In JabRef, open <b>Options -> Manage custom imports</b>, and click <b>Add from folder</b>.
 110 Navigate to <code>/mypath</code> and click the <b>Select ...</b> button. Select the
 111 <code>SimpleCsvImporter.class</code> and click the <b>Select ...</b> button.
 112 Your importer should now appear in the list of custom importers under the name
 113 "Simple CSV Importer" and, after you click <b>Close</b> also in the <b>File -> Import ->
 114 Custom Importers</b> and <b>File -> Import and Append -> Custom Importers</b> submenus
 115 of the JabRef window.</p>
 116
 117 <H2>Sharing your work</H2>
 118
 119 <p>With custom importer files, it's fairly simple to share custom import formats between users.
 120 If you write an import filter for a format not supported by JabRef, or an improvement over an
 121 existing one, we encourage you to post your work on our SourceForge.net page. We'd be happy to
 122 distribute a collection of submitted import files, or to add to the selection of standard
 123 importers.</p>
 124
 125 </BODY>
 126 </HTML>