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