[svn-upgrade] new version jabref (2.7~beta1+ds)
[debian/jabref.git] / src / help / CustomImports.html
1 <html xmlns="http://www.w3.org/1999/xhtml">
2 <head>
3 <link rel="stylesheet" type="text/css" href="jabref_help.css"/>
4 </head>
5
6 <body>
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>