1 <html xmlns="http://www.w3.org/1999/xhtml">
\r
3 <body text="#275856">
\r
4 <basefont size="4" color="#2F4958" face="arial" />
\r
6 <h1>JabRef Plugin System</h1>
\r
8 <p>Starting with 2.4b1, JabRef can be extended using a plugin system which was
\r
9 build using Java Plugin Framework (JPF).</p>
\r
11 <p>To <i>use plugins</i> simply put the jar file of the plugin in a folder called <code>plugins</code> in the
\r
12 folder where the JabRef.jar is located. When starting up, JabRef will print a list of all plugins loaded.</p>
\r
14 <h2>How to write a plugin</h2>
\r
16 <p>JabRef offers the following extension-points for developers:</p>
\r
18 <li><code>ImportFormat</code> - Add importers to JabRef accessible from the 'Import into ... database'.</li>
\r
19 <li><code>EntryFetcher</code> - Add access to databases like Citeseer or Medline to the <i>Web Search</i> menu.</li>
\r
20 <li><code>ExportFormatTemplate</code> - Add a template based export like the ones accessible using the <i>Manage Custom Exports</i>.</li>
\r
21 <li><code>ExportFormat</code> - Add an export filter to JabRef's export dialog, that is more complicated than the simple template based one.</li>
\r
22 <li><code>ExportFormatProvider</code> - A more powerful way to add export formats to JabRef.</li>
\r
23 <li><code>LayoutFormatter</code> - Add formatters that can be used in the layout based exporters.</li>
\r
24 <li><code>SidePanePlugin</code> - Add a side pane component that can do any kinds of operations. The panel is
\r
25 accessed from a <b>Plugins</b> menu in JabRef's main window.</li>
\r
28 <p>These extension-points are defined in the <code>plugin.xml</code> of the JabRef-core-plugin,
\r
29 which can be found in <code>JabRef/src/plugins/net.sf.jabref.core/</code>.</p>
\r
31 <p>To start developing follow these rough steps:</p>
\r
33 <li>Checkout the JabRef trunk from subversion (<code>https://jabref.svn.sourceforge.net/svnroot/jabref/trunk</code>).
\r
34 This contains both JabRef itself and plug-ins contributed so far to JabRef (you don't need the htdocs folder), which make great starting points for your own plugins.</li>
\r
35 <li>Compile JabRef using <code>ant jars</code>.</li>
\r
36 <li>Create your own project and define your extension in your own plugin.xml that satisfy the extension points of the core plugin.xml.
\r
37 In particular make sure that:
\r
39 <li>...your plugin.xml has a <code>requires</code>-section that imports the core plugin (<code>net.sf.jabref.core</code>).</li>
\r
40 <li>...your plugin.xml has a <code>runtime</code>-section, where you tell JPF, where in your project you have stored your class files and resources.</li>
\r
43 <li>Create a jar of your project and put it into the <code>plugins</code>-folder of JabRef.</li>
\r
44 <li>Your plugin should be loaded when you run JabRef from the jar.</li>
\r
47 <p>Feel free to ask us questions related to the plugin system on the mailing-list!</p>
\r
49 <h2>How to add an extension point to JabRef</h2>
\r
51 <p>This documentation is intended for JabRef developers who want to add further extensions points.</p>
\r
53 <p>To add a new extension-point, you need to declare this extension-point in the plugin.xml of the core plugin similar to this:</p>
\r
56 <extension-point id="PushToApplication">
\r
57 <parameter-def type="string" id="pushToApp"
\r
58 custom-data="<classname of the interface that plugin providers need to implement>" />
\r
59 <!-- optionally other parameters (we currently do not use any of these for anything)
\r
60 <parameter-def type="string" id="name" />
\r
61 <parameter-def type="string" id="description"
\r
62 multiplicity="none-or-one" />
\r
64 </extension-point>
\r
67 <p>Then you need to re-run the plugin code generator "<code>ant generate</code>", which will re-create the helper class in
\r
68 "<code>net.sf.jabref.plugin.core.generated</code>" so that it includes a method <code>getPushToApplicationExtensions()</code> which
\r
69 returns a list of all PushToTalk extensions registered with the system.</p>
\r
71 <p>This list then can be used like this (here an example what we do with the entry fetcher extensions):</p>
\r
75 * Load fetchers that are plug-in extensions
\r
77 JabRefPlugin jabrefPlugin = JabRefPlugin.getInstance(PluginCore.getManager());
\r
78 if (jabrefPlugin != null){
\r
79 for (EntryFetcherExtension ext : jabrefPlugin.getEntryFetcherExtensions()){
\r
80 EntryFetcher fetcher = ext.getEntryFetcher();
\r
81 if (fetcher != null){
\r
82 fetchers.add(fetcher);
\r
89 for (EntryFetcher fetcher : fetchers){
\r
90 GeneralFetcher generalFetcher = new GeneralFetcher(sidePaneManager, this, fetcher);
\r
91 web.add(generalFetcher.getAction());
\r
92 fetcherActions.add(generalFetcher.getAction());
\r