3158 |
05 Mar 07 |
martin |
1 |
<?xml version="1.0" encoding="UTF-8"?> |
3159 |
05 Mar 07 |
martin |
2 |
<!DOCTYPE chapter PUBLIC |
3159 |
05 Mar 07 |
martin |
3 |
"-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" |
3192 |
13 Mar 07 |
martin |
4 |
"../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"> |
3158 |
05 Mar 07 |
martin |
5 |
<!-- |
3192 |
13 Mar 07 |
martin |
$Id$ |
3158 |
05 Mar 07 |
martin |
7 |
|
4889 |
06 Apr 09 |
nicklas |
Copyright (C) 2007 Johan Enell, Jari Häkkinen, Peter Johansson, Nicklas Nordborg, Martin Svensson |
5178 |
02 Nov 09 |
jari |
Copyright (C) 2008 Jari Häkkinen, Nicklas Nordborg |
5178 |
02 Nov 09 |
jari |
Copyright (C) 2009 Jari Häkkinen, Nicklas Nordborg, Martin Svensson |
3158 |
05 Mar 07 |
martin |
11 |
|
3158 |
05 Mar 07 |
martin |
This file is part of BASE - BioArray Software Environment. |
3158 |
05 Mar 07 |
martin |
Available at http://base.thep.lu.se/ |
3158 |
05 Mar 07 |
martin |
14 |
|
3158 |
05 Mar 07 |
martin |
BASE is free software; you can redistribute it and/or |
3158 |
05 Mar 07 |
martin |
modify it under the terms of the GNU General Public License |
4477 |
05 Sep 08 |
jari |
as published by the Free Software Foundation; either version 3 |
3158 |
05 Mar 07 |
martin |
of the License, or (at your option) any later version. |
3158 |
05 Mar 07 |
martin |
19 |
|
3158 |
05 Mar 07 |
martin |
BASE is distributed in the hope that it will be useful, |
3158 |
05 Mar 07 |
martin |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
3158 |
05 Mar 07 |
martin |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
3158 |
05 Mar 07 |
martin |
GNU General Public License for more details. |
3158 |
05 Mar 07 |
martin |
24 |
|
3158 |
05 Mar 07 |
martin |
You should have received a copy of the GNU General Public License |
4509 |
11 Sep 08 |
jari |
along with BASE. If not, see <http://www.gnu.org/licenses/>. |
3158 |
05 Mar 07 |
martin |
27 |
--> |
3158 |
05 Mar 07 |
martin |
28 |
|
3329 |
11 May 07 |
nicklas |
29 |
<chapter id="plugins"> |
5737 |
14 Sep 11 |
nicklas |
30 |
<title>Plug-ins and extensions</title> |
3175 |
08 Mar 07 |
enell |
31 |
|
3175 |
08 Mar 07 |
enell |
32 |
<para> |
5737 |
14 Sep 11 |
nicklas |
33 |
BASE can get extended functionality by the use of plug-ins and extensions. |
5737 |
14 Sep 11 |
nicklas |
34 |
Much of the hard work, such as data import/export and analysis is done with plug-ins. |
3329 |
11 May 07 |
nicklas |
35 |
BASE ships with a number of standard plug-ins, the core plug-ins, which gives |
5737 |
14 Sep 11 |
nicklas |
36 |
basic import/export and analysis functionality. Typically a plug-in interacts with |
5737 |
14 Sep 11 |
nicklas |
37 |
a user by asking for parameters that it need to be able to do it's work. For |
5737 |
14 Sep 11 |
nicklas |
38 |
example, which file to import data from, and maybe some regular expressions that |
5737 |
14 Sep 11 |
nicklas |
39 |
should be used when parsing the file and then some information about how the data |
5737 |
14 Sep 11 |
nicklas |
40 |
in the file should be mapped to items and properties in BASE. When the plug-in has |
5737 |
14 Sep 11 |
nicklas |
41 |
all parameters it needs a <guilabel>Job</guilabel> is added to a job queue. A job |
5737 |
14 Sep 11 |
nicklas |
42 |
agent or similar is then responsible for sceduling and executing (possibly on a |
5737 |
14 Sep 11 |
nicklas |
43 |
different machine) the plug-in code. |
3175 |
08 Mar 07 |
enell |
44 |
</para> |
5737 |
14 Sep 11 |
nicklas |
45 |
|
5737 |
14 Sep 11 |
nicklas |
46 |
<para> |
5737 |
14 Sep 11 |
nicklas |
47 |
Extensions are historically more targeted at additions to the user interface, |
5737 |
14 Sep 11 |
nicklas |
48 |
such as additional menu items, toolbar buttons, etc. As a result, extensions have |
5737 |
14 Sep 11 |
nicklas |
49 |
a lot more flexibility when it comes to the visual appearance. On the other |
5737 |
14 Sep 11 |
nicklas |
50 |
hand they are executed immediately as a result of user interaction and are expected |
5737 |
14 Sep 11 |
nicklas |
51 |
to perform quickly and without delay. |
5737 |
14 Sep 11 |
nicklas |
52 |
</para> |
5737 |
14 Sep 11 |
nicklas |
53 |
|
5737 |
14 Sep 11 |
nicklas |
54 |
<para> |
5737 |
14 Sep 11 |
nicklas |
55 |
Starting with BASE 3 the extension mechanism has been somewhat extended to cover |
5737 |
14 Sep 11 |
nicklas |
56 |
other things that are not directly related to the web interface. For example, |
5737 |
14 Sep 11 |
nicklas |
57 |
extensions can be used to add support for other protocols than HTTP when using |
5737 |
14 Sep 11 |
nicklas |
58 |
external files. The main difference between a plug-in and extension is that an |
5737 |
14 Sep 11 |
nicklas |
59 |
extension must execute immediately it's service is requested, but a plug-in can |
5737 |
14 Sep 11 |
nicklas |
60 |
be scheduled for later execution. |
5737 |
14 Sep 11 |
nicklas |
61 |
</para> |
3175 |
08 Mar 07 |
enell |
62 |
|
3182 |
12 Mar 07 |
enell |
63 |
|
3329 |
11 May 07 |
nicklas |
64 |
<sect1 id="plugins.installation"> |
5737 |
14 Sep 11 |
nicklas |
65 |
<title>Managing plug-ins and extensions</title> |
3329 |
11 May 07 |
nicklas |
66 |
|
5801 |
12 Oct 11 |
nicklas |
67 |
<important> |
5737 |
14 Sep 11 |
nicklas |
68 |
<title>Changes since BASE 2</title> |
5737 |
14 Sep 11 |
nicklas |
69 |
<para> |
5737 |
14 Sep 11 |
nicklas |
70 |
The plug-in and extensions installation has changed since BASE 2. The major |
5737 |
14 Sep 11 |
nicklas |
71 |
changes are: |
5737 |
14 Sep 11 |
nicklas |
72 |
</para> |
5737 |
14 Sep 11 |
nicklas |
73 |
<itemizedlist> |
5737 |
14 Sep 11 |
nicklas |
74 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
75 |
<para> |
5737 |
14 Sep 11 |
nicklas |
76 |
The main JAR file must be installed in the directory specified by the |
5737 |
14 Sep 11 |
nicklas |
77 |
<constant>plugins.dir</constant> setting in <filename>base.config</filename>. |
5737 |
14 Sep 11 |
nicklas |
78 |
Subdirectories are not allowed. This applies to both plug-ins and |
5737 |
14 Sep 11 |
nicklas |
79 |
extensions. The <filename>WEB-INF/extensions</filename> is not used for |
5737 |
14 Sep 11 |
nicklas |
80 |
extensions anymore. |
5737 |
14 Sep 11 |
nicklas |
81 |
</para> |
5737 |
14 Sep 11 |
nicklas |
82 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
83 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
84 |
<para> |
5737 |
14 Sep 11 |
nicklas |
85 |
A package must be installed as a whole. It is no longer possible to only |
5737 |
14 Sep 11 |
nicklas |
86 |
select some of the plug-ins to install. If neccessary, the administrator can |
5737 |
14 Sep 11 |
nicklas |
87 |
always disable plug-ins that is not wanted. |
5737 |
14 Sep 11 |
nicklas |
88 |
</para> |
5737 |
14 Sep 11 |
nicklas |
89 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
90 |
</itemizedlist> |
5801 |
12 Oct 11 |
nicklas |
91 |
</important> |
3329 |
11 May 07 |
nicklas |
92 |
|
3329 |
11 May 07 |
nicklas |
93 |
<para> |
5737 |
14 Sep 11 |
nicklas |
94 |
The first step is to install the actual code on the web server. The recommendation |
5737 |
14 Sep 11 |
nicklas |
95 |
to developers is to ship the entire package as a single JAR file. If everything is |
5737 |
14 Sep 11 |
nicklas |
96 |
JAVA based this should not be a problem. A common exception is that configuration |
5737 |
14 Sep 11 |
nicklas |
97 |
files should be installed (and configured) separately. Always read the installation |
5737 |
14 Sep 11 |
nicklas |
98 |
instructions for the package you are installing. The rest of the instructions in |
5737 |
14 Sep 11 |
nicklas |
99 |
this section assume that the plug-in/extensions comes as a single JAR file. |
3329 |
11 May 07 |
nicklas |
100 |
</para> |
3329 |
11 May 07 |
nicklas |
101 |
|
3329 |
11 May 07 |
nicklas |
102 |
<note> |
5737 |
14 Sep 11 |
nicklas |
103 |
<title>Make sure the extensions folder is writable by Tomcat</title> |
3329 |
11 May 07 |
nicklas |
104 |
<para> |
5737 |
14 Sep 11 |
nicklas |
105 |
The package you are installing may include resources such as HTML |
5737 |
14 Sep 11 |
nicklas |
106 |
files, JSP scripts, images, etc. that needs to be extracted to the |
5737 |
14 Sep 11 |
nicklas |
107 |
web application path before they can be used. This extraction is |
5737 |
14 Sep 11 |
nicklas |
108 |
automatically done by the installation wizard, but you have to make |
5737 |
14 Sep 11 |
nicklas |
109 |
sure that the user account Tomcat is running as has permission |
5737 |
14 Sep 11 |
nicklas |
110 |
to create (and delete) new files in the |
5737 |
14 Sep 11 |
nicklas |
111 |
<filename class="directory"><base-dir>/www/extensions</filename> |
5737 |
14 Sep 11 |
nicklas |
112 |
directory. |
3329 |
11 May 07 |
nicklas |
113 |
</para> |
3329 |
11 May 07 |
nicklas |
114 |
</note> |
3329 |
11 May 07 |
nicklas |
115 |
|
3329 |
11 May 07 |
nicklas |
116 |
<para> |
5737 |
14 Sep 11 |
nicklas |
117 |
So, the first step should be simple. Just put the JAR file in the |
5737 |
14 Sep 11 |
nicklas |
118 |
dedicated plug-ins directory. This is the directory that is specified |
5737 |
14 Sep 11 |
nicklas |
119 |
in the <constant>plugins.dir</constant> setting in <filename>base.config</filename>. |
3329 |
11 May 07 |
nicklas |
120 |
</para> |
3329 |
11 May 07 |
nicklas |
121 |
|
6410 |
31 Jan 14 |
nicklas |
122 |
<important> |
6410 |
31 Jan 14 |
nicklas |
123 |
<title>Content security policy</title> |
6410 |
31 Jan 14 |
nicklas |
124 |
<para> |
6410 |
31 Jan 14 |
nicklas |
125 |
Since BASE 3.3 the default configuration specify a setting that tell web browsers |
6410 |
31 Jan 14 |
nicklas |
126 |
to not execute code (including JavaScript) that is considered unsafe. Older extensions |
6410 |
31 Jan 14 |
nicklas |
127 |
may not adhere to the restrictions implied by this and may thus not work unless |
6410 |
31 Jan 14 |
nicklas |
128 |
the configured <emphasis>Content security policy</emphasis> is relaxed a bit. |
6410 |
31 Jan 14 |
nicklas |
129 |
The extension installation wizard will try to detect if a plug-in violates the |
6410 |
31 Jan 14 |
nicklas |
130 |
policy and display a warning message. If you see the warning please read |
6410 |
31 Jan 14 |
nicklas |
131 |
<xref linkend="appendix.web.xml.csp-filter" /> for more information. |
6410 |
31 Jan 14 |
nicklas |
132 |
</para> |
6410 |
31 Jan 14 |
nicklas |
133 |
</important> |
6410 |
31 Jan 14 |
nicklas |
134 |
|
5737 |
14 Sep 11 |
nicklas |
135 |
<sect2 id="plugins.installation.wizard"> |
5737 |
14 Sep 11 |
nicklas |
136 |
<title>Automatic installation wizard</title> |
5737 |
14 Sep 11 |
nicklas |
137 |
|
3753 |
18 Sep 07 |
martin |
138 |
<para> |
5737 |
14 Sep 11 |
nicklas |
139 |
When the plug-in/extensions package is installed on the server you must register |
5737 |
14 Sep 11 |
nicklas |
140 |
it with BASE. Go to |
5737 |
14 Sep 11 |
nicklas |
141 |
<menuchoice> |
5737 |
14 Sep 11 |
nicklas |
142 |
<guimenu>Administrate</guimenu> |
5737 |
14 Sep 11 |
nicklas |
143 |
<guisubmenu>Plug-ins & extensions</guisubmenu> |
5737 |
14 Sep 11 |
nicklas |
144 |
<guimenuitem>Overview</guimenuitem> |
5737 |
14 Sep 11 |
nicklas |
145 |
</menuchoice>. |
3753 |
18 Sep 07 |
martin |
146 |
</para> |
5737 |
14 Sep 11 |
nicklas |
147 |
|
5737 |
14 Sep 11 |
nicklas |
148 |
<figure id="extensions.figures.installedextensions"> |
5737 |
14 Sep 11 |
nicklas |
149 |
<title>Installed extensions & plug-ins</title> |
5737 |
14 Sep 11 |
nicklas |
150 |
<screenshot> |
5737 |
14 Sep 11 |
nicklas |
151 |
<mediaobject> |
5737 |
14 Sep 11 |
nicklas |
152 |
<imageobject> |
5737 |
14 Sep 11 |
nicklas |
153 |
<imagedata fileref="figures/installed_extensions.png" format="PNG" /> |
5737 |
14 Sep 11 |
nicklas |
154 |
</imageobject> |
5737 |
14 Sep 11 |
nicklas |
155 |
</mediaobject> |
5737 |
14 Sep 11 |
nicklas |
156 |
</screenshot> |
5737 |
14 Sep 11 |
nicklas |
157 |
</figure> |
5737 |
14 Sep 11 |
nicklas |
158 |
|
5737 |
14 Sep 11 |
nicklas |
159 |
<helptext |
5737 |
14 Sep 11 |
nicklas |
160 |
external_id="extensions.details.main" |
5737 |
14 Sep 11 |
nicklas |
161 |
title="Installed extensions"> |
3866 |
19 Oct 07 |
nicklas |
162 |
|
5737 |
14 Sep 11 |
nicklas |
163 |
<para> |
5737 |
14 Sep 11 |
nicklas |
164 |
The left-hand side of the screen shows a tree with all installed |
5737 |
14 Sep 11 |
nicklas |
165 |
plug-ins and extensions, sorted by extension point and by file. Use |
5737 |
14 Sep 11 |
nicklas |
166 |
the + and - icons to expand and collapse parts of the tree. Click on an item |
5737 |
14 Sep 11 |
nicklas |
167 |
in the tree to display detailed information about it |
5737 |
14 Sep 11 |
nicklas |
168 |
on the right-hand side of the screen. Click on the |
5737 |
14 Sep 11 |
nicklas |
169 |
<guibutton>Install/uninstall</guibutton> button to start |
5737 |
14 Sep 11 |
nicklas |
170 |
the installation wizard (which can also be used for uninstallation). |
5737 |
14 Sep 11 |
nicklas |
171 |
</para> |
3866 |
19 Oct 07 |
nicklas |
172 |
|
3866 |
19 Oct 07 |
nicklas |
173 |
<seeother> |
5737 |
14 Sep 11 |
nicklas |
174 |
<other external_id="extensions.install-wizard">Install/uninstall wizard</other> |
3866 |
19 Oct 07 |
nicklas |
175 |
</seeother> |
5737 |
14 Sep 11 |
nicklas |
176 |
</helptext> |
5737 |
14 Sep 11 |
nicklas |
177 |
|
5737 |
14 Sep 11 |
nicklas |
178 |
<figure id="plugins.figures.installwizard"> |
5737 |
14 Sep 11 |
nicklas |
179 |
<title>Extensions and plug-ins installation wizard</title> |
5737 |
14 Sep 11 |
nicklas |
180 |
<screenshot> |
5737 |
14 Sep 11 |
nicklas |
181 |
<mediaobject> |
5737 |
14 Sep 11 |
nicklas |
182 |
<imageobject> |
5737 |
14 Sep 11 |
nicklas |
183 |
<imagedata fileref="figures/plugins_install_wizard.png" format="PNG" |
5737 |
14 Sep 11 |
nicklas |
184 |
scalefit="1" width="100%" /> |
5737 |
14 Sep 11 |
nicklas |
185 |
</imageobject> |
5737 |
14 Sep 11 |
nicklas |
186 |
</mediaobject> |
5737 |
14 Sep 11 |
nicklas |
187 |
</screenshot> |
5737 |
14 Sep 11 |
nicklas |
188 |
</figure> |
3866 |
19 Oct 07 |
nicklas |
189 |
|
5737 |
14 Sep 11 |
nicklas |
190 |
|
5737 |
14 Sep 11 |
nicklas |
191 |
<helptext |
5737 |
14 Sep 11 |
nicklas |
192 |
external_id="extensions.install-wizard" |
5737 |
14 Sep 11 |
nicklas |
193 |
title="Extensions and plug-ins installation wizard"> |
5737 |
14 Sep 11 |
nicklas |
194 |
|
5737 |
14 Sep 11 |
nicklas |
195 |
<para> |
5737 |
14 Sep 11 |
nicklas |
196 |
This wizard can be used for both installing, re-installing and un-installing |
5737 |
14 Sep 11 |
nicklas |
197 |
plug-in and extension packages. The first dialog shows a list with all |
5737 |
14 Sep 11 |
nicklas |
198 |
currently installed packages as well as any new packages that has been |
5737 |
14 Sep 11 |
nicklas |
199 |
found on the server. The list includes the name of the JAR file, |
5737 |
14 Sep 11 |
nicklas |
200 |
the current status and some information provided by the author of the package. |
7234 |
17 Nov 16 |
nicklas |
201 |
There are also three columns <guilabel>Install</guilabel>, <guilabel>Uninstall</guilabel> and |
7234 |
17 Nov 16 |
nicklas |
202 |
<guilabel>Ignore</guilabel> which may or may not have a checkbox in them. |
5737 |
14 Sep 11 |
nicklas |
203 |
For new packages there should be a checkbox in the install column that is already |
5737 |
14 Sep 11 |
nicklas |
204 |
checked. Already installed packages can either be re-installed or uninstalled by |
5737 |
14 Sep 11 |
nicklas |
205 |
checking the appropriate checkbox. If there is a problem with a package an error |
5737 |
14 Sep 11 |
nicklas |
206 |
message is displayed and neither installation or uninstallation is possible. |
5737 |
14 Sep 11 |
nicklas |
207 |
</para> |
5737 |
14 Sep 11 |
nicklas |
208 |
|
5737 |
14 Sep 11 |
nicklas |
209 |
<para> |
7234 |
17 Nov 16 |
nicklas |
210 |
The <guilabel>Ignore</guilabel> column can be used to tell the wizard to |
7234 |
17 Nov 16 |
nicklas |
211 |
ignore the selected file from now on. Ignored files are moved to a |
7234 |
17 Nov 16 |
nicklas |
212 |
separate section at the bottom of the installation wizard and you will |
7234 |
17 Nov 16 |
nicklas |
213 |
not be asked about installing them every time you run the wizard. Ignored |
7234 |
17 Nov 16 |
nicklas |
214 |
files can either be brought back to the regular flow with the |
7234 |
17 Nov 16 |
nicklas |
215 |
<guilabel>Stop ignore</guilabel> option or directly installed with |
7234 |
17 Nov 16 |
nicklas |
216 |
the <guilabel>Install</guilabel> button. |
7234 |
17 Nov 16 |
nicklas |
217 |
</para> |
7234 |
17 Nov 16 |
nicklas |
218 |
|
7234 |
17 Nov 16 |
nicklas |
219 |
<para> |
5737 |
14 Sep 11 |
nicklas |
220 |
Click on <guibutton>Next</guibutton> to perform the selected actions. The next |
5737 |
14 Sep 11 |
nicklas |
221 |
dialog should display a summary with the installation results. |
5737 |
14 Sep 11 |
nicklas |
222 |
Hopefully everything was succeessful. Close the dialog and refresh the overview tree |
5737 |
14 Sep 11 |
nicklas |
223 |
to see the changes. |
5737 |
14 Sep 11 |
nicklas |
224 |
</para> |
5737 |
14 Sep 11 |
nicklas |
225 |
|
5737 |
14 Sep 11 |
nicklas |
226 |
<note> |
5737 |
14 Sep 11 |
nicklas |
227 |
<para> |
5737 |
14 Sep 11 |
nicklas |
228 |
Uninstalling a package doesn't remove the plug-in definitions from BASE nor |
5737 |
14 Sep 11 |
nicklas |
229 |
does it remove the JAR file from the server. This is because there may be jobs |
5737 |
14 Sep 11 |
nicklas |
230 |
and other items referencing the plug-ins. The plug-ins are only marked as disabled |
5737 |
14 Sep 11 |
nicklas |
231 |
and it is up to the administrator to actually delete them if it is possible. |
5737 |
14 Sep 11 |
nicklas |
232 |
</para> |
5737 |
14 Sep 11 |
nicklas |
233 |
</note> |
3753 |
18 Sep 07 |
martin |
234 |
</helptext> |
5737 |
14 Sep 11 |
nicklas |
235 |
|
5737 |
14 Sep 11 |
nicklas |
236 |
<figure id="plugins.figures.installresults"> |
5737 |
14 Sep 11 |
nicklas |
237 |
<title>Extensions and plug-ins installation results</title> |
5737 |
14 Sep 11 |
nicklas |
238 |
<screenshot> |
5737 |
14 Sep 11 |
nicklas |
239 |
<mediaobject> |
5737 |
14 Sep 11 |
nicklas |
240 |
<imageobject> |
5737 |
14 Sep 11 |
nicklas |
241 |
<imagedata fileref="figures/plugins_install_wizard_2.png" format="PNG" |
5737 |
14 Sep 11 |
nicklas |
242 |
scalefit="1" width="100%" /> |
5737 |
14 Sep 11 |
nicklas |
243 |
</imageobject> |
5737 |
14 Sep 11 |
nicklas |
244 |
</mediaobject> |
5737 |
14 Sep 11 |
nicklas |
245 |
</screenshot> |
5737 |
14 Sep 11 |
nicklas |
246 |
</figure> |
3753 |
18 Sep 07 |
martin |
247 |
</sect2> |
3753 |
18 Sep 07 |
martin |
248 |
|
5737 |
14 Sep 11 |
nicklas |
249 |
<sect2 id="plugins.installation.manual"> |
5737 |
14 Sep 11 |
nicklas |
250 |
<title>Manual plug-in registration</title> |
3329 |
11 May 07 |
nicklas |
251 |
|
5737 |
14 Sep 11 |
nicklas |
252 |
<para> |
5737 |
14 Sep 11 |
nicklas |
253 |
Manual installation of a plug-in should almost never be neccessary. |
5737 |
14 Sep 11 |
nicklas |
254 |
One exception is that developers may want to do this as a first step |
5737 |
14 Sep 11 |
nicklas |
255 |
before everything has been properly packaged. Another exception is plug-ins |
5737 |
14 Sep 11 |
nicklas |
256 |
developed for BASE 2 that doesn't support the automatic installation procedure. |
5737 |
14 Sep 11 |
nicklas |
257 |
If the old plug-in still works API-wise in BASE 3, manual installation |
5737 |
14 Sep 11 |
nicklas |
258 |
can be used to install it. Repackaging such a plug-in is however not difficult |
5737 |
14 Sep 11 |
nicklas |
259 |
so we recommend that the plug-in author is asked to provide an updated |
5737 |
14 Sep 11 |
nicklas |
260 |
version. |
5737 |
14 Sep 11 |
nicklas |
261 |
</para> |
5737 |
14 Sep 11 |
nicklas |
262 |
|
5737 |
14 Sep 11 |
nicklas |
263 |
<para> |
5830 |
27 Oct 11 |
nicklas |
264 |
To perform a manual installation the plug-in's JAR file must be |
5830 |
27 Oct 11 |
nicklas |
265 |
located in the the directory specified by the <constant>plugins.dir</constant> |
5830 |
27 Oct 11 |
nicklas |
266 |
setting in <filename>base.config</filename>. Subdirectories are not |
5830 |
27 Oct 11 |
nicklas |
267 |
allowed. This is a change since BASE 2 were plug-ins could be installed |
5830 |
27 Oct 11 |
nicklas |
268 |
almost anywhere. When the JAR file is in place, go to |
5830 |
27 Oct 11 |
nicklas |
269 |
<menuchoice> |
5737 |
14 Sep 11 |
nicklas |
270 |
<guimenu>Administrate</guimenu> |
5737 |
14 Sep 11 |
nicklas |
271 |
<guisubmenu>Plug-ins & extensions</guisubmenu> |
5737 |
14 Sep 11 |
nicklas |
272 |
<guimenuitem>Plug-in definitions</guimenuitem> |
5737 |
14 Sep 11 |
nicklas |
273 |
</menuchoice> and click on the <guibutton>New</guibutton> button. |
5737 |
14 Sep 11 |
nicklas |
274 |
</para> |
3866 |
19 Oct 07 |
nicklas |
275 |
|
5737 |
14 Sep 11 |
nicklas |
276 |
<figure id="plugins.figures.installmanual"> |
5737 |
14 Sep 11 |
nicklas |
277 |
<title>Manually installing a plug-in</title> |
5737 |
14 Sep 11 |
nicklas |
278 |
<screenshot> |
5737 |
14 Sep 11 |
nicklas |
279 |
<mediaobject> |
5737 |
14 Sep 11 |
nicklas |
280 |
<imageobject><imagedata |
5737 |
14 Sep 11 |
nicklas |
281 |
fileref="figures/plugins_install_manual.png" format="PNG" |
5737 |
14 Sep 11 |
nicklas |
282 |
/></imageobject> |
5737 |
14 Sep 11 |
nicklas |
283 |
</mediaobject> |
5737 |
14 Sep 11 |
nicklas |
284 |
</screenshot> |
5737 |
14 Sep 11 |
nicklas |
285 |
</figure> |
3329 |
11 May 07 |
nicklas |
286 |
|
3329 |
11 May 07 |
nicklas |
287 |
<helptext external_id="plugindefinition.edit" |
3339 |
15 May 07 |
nicklas |
288 |
title="Plug-in properties"> |
3329 |
11 May 07 |
nicklas |
289 |
|
3329 |
11 May 07 |
nicklas |
290 |
<variablelist> |
3329 |
11 May 07 |
nicklas |
291 |
<varlistentry> |
3329 |
11 May 07 |
nicklas |
292 |
<term><guilabel>Name</guilabel></term> |
3329 |
11 May 07 |
nicklas |
293 |
<listitem> |
3329 |
11 May 07 |
nicklas |
294 |
<para> |
3329 |
11 May 07 |
nicklas |
295 |
The name of the plug-in. This name is set automatically by |
3487 |
13 Jun 07 |
peter |
296 |
the plug-in and cannot be changed. |
3329 |
11 May 07 |
nicklas |
297 |
</para> |
3329 |
11 May 07 |
nicklas |
298 |
</listitem> |
3329 |
11 May 07 |
nicklas |
299 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
300 |
<varlistentry> |
3329 |
11 May 07 |
nicklas |
301 |
<term><guilabel>Class</guilabel></term> |
3329 |
11 May 07 |
nicklas |
302 |
<listitem> |
3329 |
11 May 07 |
nicklas |
303 |
<para> |
5737 |
14 Sep 11 |
nicklas |
304 |
The full Java class name of the plug-in. |
3329 |
11 May 07 |
nicklas |
305 |
</para> |
3329 |
11 May 07 |
nicklas |
306 |
</listitem> |
3329 |
11 May 07 |
nicklas |
307 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
308 |
<varlistentry> |
5737 |
14 Sep 11 |
nicklas |
309 |
<term><guilabel>JAR file</guilabel></term> |
3329 |
11 May 07 |
nicklas |
310 |
<listitem> |
3329 |
11 May 07 |
nicklas |
311 |
<para> |
5737 |
14 Sep 11 |
nicklas |
312 |
The name of the JAR file on the web server. The JAR file must |
5737 |
14 Sep 11 |
nicklas |
313 |
be installed in the directory specified by the <constant>plugins.dir</constant> |
5737 |
14 Sep 11 |
nicklas |
314 |
setting in <filename>base.config</filename> If left empty |
3329 |
11 May 07 |
nicklas |
315 |
the plug-in must be on the web server's class path (not |
3329 |
11 May 07 |
nicklas |
316 |
recommended). |
3329 |
11 May 07 |
nicklas |
317 |
</para> |
3329 |
11 May 07 |
nicklas |
318 |
</listitem> |
3329 |
11 May 07 |
nicklas |
319 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
320 |
<varlistentry> |
3329 |
11 May 07 |
nicklas |
321 |
<term><guilabel>Max memory</guilabel></term> |
3329 |
11 May 07 |
nicklas |
322 |
<listitem> |
3329 |
11 May 07 |
nicklas |
323 |
<para> |
3329 |
11 May 07 |
nicklas |
324 |
The maximum amount of memory the plug-in may use. This setting |
3329 |
11 May 07 |
nicklas |
325 |
only applies when the plug-in is executed with a job agent. If |
3345 |
16 May 07 |
martin |
326 |
the internal job queue is used this setting has no effect and the |
3329 |
11 May 07 |
nicklas |
327 |
plug-in may use as much memory as it likes. |
5738 |
15 Sep 11 |
nicklas |
328 |
<nohelp>See <xref linkend="installation.jobagents.configuration" /> for more information.</nohelp> |
3329 |
11 May 07 |
nicklas |
329 |
</para> |
3329 |
11 May 07 |
nicklas |
330 |
</listitem> |
3329 |
11 May 07 |
nicklas |
331 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
332 |
<varlistentry> |
3329 |
11 May 07 |
nicklas |
333 |
<term><guilabel>Trusted</guilabel></term> |
3329 |
11 May 07 |
nicklas |
334 |
<listitem> |
3329 |
11 May 07 |
nicklas |
335 |
<para> |
3329 |
11 May 07 |
nicklas |
336 |
If the plug-in is trusted enough to be executed in an |
3329 |
11 May 07 |
nicklas |
337 |
unprotected environment. This setting has currently no |
3487 |
13 Jun 07 |
peter |
338 |
effect since BASE cannot run in a protected environment. |
3329 |
11 May 07 |
nicklas |
339 |
When this becomes implemented in the future a |
3329 |
11 May 07 |
nicklas |
340 |
<guilabel>no</guilabel> value will apply security restrictions |
3345 |
16 May 07 |
martin |
341 |
to plug-ins similar to those a web browser put on applets. |
3329 |
11 May 07 |
nicklas |
342 |
For example, the plug-in is not allowed to access the file |
3329 |
11 May 07 |
nicklas |
343 |
system, open ports, shut down the server, and a lot of |
3329 |
11 May 07 |
nicklas |
344 |
other nasty things. |
3329 |
11 May 07 |
nicklas |
345 |
</para> |
3329 |
11 May 07 |
nicklas |
346 |
</listitem> |
3329 |
11 May 07 |
nicklas |
347 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
348 |
<varlistentry> |
3329 |
11 May 07 |
nicklas |
349 |
<term><guilabel>Allow immediate execution</guilabel></term> |
3329 |
11 May 07 |
nicklas |
350 |
<listitem> |
3329 |
11 May 07 |
nicklas |
351 |
<para> |
3329 |
11 May 07 |
nicklas |
352 |
If the plug-in is allowed to bypass the job queue |
3329 |
11 May 07 |
nicklas |
353 |
and be executed immediately. |
3329 |
11 May 07 |
nicklas |
354 |
|
3329 |
11 May 07 |
nicklas |
355 |
<itemizedlist> |
3329 |
11 May 07 |
nicklas |
356 |
<listitem> |
3329 |
11 May 07 |
nicklas |
357 |
<para> |
3329 |
11 May 07 |
nicklas |
358 |
<guilabel>No</guilabel>: The plug-in must always use |
3329 |
11 May 07 |
nicklas |
359 |
the job queue. |
3329 |
11 May 07 |
nicklas |
360 |
</para> |
3329 |
11 May 07 |
nicklas |
361 |
</listitem> |
3329 |
11 May 07 |
nicklas |
362 |
<listitem> |
3329 |
11 May 07 |
nicklas |
363 |
<para> |
3329 |
11 May 07 |
nicklas |
364 |
<guilabel>Yes</guilabel>: The plug-in is allowed to bypass |
3329 |
11 May 07 |
nicklas |
365 |
the job queue. This also means that the plug-in always |
3329 |
11 May 07 |
nicklas |
366 |
executes on the web server, job agents are not used. |
3329 |
11 May 07 |
nicklas |
367 |
This setting is mainly useful for export plug-ins that |
3329 |
11 May 07 |
nicklas |
368 |
needs to support immediate download of the exported data. |
3329 |
11 May 07 |
nicklas |
369 |
<nohelp> |
3329 |
11 May 07 |
nicklas |
370 |
See <xref linkend="import_export_data.export.immediatedownload" />. |
3329 |
11 May 07 |
nicklas |
371 |
</nohelp> |
3329 |
11 May 07 |
nicklas |
372 |
</para> |
3329 |
11 May 07 |
nicklas |
373 |
|
3329 |
11 May 07 |
nicklas |
374 |
<note> |
3329 |
11 May 07 |
nicklas |
375 |
If a plug-in should be executed immediately or not |
3329 |
11 May 07 |
nicklas |
376 |
is always decided by the plug-in. BASE will never give |
3329 |
11 May 07 |
nicklas |
377 |
the users a choice. |
3329 |
11 May 07 |
nicklas |
378 |
</note> |
3329 |
11 May 07 |
nicklas |
379 |
|
3329 |
11 May 07 |
nicklas |
380 |
</listitem> |
3329 |
11 May 07 |
nicklas |
381 |
<listitem> |
3329 |
11 May 07 |
nicklas |
382 |
<para> |
3329 |
11 May 07 |
nicklas |
383 |
<guilabel>Auto</guilabel>: BASE will allow export plug-ins |
3329 |
11 May 07 |
nicklas |
384 |
to execute immediately, and deny all other types of plug-ins. |
3329 |
11 May 07 |
nicklas |
385 |
This alternative is only available when registering a new |
3329 |
11 May 07 |
nicklas |
386 |
plug-in. |
3329 |
11 May 07 |
nicklas |
387 |
</para> |
3329 |
11 May 07 |
nicklas |
388 |
</listitem> |
3329 |
11 May 07 |
nicklas |
389 |
</itemizedlist> |
3329 |
11 May 07 |
nicklas |
390 |
|
3329 |
11 May 07 |
nicklas |
391 |
</para> |
3329 |
11 May 07 |
nicklas |
392 |
</listitem> |
3329 |
11 May 07 |
nicklas |
393 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
394 |
</variablelist> |
3329 |
11 May 07 |
nicklas |
395 |
|
3329 |
11 May 07 |
nicklas |
396 |
<para> |
3394 |
28 May 07 |
martin |
397 |
Click on &gbSave; to finish the registration |
3394 |
28 May 07 |
martin |
398 |
or on &gbCancel; to abort. |
3329 |
11 May 07 |
nicklas |
399 |
</para> |
3329 |
11 May 07 |
nicklas |
400 |
|
3329 |
11 May 07 |
nicklas |
401 |
<seeother> |
3339 |
15 May 07 |
nicklas |
402 |
<other external_id="plugindefinition.edit.permissions">Plug-in permissions</other> |
3339 |
15 May 07 |
nicklas |
403 |
<other external_id="plugindefinition.jobagents">Job agents</other> |
3866 |
19 Oct 07 |
nicklas |
404 |
<other external_id="plugindefintion.autoinstaller">Automatic installation</other> |
3329 |
11 May 07 |
nicklas |
405 |
</seeother> |
3329 |
11 May 07 |
nicklas |
406 |
|
3329 |
11 May 07 |
nicklas |
407 |
</helptext> |
3329 |
11 May 07 |
nicklas |
408 |
</sect2> |
3329 |
11 May 07 |
nicklas |
409 |
|
5737 |
14 Sep 11 |
nicklas |
410 |
|
3329 |
11 May 07 |
nicklas |
411 |
<sect2 id="plugins.installation.base1"> |
4441 |
03 Sep 08 |
jari |
412 |
<title>BASE version 1 plug-ins</title> |
3339 |
15 May 07 |
nicklas |
413 |
<para> |
4441 |
03 Sep 08 |
jari |
414 |
BASE version 1 plug-ins are supported through the use of |
4441 |
03 Sep 08 |
jari |
415 |
the <emphasis>Base1PluginExecuter</emphasis> plug-in. This is |
4441 |
03 Sep 08 |
jari |
416 |
itself a plug-in and BASE version 1 plug-ins are added as |
5178 |
02 Nov 09 |
jari |
417 |
configurations to this plug-in (cf. |
5178 |
02 Nov 09 |
jari |
418 |
<xref linkend="plugins.configuration" />). To install a BASE |
4441 |
03 Sep 08 |
jari |
419 |
version 1 plug-in follow these instructions: |
3339 |
15 May 07 |
nicklas |
420 |
</para> |
3339 |
15 May 07 |
nicklas |
421 |
|
3339 |
15 May 07 |
nicklas |
422 |
<orderedlist> |
3339 |
15 May 07 |
nicklas |
423 |
<listitem> |
3339 |
15 May 07 |
nicklas |
424 |
<para> |
5178 |
02 Nov 09 |
jari |
425 |
Install the BASE version 1 plug-in executable and any other |
5178 |
02 Nov 09 |
jari |
426 |
files needed by it on the BASE server. Check the |
5178 |
02 Nov 09 |
jari |
427 |
documentation for the plug-in for information about what is |
5178 |
02 Nov 09 |
jari |
428 |
needed. |
3339 |
15 May 07 |
nicklas |
429 |
</para> |
3339 |
15 May 07 |
nicklas |
430 |
</listitem> |
3339 |
15 May 07 |
nicklas |
431 |
|
3339 |
15 May 07 |
nicklas |
432 |
<listitem> |
3339 |
15 May 07 |
nicklas |
433 |
<para> |
5737 |
14 Sep 11 |
nicklas |
434 |
Upload the <filename>*.base</filename> file for the BASE |
5737 |
14 Sep 11 |
nicklas |
435 |
version 1 plug-in. If you cannot find the file, you can let |
5737 |
14 Sep 11 |
nicklas |
436 |
your BASE version 1 server create one for you. In your BASE |
5737 |
14 Sep 11 |
nicklas |
437 |
version 1 installation go to |
5737 |
14 Sep 11 |
nicklas |
438 |
<menuchoice> |
5737 |
14 Sep 11 |
nicklas |
439 |
<guimenu>Analyze data</guimenu> |
5737 |
14 Sep 11 |
nicklas |
440 |
<guimenuitem>Plug-ins</guimenuitem> |
5737 |
14 Sep 11 |
nicklas |
441 |
</menuchoice> |
5737 |
14 Sep 11 |
nicklas |
442 |
and use the <guilabel>Export</guilabel> function. This will |
5737 |
14 Sep 11 |
nicklas |
443 |
create a configuration file for your BASE version 1 plug-in |
5737 |
14 Sep 11 |
nicklas |
444 |
that you can upload to your new BASE server. |
3339 |
15 May 07 |
nicklas |
445 |
</para> |
3339 |
15 May 07 |
nicklas |
446 |
</listitem> |
3339 |
15 May 07 |
nicklas |
447 |
|
3329 |
11 May 07 |
nicklas |
448 |
<listitem> |
3329 |
11 May 07 |
nicklas |
449 |
<para> |
5737 |
14 Sep 11 |
nicklas |
450 |
Create a new plug-in configuration using, for example, |
5737 |
14 Sep 11 |
nicklas |
451 |
the <guibutton>New configuration</guibutton> button in |
5737 |
14 Sep 11 |
nicklas |
452 |
single-item view for |
5737 |
14 Sep 11 |
nicklas |
453 |
the <emphasis>Base1PluginExecuter</emphasis> plug-in. |
3329 |
11 May 07 |
nicklas |
454 |
</para> |
3329 |
11 May 07 |
nicklas |
455 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
456 |
|
3329 |
11 May 07 |
nicklas |
457 |
<listitem> |
3329 |
11 May 07 |
nicklas |
458 |
<para> |
5737 |
14 Sep 11 |
nicklas |
459 |
Start the configuration wizard and select parameters: |
3329 |
11 May 07 |
nicklas |
460 |
</para> |
5737 |
14 Sep 11 |
nicklas |
461 |
<itemizedlist> |
5737 |
14 Sep 11 |
nicklas |
462 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
463 |
<para> |
5737 |
14 Sep 11 |
nicklas |
464 |
<guilabel>File</guilabel>: The <filename>*.base</filename> file |
5737 |
14 Sep 11 |
nicklas |
465 |
describing the BASE version 1 plug-in. This can be left empty for |
5737 |
14 Sep 11 |
nicklas |
466 |
manual configuration, but in reality it is only usable for tweaking |
5737 |
14 Sep 11 |
nicklas |
467 |
an existing configuration that has been created from a file |
5737 |
14 Sep 11 |
nicklas |
468 |
in the first place. |
5737 |
14 Sep 11 |
nicklas |
469 |
</para> |
5737 |
14 Sep 11 |
nicklas |
470 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
471 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
472 |
<para> |
5737 |
14 Sep 11 |
nicklas |
473 |
<guilabel>Plugin executables path</guilabel>: The path to the executable |
5737 |
14 Sep 11 |
nicklas |
474 |
program that was installed in the first step. |
5737 |
14 Sep 11 |
nicklas |
475 |
|
5737 |
14 Sep 11 |
nicklas |
476 |
</para> |
5737 |
14 Sep 11 |
nicklas |
477 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
478 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
479 |
<para> |
5737 |
14 Sep 11 |
nicklas |
480 |
<guilabel>Source intensities</guilabel>: Select if the plug-in can work |
5737 |
14 Sep 11 |
nicklas |
481 |
with regular or logged data (or both). |
5737 |
14 Sep 11 |
nicklas |
482 |
</para> |
5737 |
14 Sep 11 |
nicklas |
483 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
484 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
485 |
<para> |
5737 |
14 Sep 11 |
nicklas |
486 |
<guilabel>Resulting intensities</guilabel>: Select if the plug-in generates |
5737 |
14 Sep 11 |
nicklas |
487 |
regular or logged data. |
5737 |
14 Sep 11 |
nicklas |
488 |
</para> |
5737 |
14 Sep 11 |
nicklas |
489 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
490 |
</itemizedlist> |
5737 |
14 Sep 11 |
nicklas |
491 |
|
3329 |
11 May 07 |
nicklas |
492 |
<para> |
5737 |
14 Sep 11 |
nicklas |
493 |
Click <guibutton>Next</guibutton> to finish the wizard. |
3329 |
11 May 07 |
nicklas |
494 |
</para> |
5737 |
14 Sep 11 |
nicklas |
495 |
|
3329 |
11 May 07 |
nicklas |
496 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
497 |
|
3329 |
11 May 07 |
nicklas |
498 |
<listitem> |
3329 |
11 May 07 |
nicklas |
499 |
<para> |
5737 |
14 Sep 11 |
nicklas |
500 |
To check that the new plug-in works correctly, you need to |
5737 |
14 Sep 11 |
nicklas |
501 |
have an experiment with some data. Go to the single-item |
5737 |
14 Sep 11 |
nicklas |
502 |
view for a bioassay set and click on the <guibutton>Run |
5737 |
14 Sep 11 |
nicklas |
503 |
analysis</guibutton> button. Select |
5737 |
14 Sep 11 |
nicklas |
504 |
the <emphasis>Base1PluginExecuter</emphasis> plug-in. The |
5737 |
14 Sep 11 |
nicklas |
505 |
list of configurations should include the newly installed |
5737 |
14 Sep 11 |
nicklas |
506 |
plug-in. Select it and click on &gbNext;. |
3329 |
11 May 07 |
nicklas |
507 |
</para> |
3329 |
11 May 07 |
nicklas |
508 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
509 |
|
3329 |
11 May 07 |
nicklas |
510 |
<listitem> |
3329 |
11 May 07 |
nicklas |
511 |
<para> |
5737 |
14 Sep 11 |
nicklas |
512 |
This will enter regular plug-in execution wizard and you |
5737 |
14 Sep 11 |
nicklas |
513 |
will have to enter parameters needed by the plug-in. |
3329 |
11 May 07 |
nicklas |
514 |
</para> |
3329 |
11 May 07 |
nicklas |
515 |
</listitem> |
3175 |
08 Mar 07 |
enell |
516 |
|
5737 |
14 Sep 11 |
nicklas |
517 |
</orderedlist> |
3329 |
11 May 07 |
nicklas |
518 |
|
5737 |
14 Sep 11 |
nicklas |
519 |
</sect2> |
5737 |
14 Sep 11 |
nicklas |
520 |
|
3329 |
11 May 07 |
nicklas |
521 |
|
5737 |
14 Sep 11 |
nicklas |
522 |
<sect2 id="plugins.installation.xjspcompiler"> |
5737 |
14 Sep 11 |
nicklas |
523 |
<title>Installing the X-JSP compiler</title> |
5737 |
14 Sep 11 |
nicklas |
524 |
<para> |
5737 |
14 Sep 11 |
nicklas |
525 |
Some extensions may want to use custom JSP files that also uses |
5737 |
14 Sep 11 |
nicklas |
526 |
classes that are stored in the extension's JAR file. The problem |
5737 |
14 Sep 11 |
nicklas |
527 |
with this is that Tomcat usually doesn't know to look for classes |
5737 |
14 Sep 11 |
nicklas |
528 |
in the <filename>plugins.dir</filename> directory. To solve |
5737 |
14 Sep 11 |
nicklas |
529 |
this problem BASE ships with a X-JSP compiler that can do this. |
5737 |
14 Sep 11 |
nicklas |
530 |
This compiler has been mapped to files with a <code>.xjsp</code> |
5737 |
14 Sep 11 |
nicklas |
531 |
extension, which are just regular JSP files with a different extension. |
5737 |
14 Sep 11 |
nicklas |
532 |
</para> |
3339 |
15 May 07 |
nicklas |
533 |
|
3339 |
15 May 07 |
nicklas |
534 |
<para> |
5737 |
14 Sep 11 |
nicklas |
535 |
The X-JSP compiler must be installed into Tomcat's internal |
5737 |
14 Sep 11 |
nicklas |
536 |
library folder (<filename>$CATALINA_HOME/lib</filename>) |
5737 |
14 Sep 11 |
nicklas |
537 |
since this is the only place where Tomcat look for compilers. The installation |
5737 |
14 Sep 11 |
nicklas |
538 |
is easy. Simply copy <filename><base-dir>/bin/jar/base-xjsp-compiler-3.x.jar</filename> |
5737 |
14 Sep 11 |
nicklas |
539 |
to <filename>$CATALINA_HOME/lib</filename> and restart Tomcat. |
3339 |
15 May 07 |
nicklas |
540 |
</para> |
3339 |
15 May 07 |
nicklas |
541 |
|
5737 |
14 Sep 11 |
nicklas |
542 |
<note> |
5737 |
14 Sep 11 |
nicklas |
543 |
<title>X-JSP is experimental</title> |
5737 |
14 Sep 11 |
nicklas |
544 |
<para> |
5737 |
14 Sep 11 |
nicklas |
545 |
This is an experimental feature that depends on internal functionality |
5737 |
14 Sep 11 |
nicklas |
546 |
in Tomcat. It may or may not work with future versions of Tomcat. |
5737 |
14 Sep 11 |
nicklas |
547 |
The compiler will most likely not work with other servlet |
6129 |
14 Sep 12 |
nicklas |
548 |
containers. |
5737 |
14 Sep 11 |
nicklas |
549 |
</para> |
5737 |
14 Sep 11 |
nicklas |
550 |
</note> |
5737 |
14 Sep 11 |
nicklas |
551 |
</sect2> |
5737 |
14 Sep 11 |
nicklas |
552 |
|
5737 |
14 Sep 11 |
nicklas |
553 |
<sect2 id="plugins.installation.disable"> |
5737 |
14 Sep 11 |
nicklas |
554 |
<title>Disable/enable plug-ins and extensions</title> |
3339 |
15 May 07 |
nicklas |
555 |
|
3339 |
15 May 07 |
nicklas |
556 |
<para> |
5737 |
14 Sep 11 |
nicklas |
557 |
It is possible to disable specific extensions, extension point |
5737 |
14 Sep 11 |
nicklas |
558 |
and or a plug-in without uninstalling the XML or JAR file. |
5737 |
14 Sep 11 |
nicklas |
559 |
When you click on an item in the tree on the left-hand side of the |
5737 |
14 Sep 11 |
nicklas |
560 |
screen a lot of detailed information about it will show up on the right-hand side. |
5737 |
14 Sep 11 |
nicklas |
561 |
The right-hand side usually has a <guibutton>Disable</guibutton> |
5737 |
14 Sep 11 |
nicklas |
562 |
or <guibutton>Disable all</guibutton> button in the toolbar. Click on that button |
5737 |
14 Sep 11 |
nicklas |
563 |
to disable the plug-in, extension or all extensions |
5737 |
14 Sep 11 |
nicklas |
564 |
for an extension point. The button will change to <guibutton>Enable</guibutton> |
5737 |
14 Sep 11 |
nicklas |
565 |
or <guibutton>Enable all</guibutton> which lets you enable the extensions and |
5737 |
14 Sep 11 |
nicklas |
566 |
plug-ins again. |
3339 |
15 May 07 |
nicklas |
567 |
</para> |
5737 |
14 Sep 11 |
nicklas |
568 |
</sect2> |
5737 |
14 Sep 11 |
nicklas |
569 |
|
5737 |
14 Sep 11 |
nicklas |
570 |
<sect2 id="plugins.permissions"> |
5737 |
14 Sep 11 |
nicklas |
571 |
<title>Plug-in permissions</title> |
5737 |
14 Sep 11 |
nicklas |
572 |
|
5737 |
14 Sep 11 |
nicklas |
573 |
<helptext external_id="plugindefinition.edit.permissions" |
5737 |
14 Sep 11 |
nicklas |
574 |
title="Edit plug-in permissions"> |
5737 |
14 Sep 11 |
nicklas |
575 |
|
3339 |
15 May 07 |
nicklas |
576 |
|
5737 |
14 Sep 11 |
nicklas |
577 |
<para> |
5737 |
14 Sep 11 |
nicklas |
578 |
When a plug-in is executed the default is to give it the same |
5737 |
14 Sep 11 |
nicklas |
579 |
permissions as the user that started it. This can be seen as a |
5737 |
14 Sep 11 |
nicklas |
580 |
security risk if the plug-in is not trusted, or if someone manages |
5737 |
14 Sep 11 |
nicklas |
581 |
to replace the plug-in code with their own code. A malicious plug-in can, |
5737 |
14 Sep 11 |
nicklas |
582 |
for example, delete the entire database if invoked by the root user. |
5737 |
14 Sep 11 |
nicklas |
583 |
</para> |
5737 |
14 Sep 11 |
nicklas |
584 |
|
5737 |
14 Sep 11 |
nicklas |
585 |
<para> |
5737 |
14 Sep 11 |
nicklas |
586 |
To limit this problem it is possible to tune the permissions for |
5737 |
14 Sep 11 |
nicklas |
587 |
a plug-in so that it only has permission to do things that it |
5737 |
14 Sep 11 |
nicklas |
588 |
is supposed to do. For example, a plug-in that import reporters |
5737 |
14 Sep 11 |
nicklas |
589 |
may only need permission to update and create new reporters and |
5737 |
14 Sep 11 |
nicklas |
590 |
nothing else. |
5737 |
14 Sep 11 |
nicklas |
591 |
</para> |
3339 |
15 May 07 |
nicklas |
592 |
|
5737 |
14 Sep 11 |
nicklas |
593 |
<nohelp> |
5737 |
14 Sep 11 |
nicklas |
594 |
<para> |
5737 |
14 Sep 11 |
nicklas |
595 |
To enable the permission system for a plug-in go the |
5737 |
14 Sep 11 |
nicklas |
596 |
edit view of the plug-in and select the <guilabel>Permissions</guilabel> |
5737 |
14 Sep 11 |
nicklas |
597 |
tab. |
5737 |
14 Sep 11 |
nicklas |
598 |
</para> |
5737 |
14 Sep 11 |
nicklas |
599 |
|
5737 |
14 Sep 11 |
nicklas |
600 |
<figure id="plugins.figures.permissions"> |
5737 |
14 Sep 11 |
nicklas |
601 |
<title>Setting permissions on a plug-in</title> |
5737 |
14 Sep 11 |
nicklas |
602 |
<screenshot> |
5737 |
14 Sep 11 |
nicklas |
603 |
<mediaobject> |
5737 |
14 Sep 11 |
nicklas |
604 |
<imageobject><imagedata |
5737 |
14 Sep 11 |
nicklas |
605 |
fileref="figures/plugin_permissions.png" format="PNG" |
5737 |
14 Sep 11 |
nicklas |
606 |
/></imageobject> |
5737 |
14 Sep 11 |
nicklas |
607 |
</mediaobject> |
5737 |
14 Sep 11 |
nicklas |
608 |
</screenshot> |
5737 |
14 Sep 11 |
nicklas |
609 |
</figure> |
5737 |
14 Sep 11 |
nicklas |
610 |
</nohelp> |
5737 |
14 Sep 11 |
nicklas |
611 |
|
5737 |
14 Sep 11 |
nicklas |
612 |
<variablelist> |
5737 |
14 Sep 11 |
nicklas |
613 |
<varlistentry> |
5737 |
14 Sep 11 |
nicklas |
614 |
<term><guilabel>Use permissions</guilabel></term> |
5737 |
14 Sep 11 |
nicklas |
615 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
616 |
<para> |
5737 |
14 Sep 11 |
nicklas |
617 |
Select if the plug-in should use the permission system |
5737 |
14 Sep 11 |
nicklas |
618 |
or not. If <guilabel>no</guilabel> is selected, the rest |
5737 |
14 Sep 11 |
nicklas |
619 |
of the form is disabled. |
5737 |
14 Sep 11 |
nicklas |
620 |
</para> |
5737 |
14 Sep 11 |
nicklas |
621 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
622 |
</varlistentry> |
5737 |
14 Sep 11 |
nicklas |
623 |
<varlistentry> |
5737 |
14 Sep 11 |
nicklas |
624 |
<term><guilabel>Item types</guilabel></term> |
5737 |
14 Sep 11 |
nicklas |
625 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
626 |
<para> |
5737 |
14 Sep 11 |
nicklas |
627 |
The list contains all item types found in BASE that |
5737 |
14 Sep 11 |
nicklas |
628 |
can have permissions set on them. The list is more or less the |
5737 |
14 Sep 11 |
nicklas |
629 |
same as the permission list for roles. |
5737 |
14 Sep 11 |
nicklas |
630 |
<nohelp> |
5738 |
15 Sep 11 |
nicklas |
631 |
See <xref linkend="accounts.roles.edit.permissions" />. |
5737 |
14 Sep 11 |
nicklas |
632 |
</nohelp> |
5737 |
14 Sep 11 |
nicklas |
633 |
</para> |
5737 |
14 Sep 11 |
nicklas |
634 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
635 |
</varlistentry> |
5737 |
14 Sep 11 |
nicklas |
636 |
<varlistentry> |
5737 |
14 Sep 11 |
nicklas |
637 |
<term><guilabel>Always grant</guilabel></term> |
5737 |
14 Sep 11 |
nicklas |
638 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
639 |
<para> |
5737 |
14 Sep 11 |
nicklas |
640 |
The selected permissions will always be granted |
5737 |
14 Sep 11 |
nicklas |
641 |
to the plug-in no matter if the logged in user had the |
5737 |
14 Sep 11 |
nicklas |
642 |
permission to begin with or not. This makes it possible to |
5737 |
14 Sep 11 |
nicklas |
643 |
develop a plug-in that allows users to do things that they |
5737 |
14 Sep 11 |
nicklas |
644 |
are normally not allowed to do. The reporter importer is |
5737 |
14 Sep 11 |
nicklas |
645 |
for example allowed to create and use reporter types. |
5737 |
14 Sep 11 |
nicklas |
646 |
</para> |
5737 |
14 Sep 11 |
nicklas |
647 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
648 |
</varlistentry> |
5737 |
14 Sep 11 |
nicklas |
649 |
<varlistentry> |
5737 |
14 Sep 11 |
nicklas |
650 |
<term><guilabel>Always deny</guilabel></term> |
5737 |
14 Sep 11 |
nicklas |
651 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
652 |
<para> |
5737 |
14 Sep 11 |
nicklas |
653 |
The selected permissions will always be denied |
5737 |
14 Sep 11 |
nicklas |
654 |
to the plug-in no matter if the logged in user had the |
5737 |
14 Sep 11 |
nicklas |
655 |
permission to begin with or not. The default is to always |
5737 |
14 Sep 11 |
nicklas |
656 |
deny all permissions. Permissions that are not always |
5737 |
14 Sep 11 |
nicklas |
657 |
denied and not always granted uses permissions from |
5737 |
14 Sep 11 |
nicklas |
658 |
the logged in user. |
5737 |
14 Sep 11 |
nicklas |
659 |
</para> |
5737 |
14 Sep 11 |
nicklas |
660 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
661 |
</varlistentry> |
5737 |
14 Sep 11 |
nicklas |
662 |
<varlistentry> |
5737 |
14 Sep 11 |
nicklas |
663 |
<term><guilabel>Requested by plug-in</guilabel></term> |
5737 |
14 Sep 11 |
nicklas |
664 |
<listitem> |
5737 |
14 Sep 11 |
nicklas |
665 |
<para> |
5737 |
14 Sep 11 |
nicklas |
666 |
To make it easier for the server administrator |
5737 |
14 Sep 11 |
nicklas |
667 |
to assign permissions, the plug-in developer can |
5737 |
14 Sep 11 |
nicklas |
668 |
let the plug-in include a list of permissions that |
5737 |
14 Sep 11 |
nicklas |
669 |
are needed. Plug-in developers are advised to |
5737 |
14 Sep 11 |
nicklas |
670 |
only include the minimal set of permissions that are |
5737 |
14 Sep 11 |
nicklas |
671 |
required for the plug-in to function. Click on the |
5737 |
14 Sep 11 |
nicklas |
672 |
<guibutton>Use requested permissions</guibutton> |
5737 |
14 Sep 11 |
nicklas |
673 |
button to give the plug-in the requested permissions. |
5737 |
14 Sep 11 |
nicklas |
674 |
</para> |
5737 |
14 Sep 11 |
nicklas |
675 |
</listitem> |
5737 |
14 Sep 11 |
nicklas |
676 |
</varlistentry> |
5737 |
14 Sep 11 |
nicklas |
677 |
</variablelist> |
5737 |
14 Sep 11 |
nicklas |
678 |
|
5737 |
14 Sep 11 |
nicklas |
679 |
<seeother> |
5737 |
14 Sep 11 |
nicklas |
680 |
<other external_id="plugindefinition.edit">Plug-in properties</other> |
5737 |
14 Sep 11 |
nicklas |
681 |
<other external_id="plugindefinition.jobagents">Job agents</other> |
5737 |
14 Sep 11 |
nicklas |
682 |
<other external_id="role.edit.permissions">Role permissions</other> |
5737 |
14 Sep 11 |
nicklas |
683 |
</seeother> |
5737 |
14 Sep 11 |
nicklas |
684 |
</helptext> |
5737 |
14 Sep 11 |
nicklas |
685 |
|
5737 |
14 Sep 11 |
nicklas |
686 |
</sect2> |
5737 |
14 Sep 11 |
nicklas |
687 |
|
3329 |
11 May 07 |
nicklas |
688 |
</sect1> |
5737 |
14 Sep 11 |
nicklas |
689 |
|
3329 |
11 May 07 |
nicklas |
690 |
|
3329 |
11 May 07 |
nicklas |
691 |
<sect1 id="plugins.configuration"> |
3329 |
11 May 07 |
nicklas |
692 |
<title>Plug-in configurations</title> |
3329 |
11 May 07 |
nicklas |
693 |
|
3329 |
11 May 07 |
nicklas |
694 |
<para> |
3329 |
11 May 07 |
nicklas |
695 |
While some plug-ins work right out of the box, some |
3329 |
11 May 07 |
nicklas |
696 |
may require configuration before they can be used. For example, |
3329 |
11 May 07 |
nicklas |
697 |
most of the core import plug-ins need configurations in the |
3329 |
11 May 07 |
nicklas |
698 |
form of regular expressions to be able to find headers and |
4441 |
03 Sep 08 |
jari |
699 |
data in the data files and the Base1PluginExecuter uses |
4441 |
03 Sep 08 |
jari |
700 |
configurations to store information about the BASE version 1 plug-ins. |
3329 |
11 May 07 |
nicklas |
701 |
</para> |
3329 |
11 May 07 |
nicklas |
702 |
|
3329 |
11 May 07 |
nicklas |
703 |
<para> |
3329 |
11 May 07 |
nicklas |
704 |
Configurations are managed from a plug-in's single-item view page |
3329 |
11 May 07 |
nicklas |
705 |
or from the |
3329 |
11 May 07 |
nicklas |
706 |
<menuchoice> |
3329 |
11 May 07 |
nicklas |
707 |
<guimenu>Administrate</guimenu> |
5737 |
14 Sep 11 |
nicklas |
708 |
<guisubmenu>Plug-ins & extensions</guisubmenu> |
5737 |
14 Sep 11 |
nicklas |
709 |
<guimenuitem>Plug-in configurations</guimenuitem> |
3329 |
11 May 07 |
nicklas |
710 |
</menuchoice> |
5737 |
14 Sep 11 |
nicklas |
711 |
page or from the single-item view page of each plug-in. |
3329 |
11 May 07 |
nicklas |
712 |
</para> |
3329 |
11 May 07 |
nicklas |
713 |
|
3329 |
11 May 07 |
nicklas |
714 |
<para> |
3394 |
28 May 07 |
martin |
715 |
Click on the &gbNew; button |
3329 |
11 May 07 |
nicklas |
716 |
to create a new configuration. |
3329 |
11 May 07 |
nicklas |
717 |
</para> |
3329 |
11 May 07 |
nicklas |
718 |
|
3329 |
11 May 07 |
nicklas |
719 |
<figure id="plugins.figures.configuration"> |
3329 |
11 May 07 |
nicklas |
720 |
<title>Create plug-in configuration</title> |
3329 |
11 May 07 |
nicklas |
721 |
<screenshot> |
3329 |
11 May 07 |
nicklas |
722 |
<mediaobject> |
3329 |
11 May 07 |
nicklas |
723 |
<imageobject><imagedata |
3329 |
11 May 07 |
nicklas |
724 |
fileref="figures/plugin_configuration.png" format="PNG" |
3329 |
11 May 07 |
nicklas |
725 |
/></imageobject> |
3329 |
11 May 07 |
nicklas |
726 |
</mediaobject> |
3329 |
11 May 07 |
nicklas |
727 |
</screenshot> |
3329 |
11 May 07 |
nicklas |
728 |
</figure> |
3329 |
11 May 07 |
nicklas |
729 |
|
3329 |
11 May 07 |
nicklas |
730 |
<helptext external_id="pluginconfiguration.edit" |
3329 |
11 May 07 |
nicklas |
731 |
title="Edit plugin configuration"> |
3329 |
11 May 07 |
nicklas |
732 |
|
3329 |
11 May 07 |
nicklas |
733 |
<variablelist> |
3329 |
11 May 07 |
nicklas |
734 |
<varlistentry> |
3329 |
11 May 07 |
nicklas |
735 |
<term><guilabel>Plugin</guilabel></term> |
3329 |
11 May 07 |
nicklas |
736 |
<listitem> |
3329 |
11 May 07 |
nicklas |
737 |
<para> |
3487 |
13 Jun 07 |
peter |
738 |
The plug-in this configuration belongs to. This cannot |
3329 |
11 May 07 |
nicklas |
739 |
be changed for existing configurations. Use the |
3329 |
11 May 07 |
nicklas |
740 |
<guibutton>Select…</guibutton> button |
4441 |
03 Sep 08 |
jari |
741 |
to open a pop-up window where you can select a plug-in. |
3329 |
11 May 07 |
nicklas |
742 |
</para> |
3329 |
11 May 07 |
nicklas |
743 |
</listitem> |
3329 |
11 May 07 |
nicklas |
744 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
745 |
<varlistentry> |
3329 |
11 May 07 |
nicklas |
746 |
<term><guilabel>Name</guilabel></term> |
3329 |
11 May 07 |
nicklas |
747 |
<listitem> |
3329 |
11 May 07 |
nicklas |
748 |
<para> |
3329 |
11 May 07 |
nicklas |
749 |
The name of the configuration. |
3329 |
11 May 07 |
nicklas |
750 |
</para> |
3329 |
11 May 07 |
nicklas |
751 |
</listitem> |
3329 |
11 May 07 |
nicklas |
752 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
753 |
<varlistentry> |
3329 |
11 May 07 |
nicklas |
754 |
<term><guilabel>Description</guilabel></term> |
3329 |
11 May 07 |
nicklas |
755 |
<listitem> |
3329 |
11 May 07 |
nicklas |
756 |
<para> |
3329 |
11 May 07 |
nicklas |
757 |
A description of the configuration (optional). |
3329 |
11 May 07 |
nicklas |
758 |
</para> |
3329 |
11 May 07 |
nicklas |
759 |
</listitem> |
3329 |
11 May 07 |
nicklas |
760 |
</varlistentry> |
3329 |
11 May 07 |
nicklas |
761 |
</variablelist> |
3329 |
11 May 07 |
nicklas |
762 |
|
3329 |
11 May 07 |
nicklas |
763 |
<note> |
3487 |
13 Jun 07 |
peter |
764 |
You cannot create configurations for plug-ins that |
3487 |
13 Jun 07 |
peter |
765 |
does not support being configured. |
3329 |
11 May 07 |
nicklas |
766 |
</note> |
3329 |
11 May 07 |
nicklas |
767 |
|
3329 |
11 May 07 |
nicklas |
768 |
<para> |
3394 |
28 May 07 |
martin |
769 |
Use the &gbSave; button to save the |
3329 |
11 May 07 |
nicklas |
770 |
configuration or the <guibutton>Save and configure</guibutton> |
3329 |
11 May 07 |
nicklas |
771 |
button to save and then start the configuration wizard. |
3329 |
11 May 07 |
nicklas |
772 |
</para> |
3329 |
11 May 07 |
nicklas |
773 |
|
3329 |
11 May 07 |
nicklas |
774 |
</helptext> |
3329 |
11 May 07 |
nicklas |
775 |
|
3329 |
11 May 07 |
nicklas |
776 |
<sect2 id="plugins.configuration.wizard"> |
3329 |
11 May 07 |
nicklas |
777 |
<title>Configuring plug-in configurations</title> |
3329 |
11 May 07 |
nicklas |
778 |
|
3329 |
11 May 07 |
nicklas |
779 |
<helptext external_id="runplugin.configure" |
3329 |
11 May 07 |
nicklas |
780 |
title="The plug-in configuration wizard"> |
3329 |
11 May 07 |
nicklas |
781 |
|
3329 |
11 May 07 |
nicklas |
782 |
<para> |
3329 |
11 May 07 |
nicklas |
783 |
Configuring a plug-in is done with a wizard-like |
3329 |
11 May 07 |
nicklas |
784 |
interface. Since the configuration parameters may vary |
3329 |
11 May 07 |
nicklas |
785 |
from plug-in to plug-in BASE uses a generic interface |
3329 |
11 May 07 |
nicklas |
786 |
to enter parameter values. In short, it works like this: |
3329 |
11 May 07 |
nicklas |
787 |
|
3329 |
11 May 07 |
nicklas |
788 |
<orderedlist> |
3329 |
11 May 07 |
nicklas |
789 |
<listitem> |
3329 |
11 May 07 |
nicklas |
790 |
<para> |
3329 |
11 May 07 |
nicklas |
791 |
BASE asks the plug-in for information about |
3329 |
11 May 07 |
nicklas |
792 |
the parameters the plug-in needs. For example, |
3329 |
11 May 07 |
nicklas |
793 |
if the value is a string or number or should be |
3329 |
11 May 07 |
nicklas |
794 |
selected among a list of predefined values. |
3329 |
11 May 07 |
nicklas |
795 |
</para> |
3329 |
11 May 07 |
nicklas |
796 |
</listitem> |
3329 |
11 May 07 |
nicklas |
797 |
|
3329 |
11 May 07 |
nicklas |
798 |
<listitem> |
3329 |
11 May 07 |
nicklas |
799 |
<para> |
3329 |
11 May 07 |
nicklas |
800 |
BASE uses this information to create a generic form |
3329 |
11 May 07 |
nicklas |
801 |
for entering the values. The form consists of three |
3329 |
11 May 07 |
nicklas |
802 |
parts: |
3329 |
11 May 07 |
nicklas |
803 |
|
3329 |
11 May 07 |
nicklas |
804 |
<nohelp> |
3329 |
11 May 07 |
nicklas |
805 |
<figure id="plugins.figures.wizard"> |
3329 |
11 May 07 |
nicklas |
806 |
<title>The plug-in configuration wizard</title> |
3329 |
11 May 07 |
nicklas |
807 |
<screenshot> |
3329 |
11 May 07 |
nicklas |
808 |
<mediaobject> |
3329 |
11 May 07 |
nicklas |
809 |
<imageobject><imagedata |
3329 |
11 May 07 |
nicklas |
810 |
fileref="figures/plugin_wizard.png" format="PNG" |
3329 |
11 May 07 |
nicklas |
811 |
/></imageobject> |
3329 |
11 May 07 |
nicklas |
812 |
</mediaobject> |
3329 |
11 May 07 |
nicklas |
813 |
</screenshot> |
3329 |
11 May 07 |
nicklas |
814 |
</figure> |
3329 |
11 May 07 |
nicklas |
815 |
</nohelp> |
3329 |
11 May 07 |
nicklas |
816 |
|
3329 |
11 May 07 |
nicklas |
817 |
<itemizedlist> |
3329 |
11 May 07 |
nicklas |
818 |
<listitem> |
3329 |
11 May 07 |
nicklas |
819 |
<para> |
3329 |
11 May 07 |
nicklas |
820 |
<emphasis>The top part</emphasis>: Displays |
3329 |
11 May 07 |
nicklas |
821 |
the name of the selected plug-in and configuration. |
3329 |
11 May 07 |
nicklas |
822 |
</para> |
3329 |
11 May 07 |
nicklas |
823 |
</listitem> |
3329 |
11 May 07 |
nicklas |
824 |
|
3329 |
11 May 07 |
nicklas |
825 |
<listitem> |
3329 |
11 May 07 |
nicklas |
826 |
<para> |
3329 |
11 May 07 |
nicklas |
827 |
<emphasis>The left part</emphasis>: Displays |
3329 |
11 May 07 |
nicklas |
828 |
a list of all parameters supported by the plug-in. |
3329 |
11 May 07 |
nicklas |
829 |
Parameters with an <guilabel>X</guilabel> in front |
3329 |
11 May 07 |
nicklas |
830 |
of their names already have a value. Parameters |
3329 |
11 May 07 |
nicklas |
831 |
marked with a blue rectangle are required and |
3329 |
11 May 07 |
nicklas |
832 |
must be given a value before it is possible to |
3329 |
11 May 07 |
nicklas |
833 |
proceed. |
3329 |
11 May 07 |
nicklas |
834 |
</para> |
3329 |
11 May 07 |
nicklas |
835 |
</listitem> |
3329 |
11 May 07 |
nicklas |
836 |
|
3329 |
11 May 07 |
nicklas |
837 |
<listitem> |
3329 |
11 May 07 |
nicklas |
838 |
<para> |
3329 |
11 May 07 |
nicklas |
839 |
<emphasis>The right part</emphasis>: Click on a parameter |
3329 |
11 May 07 |
nicklas |
840 |
in the list to display a form for entering values for |
3329 |
11 May 07 |
nicklas |
841 |
that parameter. The form may be a simple free text field, |
3329 |
11 May 07 |
nicklas |
842 |
a list of checkboxes or radiobuttons, or something else |
3329 |
11 May 07 |
nicklas |
843 |
depending on the kind of values supported by that |
3329 |
11 May 07 |
nicklas |
844 |
parameter. |
3329 |
11 May 07 |
nicklas |
845 |
</para> |
3329 |
11 May 07 |
nicklas |
846 |
</listitem> |
3329 |
11 May 07 |
nicklas |
847 |
</itemizedlist> |
3329 |
11 May 07 |
nicklas |
848 |
|
3329 |
11 May 07 |
nicklas |
849 |
</para> |
3329 |
11 May 07 |
nicklas |
850 |
</listitem> |
3329 |
11 May 07 |
nicklas |
851 |
|
3329 |
11 May 07 |
nicklas |
852 |
<listitem> |
3329 |
11 May 07 |
nicklas |
853 |
<para> |
3394 |
28 May 07 |
martin |
854 |
When the user clicks &gbNext; |
3329 |
11 May 07 |
nicklas |
855 |
the entered values are sent to the plug-in which |
3329 |
11 May 07 |
nicklas |
856 |
validate the correctness. The plug-in may return |
3329 |
11 May 07 |
nicklas |
857 |
three different replies: |
3329 |
11 May 07 |
nicklas |
858 |
|
3329 |
11 May 07 |
nicklas |
859 |
<itemizedlist> |
3329 |
11 May 07 |
nicklas |
860 |
<listitem> |
3329 |
11 May 07 |
nicklas |
861 |
<para> |
3329 |
11 May 07 |
nicklas |
862 |
<emphasis>ERROR</emphasis>: |
3329 |
11 May 07 |
nicklas |
863 |
There is an error in the input. BASE will redisplay |
3329 |
11 May 07 |
nicklas |
864 |
the same form with any additional error information that |
3329 |
11 May 07 |
nicklas |
865 |
the plug-in sends back. |
3329 |
11 May 07 |
nicklas |
866 |
</para> |
3329 |
11 May 07 |
nicklas |
867 |
</listitem> |
3329 |
11 May 07 |
nicklas |
868 |
<listitem> |
3329 |
11 May 07 |
nicklas |
869 |
<para> |
3329 |
11 May 07 |
nicklas |
870 |
<emphasis>DONE</emphasis>: |
3686 |
20 Aug 07 |
jari |
871 |
All parameter values are okay and no more values |
3329 |
11 May 07 |
nicklas |
872 |
are needed. BASE will save the values to the database |
3329 |
11 May 07 |
nicklas |
873 |
and finish the configuration wizard. |
3329 |
11 May 07 |
nicklas |
874 |
</para> |
3329 |
11 May 07 |
nicklas |
875 |
</listitem> |
3329 |
11 May 07 |
nicklas |
876 |
<listitem> |
3329 |
11 May 07 |
nicklas |
877 |
<para> |
3329 |
11 May 07 |
nicklas |
878 |
<emphasis>CONTINUE</emphasis>: |
3686 |
20 Aug 07 |
jari |
879 |
All parameter values are okay, but the plug-in |
3329 |
11 May 07 |
nicklas |
880 |
wants more parameters. The procedure is repeated from the |
3329 |
11 May 07 |
nicklas |
881 |
first step. |
3329 |
11 May 07 |
nicklas |
882 |
</para> |
3329 |
11 May 07 |
nicklas |
883 |
</listitem> |
3329 |
11 May 07 |
nicklas |
884 |
</itemizedlist> |
3329 |
11 May 07 |
nicklas |
885 |
</para> |
3329 |
11 May 07 |
nicklas |
886 |
</listitem> |
3329 |
11 May 07 |
nicklas |
887 |
|
3329 |
11 May 07 |
nicklas |
888 |
</orderedlist> |
3329 |
11 May 07 |
nicklas |
889 |
</para> |
3329 |
11 May 07 |
nicklas |
890 |
|
3329 |
11 May 07 |
nicklas |
891 |
<note> |
3487 |
13 Jun 07 |
peter |
892 |
<title>Do not go back</title> |
5737 |
14 Sep 11 |
nicklas |
893 |
<para> |
3329 |
11 May 07 |
nicklas |
894 |
It is not possible to go backwards in the wizard. |
3329 |
11 May 07 |
nicklas |
895 |
If you try it will most likely result in an |
3329 |
11 May 07 |
nicklas |
896 |
unexpected error and the configuration must be restarted |
3329 |
11 May 07 |
nicklas |
897 |
from the beginning. |
5737 |
14 Sep 11 |
nicklas |
898 |
</para> |
3329 |
11 May 07 |
nicklas |
899 |
</note> |
3329 |
11 May 07 |
nicklas |
900 |
|
3329 |
11 May 07 |
nicklas |
901 |
<seeother> |
3329 |
11 May 07 |
nicklas |
902 |
<other external_id="runplugin.configure.import">Common parameter for import plug-ins</other> |
3329 |
11 May 07 |
nicklas |
903 |
<other external_id="runplugin.configure.export">Common parameter for export plug-ins</other> |
3329 |
11 May 07 |
nicklas |
904 |
<other external_id="runplugin.configure.analysis">Common parameter for analysis plug-ins</other> |
3329 |
11 May 07 |
nicklas |
905 |
</seeother> |
3329 |
11 May 07 |
nicklas |
906 |
</helptext> |
3329 |
11 May 07 |
nicklas |
907 |
|
3329 |
11 May 07 |
nicklas |
908 |
</sect2> |
3329 |
11 May 07 |
nicklas |
909 |
|
3339 |
15 May 07 |
nicklas |
910 |
<sect2 id="plugins.configuration.importexport"> |
3339 |
15 May 07 |
nicklas |
911 |
<title>Importing and exporting plug-in configurations</title> |
3339 |
15 May 07 |
nicklas |
912 |
<para> |
3339 |
15 May 07 |
nicklas |
913 |
BASE ships with one importer and one exporter that allows |
3339 |
15 May 07 |
nicklas |
914 |
you to import and export plug-in configurations. This makes |
5737 |
14 Sep 11 |
nicklas |
915 |
it easy to copy configurations between servers. |
3339 |
15 May 07 |
nicklas |
916 |
</para> |
3339 |
15 May 07 |
nicklas |
917 |
|
3339 |
15 May 07 |
nicklas |
918 |
<para> |
3339 |
15 May 07 |
nicklas |
919 |
Both the import and the export is started from the plug-in |
3339 |
15 May 07 |
nicklas |
920 |
configuration list view: |
3339 |
15 May 07 |
nicklas |
921 |
<menuchoice> |
3339 |
15 May 07 |
nicklas |
922 |
<guimenu>Administrate</guimenu> |
5737 |
14 Sep 11 |
nicklas |
923 |
<guisubmenu>Plug-ins & extensions</guisubmenu> |
5737 |
14 Sep 11 |
nicklas |
924 |
<guimenuitem>Plug-in configurations</guimenuitem> |
3339 |
15 May 07 |
nicklas |
925 |
</menuchoice> |
3339 |
15 May 07 |
nicklas |
926 |
</para> |
3339 |
15 May 07 |
nicklas |
927 |
|
3339 |
15 May 07 |
nicklas |
928 |
<para> |
3740 |
17 Sep 07 |
martin |
929 |
The importer supports auto detection. Simply upload and select the XML file with the |
3740 |
17 Sep 07 |
martin |
930 |
configurations. No more parameters are needed. |
3339 |
15 May 07 |
nicklas |
931 |
</para> |
3339 |
15 May 07 |
nicklas |
932 |
|
3339 |
15 May 07 |
nicklas |
933 |
<para> |
3740 |
17 Sep 07 |
martin |
934 |
If you don't want to import all |
3740 |
17 Sep 07 |
martin |
935 |
configurations that exist in the XML-file, there is an option that lets you select |
3740 |
17 Sep 07 |
martin |
936 |
each configuration individually. When the option to import all configurations is set |
3740 |
17 Sep 07 |
martin |
937 |
to FALSE in the first step of job-configuration, the following step after pressing |
3740 |
17 Sep 07 |
martin |
938 |
<guibutton>Next</guibutton> |
3740 |
17 Sep 07 |
martin |
939 |
will be to select those configurations that should be imported, otherwise this step |
3740 |
17 Sep 07 |
martin |
940 |
is skipped. |
3740 |
17 Sep 07 |
martin |
941 |
</para> |
3740 |
17 Sep 07 |
martin |
942 |
|
3740 |
17 Sep 07 |
martin |
943 |
|
3740 |
17 Sep 07 |
martin |
944 |
<para> |
3339 |
15 May 07 |
nicklas |
945 |
To use the exporter you must first select the configurations |
3686 |
20 Aug 07 |
jari |
946 |
that should be exported in the list. Then, enter a path and file name |
3339 |
15 May 07 |
nicklas |
947 |
if you wish to leave the XML file on the BASE server or leave it |
3339 |
15 May 07 |
nicklas |
948 |
empty to download it immediately. |
3339 |
15 May 07 |
nicklas |
949 |
</para> |
3339 |
15 May 07 |
nicklas |
950 |
|
3339 |
15 May 07 |
nicklas |
951 |
<note> |
3339 |
15 May 07 |
nicklas |
952 |
The import and export only supports simple values, such as strings, |
3487 |
13 Jun 07 |
peter |
953 |
numbers, etc. It does not support configuration values that reference |
3374 |
24 May 07 |
jari |
954 |
other items. If the plug-in has such values they must be fixed |
3374 |
24 May 07 |
jari |
955 |
manually after the import. |
3339 |
15 May 07 |
nicklas |
956 |
</note> |
3339 |
15 May 07 |
nicklas |
957 |
|
3329 |
11 May 07 |
nicklas |
958 |
</sect2> |
3329 |
11 May 07 |
nicklas |
959 |
|
3329 |
11 May 07 |
nicklas |
960 |
<sect2 id="plugins.configuration.testwithfile"> |
3329 |
11 May 07 |
nicklas |
961 |
<title>The <guilabel>Test with file</guilabel> function</title> |
3329 |
11 May 07 |
nicklas |
962 |
|
3339 |
15 May 07 |
nicklas |
963 |
<para> |
3345 |
16 May 07 |
martin |
964 |
The <guilabel>Test with file</guilabel> function is a very useful |
3339 |
15 May 07 |
nicklas |
965 |
function for specifying import file formats. It is supported by |
3339 |
15 May 07 |
nicklas |
966 |
many of the import plug-ins that read data from a simple text |
3339 |
15 May 07 |
nicklas |
967 |
file. This includes the raw data importer, the reporter importer, |
3339 |
15 May 07 |
nicklas |
968 |
plate reporter, etc. |
3339 |
15 May 07 |
nicklas |
969 |
</para> |
3339 |
15 May 07 |
nicklas |
970 |
|
3339 |
15 May 07 |
nicklas |
971 |
<note> |
3339 |
15 May 07 |
nicklas |
972 |
The <guilabel>Test with file</guilabel> function can only |
3339 |
15 May 07 |
nicklas |
973 |
be used with simple (tab- or comma-separated) text files. |
3487 |
13 Jun 07 |
peter |
974 |
It does not work with XML files or binary files. The text file |
3339 |
15 May 07 |
nicklas |
975 |
may have headers in the beginning. |
3339 |
15 May 07 |
nicklas |
976 |
</note> |
3339 |
15 May 07 |
nicklas |
977 |
|
3339 |
15 May 07 |
nicklas |
978 |
<para> |
3339 |
15 May 07 |
nicklas |
979 |
As you can see in figure <xref linkend="plugins.figures.wizard"/> |
3339 |
15 May 07 |
nicklas |
980 |
there is a <guibutton>Test with file</guibutton> button. This |
3339 |
15 May 07 |
nicklas |
981 |
will appear in the file format setup step for all plug-ins that |
3339 |
15 May 07 |
nicklas |
982 |
support the test with file function. For detailed technical |
3339 |
15 May 07 |
nicklas |
983 |
information about this see <xref linkend="plugin_developer.import" /> |
3339 |
15 May 07 |
nicklas |
984 |
in <xref linkend="plugin_developer" />. Clicking on the |
3339 |
15 May 07 |
nicklas |
985 |
<guibutton>Test with file</guibutton> button opens the following dialog: |
3339 |
15 May 07 |
nicklas |
986 |
</para> |
3339 |
15 May 07 |
nicklas |
987 |
|
3339 |
15 May 07 |
nicklas |
988 |
<figure id="plugins.figures.testwithfile"> |
3339 |
15 May 07 |
nicklas |
989 |
<title>The test with file function</title> |
3339 |
15 May 07 |
nicklas |
990 |
<screenshot> |
3339 |
15 May 07 |
nicklas |
991 |
<mediaobject> |
3339 |
15 May 07 |
nicklas |
992 |
<imageobject><imagedata |
3423 |
31 May 07 |
nicklas |
993 |
scalefit="1" width="100%" |
3339 |
15 May 07 |
nicklas |
994 |
fileref="figures/test_with_file.png" format="PNG" |
3339 |
15 May 07 |
nicklas |
995 |
/></imageobject> |
3339 |
15 May 07 |
nicklas |
996 |
</mediaobject> |
3339 |
15 May 07 |
nicklas |
997 |
</screenshot> |
3339 |
15 May 07 |
nicklas |
998 |
</figure> |
3339 |
15 May 07 |
nicklas |
999 |
|
3339 |
15 May 07 |
nicklas |
1000 |
<helptext external_id="runplugin.testwithfile" |
3339 |
15 May 07 |
nicklas |
1001 |
title="Test with file"> |
3339 |
15 May 07 |
nicklas |
1002 |
|
3339 |
15 May 07 |
nicklas |
1003 |
<para> |
3339 |
15 May 07 |
nicklas |
1004 |
The window consists of two parts, the upper part where the file |
3345 |
16 May 07 |
martin |
1005 |
to parse and the parameters used to parse it are entered, and |
3339 |
15 May 07 |
nicklas |
1006 |
the lower part that displays information about the parsing. |
3339 |
15 May 07 |
nicklas |
1007 |
</para> |
3339 |
15 May 07 |
nicklas |
1008 |
|
3339 |
15 May 07 |
nicklas |
1009 |
<variablelist> |
3339 |
15 May 07 |
nicklas |
1010 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1011 |
<term><guilabel>File to test</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1012 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1013 |
<para> |
3686 |
20 Aug 07 |
jari |
1014 |
The path and file name of the file to use for testing. |
3394 |
28 May 07 |
martin |
1015 |
Use the &gbBrowse; button to |
3339 |
15 May 07 |
nicklas |
1016 |
select a file from the BASE file system or upload |
3339 |
15 May 07 |
nicklas |
1017 |
a new file. Click on the <guibutton>Parse the file</guibutton> |
3339 |
15 May 07 |
nicklas |
1018 |
button to start parsing. The lower part will update itself with |
3339 |
15 May 07 |
nicklas |
1019 |
information about the parsed file. The file must follow a few simple rules: |
3339 |
15 May 07 |
nicklas |
1020 |
|
3339 |
15 May 07 |
nicklas |
1021 |
<itemizedlist> |
3339 |
15 May 07 |
nicklas |
1022 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1023 |
<para>Data must be organised into columns, with one record per line.</para> |
3339 |
15 May 07 |
nicklas |
1024 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1025 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1026 |
<para> |
3339 |
15 May 07 |
nicklas |
1027 |
Each data column must be separated by some special character or |
3345 |
16 May 07 |
martin |
1028 |
character sequence not occurring in the data, for example a tab or a comma. |
3339 |
15 May 07 |
nicklas |
1029 |
Data in fixed-size columns cannot be parsed. |
3339 |
15 May 07 |
nicklas |
1030 |
</para> |
3339 |
15 May 07 |
nicklas |
1031 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1032 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1033 |
<para> |
3345 |
16 May 07 |
martin |
1034 |
Data may optionally be preceded by a data header, for example, |
3339 |
15 May 07 |
nicklas |
1035 |
the names of the columns. |
3339 |
15 May 07 |
nicklas |
1036 |
</para> |
3339 |
15 May 07 |
nicklas |
1037 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1038 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1039 |
<para> |
3345 |
16 May 07 |
martin |
1040 |
The data header may optionally be preceded by file headers. |
3339 |
15 May 07 |
nicklas |
1041 |
A file header is something that can be split into a name-value pair. |
3339 |
15 May 07 |
nicklas |
1042 |
</para> |
3339 |
15 May 07 |
nicklas |
1043 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1044 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1045 |
<para> |
3339 |
15 May 07 |
nicklas |
1046 |
The file may contain comments, which are ignored by the parser. |
3339 |
15 May 07 |
nicklas |
1047 |
</para> |
3339 |
15 May 07 |
nicklas |
1048 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1049 |
</itemizedlist> |
3339 |
15 May 07 |
nicklas |
1050 |
</para> |
3339 |
15 May 07 |
nicklas |
1051 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1052 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1053 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1054 |
<term><guilabel>Lines to parse</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1055 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1056 |
<para> |
4441 |
03 Sep 08 |
jari |
1057 |
The number of lines to parse. The default is 100 and |
4441 |
03 Sep 08 |
jari |
1058 |
rarely needs to be changed. One reason to increase the |
4441 |
03 Sep 08 |
jari |
1059 |
number is when the data header line is beyond the default |
4441 |
03 Sep 08 |
jari |
1060 |
value. |
3339 |
15 May 07 |
nicklas |
1061 |
</para> |
3339 |
15 May 07 |
nicklas |
1062 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1063 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1064 |
<varlistentry> |
4419 |
27 Aug 08 |
nicklas |
1065 |
<term><guilabel>Character set</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1066 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1067 |
<para> |
4419 |
27 Aug 08 |
nicklas |
1068 |
The character set used in the file. The default |
4419 |
27 Aug 08 |
nicklas |
1069 |
is ISO-8859-1 (same as Latin-1). This list contains all character sets |
4441 |
03 Sep 08 |
jari |
1070 |
supported by the underlying Java run-time and can be quite long. |
3339 |
15 May 07 |
nicklas |
1071 |
</para> |
3339 |
15 May 07 |
nicklas |
1072 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1073 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1074 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1075 |
<term><guilabel>Header regexp</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1076 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1077 |
<para> |
3339 |
15 May 07 |
nicklas |
1078 |
A regular expression matching a header line. A header |
3339 |
15 May 07 |
nicklas |
1079 |
is a key-value pair with information about the |
3339 |
15 May 07 |
nicklas |
1080 |
data in the file. The regular expression must contain two capturing groups, |
3339 |
15 May 07 |
nicklas |
1081 |
the first should capture the name and the second the value of the header. |
3339 |
15 May 07 |
nicklas |
1082 |
For example, the file contains headers like: |
3339 |
15 May 07 |
nicklas |
1083 |
<screen> |
3339 |
15 May 07 |
nicklas |
1084 |
"Type=GenePix Results 3" |
3339 |
15 May 07 |
nicklas |
1085 |
"DateTime=2006/05/16 13:17:59" |
3339 |
15 May 07 |
nicklas |
1086 |
</screen> |
3339 |
15 May 07 |
nicklas |
1087 |
To match this we can use the following regular expression: |
3339 |
15 May 07 |
nicklas |
1088 |
<userinput>"(.*)=(.*)"</userinput>. |
3339 |
15 May 07 |
nicklas |
1089 |
</para> |
3339 |
15 May 07 |
nicklas |
1090 |
|
3339 |
15 May 07 |
nicklas |
1091 |
<para> |
3394 |
28 May 07 |
martin |
1092 |
Use the &gbPredefined; button to select from a |
3339 |
15 May 07 |
nicklas |
1093 |
list of common regular expressions. |
3339 |
15 May 07 |
nicklas |
1094 |
</para> |
3339 |
15 May 07 |
nicklas |
1095 |
|
3339 |
15 May 07 |
nicklas |
1096 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1097 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1098 |
|
3339 |
15 May 07 |
nicklas |
1099 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1100 |
<term><guilabel>Data splitter regexp</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1101 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1102 |
<para> |
3339 |
15 May 07 |
nicklas |
1103 |
A regular expression used to split a data line into columns. For |
3339 |
15 May 07 |
nicklas |
1104 |
example, <userinput>\t</userinput> to split on tabs. Use |
3394 |
28 May 07 |
martin |
1105 |
&gbPredefined; button to select from a list of |
3339 |
15 May 07 |
nicklas |
1106 |
common regular expressions. |
3339 |
15 May 07 |
nicklas |
1107 |
</para> |
3339 |
15 May 07 |
nicklas |
1108 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1109 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1110 |
|
3339 |
15 May 07 |
nicklas |
1111 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1112 |
<term><guilabel>Ignore regexp</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1113 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1114 |
<para> |
3339 |
15 May 07 |
nicklas |
1115 |
A regular expression that matches all lines that should be ignored. |
3339 |
15 May 07 |
nicklas |
1116 |
For example, <userinput>\#.*</userinput> to ignore all lines starting with |
3339 |
15 May 07 |
nicklas |
1117 |
a #. Use |
3394 |
28 May 07 |
martin |
1118 |
&gbPredefined; button to select from a list of |
3339 |
15 May 07 |
nicklas |
1119 |
common regular expressions. |
3339 |
15 May 07 |
nicklas |
1120 |
</para> |
3339 |
15 May 07 |
nicklas |
1121 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1122 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1123 |
|
3339 |
15 May 07 |
nicklas |
1124 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1125 |
<term><guilabel>Data header regexp</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1126 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1127 |
<para> |
3339 |
15 May 07 |
nicklas |
1128 |
A regular expression that matches the line containing the data header. |
3339 |
15 May 07 |
nicklas |
1129 |
Usually the data header contains the column names separated with the |
3339 |
15 May 07 |
nicklas |
1130 |
same separator as the data. For example, the file contains a header |
3339 |
15 May 07 |
nicklas |
1131 |
like: |
3339 |
15 May 07 |
nicklas |
1132 |
<screen> |
3339 |
15 May 07 |
nicklas |
1133 |
"Block"{tab}"Column"{tab}"Row"{tab}"Name"{tab}"ID" ...and so on |
3339 |
15 May 07 |
nicklas |
1134 |
</screen> |
3339 |
15 May 07 |
nicklas |
1135 |
To match this we can use the following regular expression: |
3339 |
15 May 07 |
nicklas |
1136 |
<userinput>"Block"\t"Column"\t"Row"\t"Name"\t"ID".*</userinput>. |
3339 |
15 May 07 |
nicklas |
1137 |
</para> |
3339 |
15 May 07 |
nicklas |
1138 |
|
3339 |
15 May 07 |
nicklas |
1139 |
<para> |
3339 |
15 May 07 |
nicklas |
1140 |
The easiest way to set this regular is expression is to leave it empty |
3339 |
15 May 07 |
nicklas |
1141 |
to start with, click on the <guibutton>Parse the file</guibutton> button. |
4441 |
03 Sep 08 |
jari |
1142 |
Then, in the <guilabel>File data</guilabel> tab, use the drop-down lists |
3339 |
15 May 07 |
nicklas |
1143 |
in the <guilabel>Use as</guilabel> column to select the line containing the |
3339 |
15 May 07 |
nicklas |
1144 |
data header. BASE will automatically generate a regular expression matching |
3339 |
15 May 07 |
nicklas |
1145 |
the line. |
3339 |
15 May 07 |
nicklas |
1146 |
</para> |
3339 |
15 May 07 |
nicklas |
1147 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1148 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1149 |
|
3339 |
15 May 07 |
nicklas |
1150 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1151 |
<term><guilabel>Date footer regexp</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1152 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1153 |
<para> |
3339 |
15 May 07 |
nicklas |
1154 |
A regular expression that matches the first line of non-data after |
3339 |
15 May 07 |
nicklas |
1155 |
all data lines. In most cases you can leave this empty. |
3339 |
15 May 07 |
nicklas |
1156 |
</para> |
3339 |
15 May 07 |
nicklas |
1157 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1158 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1159 |
|
3339 |
15 May 07 |
nicklas |
1160 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1161 |
<term><guilabel>Min and max data columns</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1162 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1163 |
<para> |
3339 |
15 May 07 |
nicklas |
1164 |
If you specify values a data line is ignored if the number of |
3487 |
13 Jun 07 |
peter |
1165 |
columns does not fall within the range. If your data file does not have |
3339 |
15 May 07 |
nicklas |
1166 |
a data header with column names you can use these settings to find the |
3339 |
15 May 07 |
nicklas |
1167 |
start of data. |
3339 |
15 May 07 |
nicklas |
1168 |
</para> |
3339 |
15 May 07 |
nicklas |
1169 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1170 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1171 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1172 |
<term><guilabel>Remove quotes</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1173 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1174 |
<para> |
3339 |
15 May 07 |
nicklas |
1175 |
If enabled, the parser will remove quotes around data entries. |
3339 |
15 May 07 |
nicklas |
1176 |
</para> |
3339 |
15 May 07 |
nicklas |
1177 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1178 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1179 |
|
3339 |
15 May 07 |
nicklas |
1180 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1181 |
<term><guilabel>File data</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1182 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1183 |
<para> |
3339 |
15 May 07 |
nicklas |
1184 |
Press the <guilabel>Parse the file</guilabel> button |
3339 |
15 May 07 |
nicklas |
1185 |
to start parsing the file. This tab will be updated with the data |
3339 |
15 May 07 |
nicklas |
1186 |
from the file, organised as a table. For each line the following information |
3339 |
15 May 07 |
nicklas |
1187 |
is displayed: |
3339 |
15 May 07 |
nicklas |
1188 |
<itemizedlist> |
3339 |
15 May 07 |
nicklas |
1189 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1190 |
<para> |
3339 |
15 May 07 |
nicklas |
1191 |
<emphasis>Line</emphasis>: The line number in the file |
3339 |
15 May 07 |
nicklas |
1192 |
</para> |
3339 |
15 May 07 |
nicklas |
1193 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1194 |
|
3339 |
15 May 07 |
nicklas |
1195 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1196 |
<para> |
3339 |
15 May 07 |
nicklas |
1197 |
<emphasis>Columns</emphasis>: The number of columns the line could be |
3339 |
15 May 07 |
nicklas |
1198 |
split into with the data splitter regular expression. |
3339 |
15 May 07 |
nicklas |
1199 |
</para> |
3339 |
15 May 07 |
nicklas |
1200 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1201 |
|
3339 |
15 May 07 |
nicklas |
1202 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1203 |
<para> |
3339 |
15 May 07 |
nicklas |
1204 |
<emphasis>Type</emphasis>: The type of line as detected by the parser. |
3339 |
15 May 07 |
nicklas |
1205 |
It should be one of the following: <emphasis>Unknown</emphasis>, |
3339 |
15 May 07 |
nicklas |
1206 |
<emphasis>Header</emphasis>, <emphasis>Data header</emphasis>, |
3339 |
15 May 07 |
nicklas |
1207 |
<emphasis>Data</emphasis> or <emphasis>Data footer</emphasis>. |
3339 |
15 May 07 |
nicklas |
1208 |
</para> |
3339 |
15 May 07 |
nicklas |
1209 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1210 |
|
3339 |
15 May 07 |
nicklas |
1211 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1212 |
<para> |
4441 |
03 Sep 08 |
jari |
1213 |
<emphasis>Use as</emphasis>: Use the drop-down lists to use a |
3339 |
15 May 07 |
nicklas |
1214 |
line as either the data header or data footer. BASE will automatically |
3339 |
15 May 07 |
nicklas |
1215 |
generate a regular expression. |
3339 |
15 May 07 |
nicklas |
1216 |
</para> |
3339 |
15 May 07 |
nicklas |
1217 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1218 |
|
3339 |
15 May 07 |
nicklas |
1219 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1220 |
<para> |
3339 |
15 May 07 |
nicklas |
1221 |
<emphasis>File data</emphasis>: The contents of the file after |
3339 |
15 May 07 |
nicklas |
1222 |
splitting and, optionally, removal of quotes. |
3339 |
15 May 07 |
nicklas |
1223 |
</para> |
3339 |
15 May 07 |
nicklas |
1224 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1225 |
</itemizedlist> |
3339 |
15 May 07 |
nicklas |
1226 |
|
3339 |
15 May 07 |
nicklas |
1227 |
</para> |
3339 |
15 May 07 |
nicklas |
1228 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1229 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1230 |
<varlistentry> |
3339 |
15 May 07 |
nicklas |
1231 |
<term><guilabel>Column mappings</guilabel></term> |
3339 |
15 May 07 |
nicklas |
1232 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1233 |
<para> |
4441 |
03 Sep 08 |
jari |
1234 |
After defining the data header you may need to press |
4441 |
03 Sep 08 |
jari |
1235 |
the <guilabel>Parse the file</guilabel> button to make |
4441 |
03 Sep 08 |
jari |
1236 |
this tab visible because this tab is only displayed when |
4441 |
03 Sep 08 |
jari |
1237 |
data has been found in the file and a data header was |
4441 |
03 Sep 08 |
jari |
1238 |
recognized. It allows you to easily select the mapping |
4441 |
03 Sep 08 |
jari |
1239 |
between columns in the file and the properties in the |
4441 |
03 Sep 08 |
jari |
1240 |
database. |
3339 |
15 May 07 |
nicklas |
1241 |
</para> |
3339 |
15 May 07 |
nicklas |
1242 |
<nohelp> |
3339 |
15 May 07 |
nicklas |
1243 |
<figure id="plugins.figures.testwithfilemappings"> |
3339 |
15 May 07 |
nicklas |
1244 |
<title>Mapping columns from a file</title> |
3339 |
15 May 07 |
nicklas |
1245 |
<screenshot> |
3339 |
15 May 07 |
nicklas |
1246 |
<mediaobject> |
3339 |
15 May 07 |
nicklas |
1247 |
<imageobject><imagedata |
3943 |
09 Nov 07 |
nicklas |
1248 |
scalefit="1" width="100%" |
3339 |
15 May 07 |
nicklas |
1249 |
fileref="figures/test_with_file_mappings.png" format="PNG" |
3339 |
15 May 07 |
nicklas |
1250 |
/></imageobject> |
3339 |
15 May 07 |
nicklas |
1251 |
</mediaobject> |
3339 |
15 May 07 |
nicklas |
1252 |
</screenshot> |
3339 |
15 May 07 |
nicklas |
1253 |
</figure> |
3339 |
15 May 07 |
nicklas |
1254 |
</nohelp> |
3339 |
15 May 07 |
nicklas |
1255 |
|
3339 |
15 May 07 |
nicklas |
1256 |
<itemizedlist> |
3339 |
15 May 07 |
nicklas |
1257 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1258 |
<para> |
3339 |
15 May 07 |
nicklas |
1259 |
<emphasis>Mapping style</emphasis>: The type |
3339 |
15 May 07 |
nicklas |
1260 |
of mapping to use when you pick a column from the |
3339 |
15 May 07 |
nicklas |
1261 |
<emphasis>File columns</emphasis> list boxes. |
3339 |
15 May 07 |
nicklas |
1262 |
</para> |
3339 |
15 May 07 |
nicklas |
1263 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1264 |
|
3339 |
15 May 07 |
nicklas |
1265 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1266 |
<para> |
3339 |
15 May 07 |
nicklas |
1267 |
<emphasis>Property</emphasis>: The database property. |
3339 |
15 May 07 |
nicklas |
1268 |
</para> |
3339 |
15 May 07 |
nicklas |
1269 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1270 |
|
3339 |
15 May 07 |
nicklas |
1271 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1272 |
<para> |
3339 |
15 May 07 |
nicklas |
1273 |
<emphasis>Mapping expression</emphasis>: An expression that |
3339 |
15 May 07 |
nicklas |
1274 |
maps the data in the file columns to the property in the |
3339 |
15 May 07 |
nicklas |
1275 |
database. There are two types of mappings, simple and expressions. |
3339 |
15 May 07 |
nicklas |
1276 |
A simple mapping is a string template with placeholders for data |
3339 |
15 May 07 |
nicklas |
1277 |
from the file. An expression mapping starts with an equal sign and |
3339 |
15 May 07 |
nicklas |
1278 |
is evaluated dynamically for each line of data. The simple |
3339 |
15 May 07 |
nicklas |
1279 |
mapping has better performance and we recommend that you use |
3339 |
15 May 07 |
nicklas |
1280 |
it unless you have to recalculate any of the numerical values. |
3911 |
06 Nov 07 |
nicklas |
1281 |
In both cases, if no column matching the placeholder exactly is found |
3911 |
06 Nov 07 |
nicklas |
1282 |
the placeholder is interpreted as a regular expression that |
3911 |
06 Nov 07 |
nicklas |
1283 |
is matched against each column. The first one found is used. |
4441 |
03 Sep 08 |
jari |
1284 |
A few mapping examples are listed in |
4441 |
03 Sep 08 |
jari |
1285 |
<xref linkend="plugins.configuration.testwithfile.mappings" |
4441 |
03 Sep 08 |
jari |
1286 |
/>. |
3339 |
15 May 07 |
nicklas |
1287 |
</para> |
4441 |
03 Sep 08 |
jari |
1288 |
|
4441 |
03 Sep 08 |
jari |
1289 |
<table frame="all" id="plugins.configuration.testwithfile.mappings"> |
4441 |
03 Sep 08 |
jari |
1290 |
<title>Mapping expression examples</title> |
5801 |
12 Oct 11 |
nicklas |
1291 |
<tgroup cols="2" align="center"> |
5801 |
12 Oct 11 |
nicklas |
1292 |
<colspec colname="expression" align="left"/> |
5801 |
12 Oct 11 |
nicklas |
1293 |
<colspec colname="explanation" align="left"/> |
4441 |
03 Sep 08 |
jari |
1294 |
<thead> |
4441 |
03 Sep 08 |
jari |
1295 |
<row> |
4441 |
03 Sep 08 |
jari |
1296 |
<entry> |
4441 |
03 Sep 08 |
jari |
1297 |
Expression |
4441 |
03 Sep 08 |
jari |
1298 |
</entry> |
4441 |
03 Sep 08 |
jari |
1299 |
<entry> |
4441 |
03 Sep 08 |
jari |
1300 |
Explanation |
4441 |
03 Sep 08 |
jari |
1301 |
</entry> |
4441 |
03 Sep 08 |
jari |
1302 |
</row> |
4441 |
03 Sep 08 |
jari |
1303 |
</thead> |
4441 |
03 Sep 08 |
jari |
1304 |
<tbody> |
4441 |
03 Sep 08 |
jari |
1305 |
<row> |
4441 |
03 Sep 08 |
jari |
1306 |
<entry> |
4441 |
03 Sep 08 |
jari |
1307 |
<constant>\Name\</constant> |
4441 |
03 Sep 08 |
jari |
1308 |
</entry> |
4441 |
03 Sep 08 |
jari |
1309 |
<entry> |
4441 |
03 Sep 08 |
jari |
1310 |
Exact match is required. |
4441 |
03 Sep 08 |
jari |
1311 |
</entry> |
4441 |
03 Sep 08 |
jari |
1312 |
</row> |
4441 |
03 Sep 08 |
jari |
1313 |
<row> |
4441 |
03 Sep 08 |
jari |
1314 |
<entry> |
4441 |
03 Sep 08 |
jari |
1315 |
<constant>\1\</constant> |
4441 |
03 Sep 08 |
jari |
1316 |
</entry> |
4441 |
03 Sep 08 |
jari |
1317 |
<entry> |
4441 |
03 Sep 08 |
jari |
1318 |
Column with index 1 (the second column). |
4441 |
03 Sep 08 |
jari |
1319 |
</entry> |
4441 |
03 Sep 08 |
jari |
1320 |
</row> |
4441 |
03 Sep 08 |
jari |
1321 |
<row> |
4441 |
03 Sep 08 |
jari |
1322 |
<entry> |
4441 |
03 Sep 08 |
jari |
1323 |
<constant>[\row\, \column\]</constant> |
4441 |
03 Sep 08 |
jari |
1324 |
</entry> |
4441 |
03 Sep 08 |
jari |
1325 |
<entry> |
4441 |
03 Sep 08 |
jari |
1326 |
Combining row and column to a single coordinate. |
4441 |
03 Sep 08 |
jari |
1327 |
</entry> |
4441 |
03 Sep 08 |
jari |
1328 |
</row> |
4441 |
03 Sep 08 |
jari |
1329 |
<row> |
4441 |
03 Sep 08 |
jari |
1330 |
<entry> |
4441 |
03 Sep 08 |
jari |
1331 |
<constant>=2 * col('radius')</constant> |
4441 |
03 Sep 08 |
jari |
1332 |
</entry> |
4441 |
03 Sep 08 |
jari |
1333 |
<entry> |
4441 |
03 Sep 08 |
jari |
1334 |
Calculate the diameter dynamically. |
4441 |
03 Sep 08 |
jari |
1335 |
</entry> |
4441 |
03 Sep 08 |
jari |
1336 |
</row> |
4441 |
03 Sep 08 |
jari |
1337 |
<row> |
4441 |
03 Sep 08 |
jari |
1338 |
<entry> |
4441 |
03 Sep 08 |
jari |
1339 |
<constant>\F63(3|5) Median\</constant> |
4441 |
03 Sep 08 |
jari |
1340 |
</entry> |
4441 |
03 Sep 08 |
jari |
1341 |
<entry> |
4441 |
03 Sep 08 |
jari |
1342 |
Use regular expression to match either F633 or |
4441 |
03 Sep 08 |
jari |
1343 |
F635. |
4441 |
03 Sep 08 |
jari |
1344 |
</entry> |
4441 |
03 Sep 08 |
jari |
1345 |
</row> |
4441 |
03 Sep 08 |
jari |
1346 |
<row> |
4441 |
03 Sep 08 |
jari |
1347 |
<entry> |
4441 |
03 Sep 08 |
jari |
1348 |
<constant>constant_string</constant> |
4441 |
03 Sep 08 |
jari |
1349 |
</entry> |
4441 |
03 Sep 08 |
jari |
1350 |
<entry> |
4441 |
03 Sep 08 |
jari |
1351 |
Use <constant>constant_string</constant> as |
4441 |
03 Sep 08 |
jari |
1352 |
value for this column for each line. |
4441 |
03 Sep 08 |
jari |
1353 |
</entry> |
4441 |
03 Sep 08 |
jari |
1354 |
</row> |
4441 |
03 Sep 08 |
jari |
1355 |
</tbody> |
4441 |
03 Sep 08 |
jari |
1356 |
</tgroup> |
4441 |
03 Sep 08 |
jari |
1357 |
</table> |
3339 |
15 May 07 |
nicklas |
1358 |
|
3339 |
15 May 07 |
nicklas |
1359 |
<note> |
3339 |
15 May 07 |
nicklas |
1360 |
Column numbers are 0-based. We recommend that you use |
3339 |
15 May 07 |
nicklas |
1361 |
column names at all times if they are present in the |
3339 |
15 May 07 |
nicklas |
1362 |
file. |
3339 |
15 May 07 |
nicklas |
1363 |
</note> |
3339 |
15 May 07 |
nicklas |
1364 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1365 |
|
3339 |
15 May 07 |
nicklas |
1366 |
<listitem> |
3339 |
15 May 07 |
nicklas |
1367 |
<para> |
4419 |
27 Aug 08 |
nicklas |
1368 |
<emphasis>Auto generate</emphasis>: Click on this button to |
4419 |
27 Aug 08 |
nicklas |
1369 |
let BASE try to automatically generate mappings based on |
4419 |
27 Aug 08 |
nicklas |
1370 |
fuzzy string matching between the property names and file |
4419 |
27 Aug 08 |
nicklas |
1371 |
column headers. Each match get a score between 0 and 1 |
4441 |
03 Sep 08 |
jari |
1372 |
where 1 indicates a better match. Use the <emphasis>similarity |
4419 |
27 Aug 08 |
nicklas |
1373 |
score</emphasis> to limit the automatically generated mappings to |
4419 |
27 Aug 08 |
nicklas |
1374 |
matches with at least the given score. A value between 0.7 and 0.9 |
4419 |
27 Aug 08 |
nicklas |
1375 |
is usually a good choice. |
4419 |
27 Aug 08 |
nicklas |
1376 |
</para> |
4419 |
27 Aug 08 |
nicklas |
1377 |
</listitem> |
4419 |
27 Aug 08 |
nicklas |
1378 |
|
4419 |
27 Aug 08 |
nicklas |
1379 |
<listitem> |
4419 |
27 Aug 08 |
nicklas |
1380 |
<para> |
3339 |
15 May 07 |
nicklas |
1381 |
<emphasis>File columns</emphasis>: Lists of column found in the file. |
3339 |
15 May 07 |
nicklas |
1382 |
Select a value from this list to let BASE automatically |
3339 |
15 May 07 |
nicklas |
1383 |
generate a mapping that picks the selected column. |
3339 |
15 May 07 |
nicklas |
1384 |
</para> |
3339 |
15 May 07 |
nicklas |
1385 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1386 |
</itemizedlist> |
3339 |
15 May 07 |
nicklas |
1387 |
</listitem> |
3339 |
15 May 07 |
nicklas |
1388 |
</varlistentry> |
3339 |
15 May 07 |
nicklas |
1389 |
</variablelist> |
3339 |
15 May 07 |
nicklas |
1390 |
|
3339 |
15 May 07 |
nicklas |
1391 |
</helptext> |
3339 |
15 May 07 |
nicklas |
1392 |
|
3339 |
15 May 07 |
nicklas |
1393 |
|
3329 |
11 May 07 |
nicklas |
1394 |
</sect2> |
5178 |
02 Nov 09 |
jari |
1395 |
|
3329 |
11 May 07 |
nicklas |
1396 |
</sect1> |
3329 |
11 May 07 |
nicklas |
1397 |
|
3329 |
11 May 07 |
nicklas |
1398 |
|
3374 |
24 May 07 |
jari |
1399 |
</chapter> |