← Back to branch summary

~ubuntu-branches/ubuntu/natty/jabref/natty

« back to all changes in this revision

Viewing changes to src/help/CustomImports.html

  • Committer: Bazaar Package Importer
  • Author(s): gregor herrmann
  • Date: 2007-11-16 18:38:18 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20071116183818-20x934jdsju14618
Tags: 2.3-2
* Add /usr/lib/jvm/java-7-icedtea to wrapper script. Doesn't work on
  Debian yet but helps Ubuntu users (TODO: add dependency on
  icedtea-java7-jre (not yet in Debian)).
* Reformat wrapper script.
* debian/rules: re-arrange targets and their dependencies.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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>
 
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>
53
67
1936;John Maynard Keynes;The General Theory of Employment, Interest and Money
54
 
2003;Boldrin & Levine;Case Against Intellectual Monopoly
 
68
2003;Boldrin &amp; Levine;Case Against Intellectual Monopoly
55
69
2004;ROBERT HUNT AND JAMES BESSEN;The Software Patent Experiment
56
 
</pre></p>
 
70
</pre><br />
 
71
    <br />
57
72
 
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>
 
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>
62
78
import java.io.*;
63
79
import java.util.*;
64
80
import net.sf.jabref.*;
74
90
  public boolean isRecognizedFormat(InputStream stream) throws IOException {
75
91
    return true; // this is discouraged except for demonstration purposes
76
92
  }
77
 
  
78
 
  public List importEntries(InputStream stream) throws IOException {    
79
 
        ArrayList bibitems = new ArrayList();
 
93
 
 
94
  public List importEntries(InputStream stream) throws IOException {
 
95
        ArrayList bibitems = new ArrayList();
80
96
    BufferedReader in = new BufferedReader(ImportFormatReader.getReaderDefaultEncoding(stream));
81
 
      
 
97
 
82
98
    String line = in.readLine();
83
99
    while (line != null) {
84
100
      if (!"".equals(line.trim())) {
90
106
        be.setField("title", fields[2]);
91
107
        bibitems.add(be);
92
108
        line = in.readLine();
93
 
      }     
 
109
      }
94
110
    }
95
 
        return bibitems;                
 
111
        return bibitems;
96
112
  }
97
113
}
98
 
</pre></p>
 
114
</pre><br />
 
115
    <br />
99
116
 
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>
 
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>
105
124
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>
 
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>
 
 
b'\\ No newline at end of file'