[svn-upgrade] new version jabref (2.7~beta1+ds)
[debian/jabref.git] / src / help / Plugin.html
1 <html xmlns="http://www.w3.org/1999/xhtml">\r
2 <head>\r
3 <link rel="stylesheet" type="text/css" href="jabref_help.css"/>\r
4 </head>\r
5 \r
6 <body>\r
7     <h1>JabRef Plugin System</h1>\r
8 \r
9     <p>Starting with version 2.4, JabRef can be extended using a plugin system which was \r
10     built using Java Plugin Framework (JPF).</p>\r
11 \r
12     <p>To use a plugin, it needs to be put in one of the directories where JabRef looks for plugins.\r
13     One such directory is the one called <code>plugins</code> below the directory where the JabRef\r
14     jar file is located. Another is the user plugin directory, <code>~/.jabref/plugins</code> under\r
15     Linux or OS X and <code>.jabref/plugins</code> under your user home directory under Windows.</p>\r
16 \r
17     <p>The simplest way of installing plugins is through the <i>Plugin manager</i>, accessed from\r
18     the <i>Plugins</i> menu. The plugin manager lists all plugins installed in your user plugin\r
19     directory, and allows you to both delete installed plugins and install new ones.\r
20     </p>\r
21     \r
22     <h2>How to write a plugin</h2>\r
23     \r
24     <p>JabRef offers the following extension-points for developers:</p>\r
25     <ul>\r
26       <li><code>ImportFormat</code> - Add importers to JabRef accessible from the 'Import into ... database'.</li> \r
27       <li><code>EntryFetcher</code> - Add access to databases like Citeseer or Medline to the <i>Web Search</i> menu.</li>\r
28       <li><code>ExportFormatTemplate</code> - Add a template based export like the ones accessible using the <i>Manage Custom Exports</i>.</li>\r
29       <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
30       <li><code>ExportFormatProvider</code> - A more powerful way to add export formats to JabRef.</li> \r
31       <li><code>LayoutFormatter</code> - Add formatters that can be used in the layout based exporters.</li>\r
32       <li><code>SidePanePlugin</code> - Add a side pane component that can do any kinds of operations. The panel is\r
33         accessed from a <b>Plugins</b> menu in JabRef's main window.</li>\r
34     </ul>\r
35     \r
36     <p>These extension-points are defined in the <code>plugin.xml</code> of the JabRef-core-plugin,\r
37     which can be found in <code>JabRef/src/plugins/net.sf.jabref.core/</code>.</p>\r
38     \r
39     <p>To start developing follow these rough steps:</p>\r
40     <ol>\r
41       <li>Checkout the JabRef trunk from subversion (<code>https://jabref.svn.sourceforge.net/svnroot/jabref/trunk</code>).\r
42     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
43       <li>Compile JabRef using <code>ant jars</code>.</li>\r
44       <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
45       In particular make sure that:\r
46       <ul>\r
47         <li>...your plugin.xml has a <code>requires</code>-section that imports the core plugin (<code>net.sf.jabref.core</code>).</li>\r
48         <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
49       </ul>\r
50       </li>\r
51       <li>Create a jar of your project and put it into the <code>plugins</code>-folder of JabRef.</li>\r
52       <li>Your plugin should be loaded when you run JabRef from the jar.</li>\r
53     </ol>\r
54 \r
55         <p>Feel free to ask us questions related to the plugin system on the mailing-list!</p>     \r
56 \r
57     <h2>How to add an extension point to JabRef</h2>\r
58     \r
59     <p>This documentation is intended for JabRef developers who want to add further extensions points.</p>\r
60     \r
61     <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
62     \r
63 <code><pre>    \r
64 &lt;extension-point id=&quot;PushToApplication&quot;&gt;\r
65         &lt;parameter-def type=&quot;string&quot; id=&quot;pushToApp&quot;\r
66                 custom-data=&quot;&lt;classname of the interface that plugin providers need to implement&gt;&quot; /&gt;\r
67         &lt;!-- optionally other parameters (we currently do not use any of these for anything)\r
68                 &lt;parameter-def type=&quot;string&quot; id=&quot;name&quot; /&gt;\r
69                 &lt;parameter-def type=&quot;string&quot; id=&quot;description&quot;\r
70                         multiplicity=&quot;none-or-one&quot; /&gt;\r
71                         --&gt;\r
72 &lt;/extension-point&gt;\r
73 </pre></code>\r
74 \r
75         <p>Then you need to re-run the plugin code generator "<code>ant generate</code>", which will re-create the helper class in \r
76         "<code>net.sf.jabref.plugin.core.generated</code>" so that it includes a method <code>getPushToApplicationExtensions()</code> which \r
77         returns a list of all PushToTalk extensions registered with the system.</p>\r
78  \r
79     <p>This list then can be used like this (here an example what we do with the entry fetcher extensions):</p>\r
80 \r
81 <code><pre> \r
82 /*\r
83  * Load fetchers that are plug-in extensions\r
84  */\r
85 JabRefPlugin jabrefPlugin = JabRefPlugin.getInstance(PluginCore.getManager());\r
86 if (jabrefPlugin != null){\r
87         for (EntryFetcherExtension ext : jabrefPlugin.getEntryFetcherExtensions()){\r
88                 EntryFetcher fetcher = ext.getEntryFetcher();\r
89                 if (fetcher != null){\r
90                         fetchers.add(fetcher);\r
91                 }\r
92         }\r
93 }\r
94  \r
95 // and later...\r
96  \r
97 for (EntryFetcher fetcher : fetchers){\r
98   GeneralFetcher generalFetcher = new GeneralFetcher(sidePaneManager, this, fetcher);\r
99   web.add(generalFetcher.getAction());\r
100   fetcherActions.add(generalFetcher.getAction());\r
101 }\r
102 </pre></code>\r
103 \r
104 </body>\r
105 </html>\r