Load /tmp/tmp.cssmc10846/jabref-2.0.1+2.1b into
[debian/jabref.git] / 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>