src/help/CustomImports.html

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