source: release-kits/lirk3/bin/ant-installer/web/.bak/manual-print.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 56.9 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4 <title>Ant Installer</title>
5 <link href="style-print.css" type="text/css" rel="stylesheet">
6 <link rel="SHORTCUT ICON" href="images/antinstaller-icon.png">
7 <meta name="keywords"
8 content="Ant, installer, AntInstall, gui, console, input, parameters, properties, swing, user interface, valiation, configuration">
9</head>
10<body>
11<table cellspacing="0" width="100%">
12 <tbody>
13 <tr class="tpheader">
14 <th class="tpleft">
15 </th>
16 <th class="tptop" valign="bottom">
17 <img src="space.gif" height="1" width="440"><br>
18
19 <table>
20 <tr>
21 <td valign="top">
22 <div class="tpheadertitle">AntInstaller</div>
23 <!--img src="images/ant-install-title.png" alt="AntInstaller"/-->
24 </td>
25 <td width="100%" align="right" valign="bottom" nowrap="true">
26 <div class="tpraised">
27 <a class="tpbutton" href="index.html">home</a>
28 <a class="tpbutton" href="http://sourceforge.net/project/showfiles.php?group_id=123466&amp;package_id=134917">download</a>
29 <a class="tpbutton" href="http://sf.net">sourceforge</a>
30 <a class="tpbutton" href="manual/manual/index.html">antmanual</a>
31 <a class="tpbutton" href="http://sourceforge.net/tracker/?group_id=123466&amp;atid=696615">RFEs</a>
32 <a class="tpbutton" href="http://sourceforge.net/tracker/?group_id=123466&amp;atid=696612">Bugs</a></div>
33 </td>
34 </tr>
35 </table>
36 </th>
37 </tr>
38 <tr class="tpbody">
39 <td valign="bottom">
40 <br/>
41 <br/><br/></td>
42 <td class="tpright" valign="top">
43 <div class="tpcontent">
44 <!--[segment-content] page content start -->
45 <div align="right"><a href="manual-print.html">Printable version</a></div>
46 <h2>Manual</h2>
47To set up an AntInstall there are a few requirements.
48 <ul>
49 <li>The <a href="#config"><code>antinstall-config.xml</code></a> file to describe
50the installation</li>
51 <li>The <code>build.xml</code> ant script to run, with targets
52that should match values in <code>antinstall-config.xml</code> </li>
53 <li>The resources to run the installer e.g. antinstaller.jar
54and ant.jar</li>
55 <li>The <a href="#scripts">scripts</a> to run the installer e.g. <code>install.sh</code></li>
56 <li>The resources to install</li>
57 </ul>
58 <ul>
59 <li>The installer can be delivered as a <a href="#extractor">self extracting JAR</a></li>
60 <li>The installer can be run directly form the Jar see <a href="#non-extractor">non extracting JAR</a>
61 Resources are extracted from the Jar during the Ant build.</li>
62 <li>Since version beta0.5 <a href="#refs">dynamic references</a> can be used in default values.</li>
63 <li>Displaying pages based on user selections on previous pages. <a href="#pagedisplay">Page displaying</a></li>
64 </ul>
65 <a name="config"></a>
66 <h3><code>antinstall-config.xml</code></h3>
67
68This part of the guide is the reference manual for the
69configuration of <code>antinstall-config.xml</code>. The config file
70is a simple XML file that describes the pages to display to the user,
71and the input the user must enter. <br>
72A simple example might be a License page to show the license of the
73software, followed by a page asking the user for their name and email.
74The next page would allow the user to choose the components to install
75(binaries, source, documentation) and the progress page with an install
76button to perform the installation. <br>
77 <br>
78The config file must always have a root element installer with some
79requried attributes as follows. <br>
80 <br>
81 <pre>&lt;installer<br> ui="swing,text"<br> verbose="false"<br> lookAndFeel="com.jgoodies.plaf.plastic.PlasticXPLookAndFeel"<br> name="Test Installer"<br> windowIcon="/resources/gkmain_inv.png"<br> defaultImageResource="/resources/greens.png"<br> minJavaVersion="1.4"&gt;<br> <br> ...<br> </pre>
82The file is then made up of <code>page</code> elements containing <code>input</code>
83elements. <br>
84 <br>
85 <ul>
86 <li><a href="#installer">Installer</a></li>
87 <li><a href="#page">Pages</a>
88 <ul>
89 <li><a href="#pagesplash">Splash Page</a></li>
90 <li><a href="#pagelicense">License Page</a></li>
91 <li><a href="#pageinput">Input Page</a></li>
92 <li><a href="#pageprogress">Progress Page</a></li>
93 </ul>
94 </li>
95 <li><a href="#inputtypes">Input types</a>
96 <ul>
97 <li><a href="#checkbox">Checkbox</a></li>
98 <li><a href="#comment">Comment</a></li>
99 <li><a href="#directory">Directory</a></li>
100 <li><a href="#app-root">Application Root</a></li>
101 <li><a href="#file">File</a></li>
102 <li><a href="#select">Select</a></li>
103 <li><a href="#target-select">Target Select</a></li>
104 <li><a href="#large-select">Large Select</a></li>
105 <li><a href="#target">Target</a></li>
106 <li><a href="#text">Unvalidated Text</a></li>
107 <li><a href="#validated">Validated Text</a></li>
108 <li><a href="#extvalidated">Externally Validated Text</a></li>
109 <li><a href="#date">Date</a></li>
110 <li><a href="#password">Password Text</a></li>
111 </ul>
112 </li>
113 </ul>
114 <br>
115 <br>
116 <table class="manual" cellspacing="0">
117 <tbody>
118 <tr class="tpheader">
119 <th class="manual" colspan="3"><a name="installer">&lt;installer&gt;</a></th>
120 </tr>
121 <tr>
122 <td colspan="3">The <code>installer</code> element is
123the root element of the config and has the following attributes.</td>
124 </tr>
125 <tr class="tpheader">
126 <th class="manual2">Attribute</th>
127 <th class="manual2">Description</th>
128 <th class="manual2">Example</th>
129 </tr>
130 <tr>
131 <td>ui</td>
132 <td>Indicates the supported installation modes</td>
133 <td>swing,text</td>
134 </tr>
135 <tr>
136 <td>verbose</td>
137 <td>Print more info the the install log file and more
138info in the <code>ant.install.properties</code> file. N.B. the properties file may not be written if the installer
139can not write to the current directory.</td>
140 <td>true</td>
141 </tr>
142 <tr>
143 <td>debug</td>
144 <td>Setting this flag prevents the temporary directory from being deleted on exit, this is useful for debugging
145 install scripts. It should normally be set to false or ommited for a final installer. </td>
146 <td>false</td>
147 </tr>
148 <tr>
149 <td>lookAndFeel</td>
150 <td>The LookAndFeel class for the installer or one of the standard entries. The classes must be on the classpath in the installer start script or inside the installer Jar. There are a few standarad entries for this
151field to set default LookAndFeels.
152<ul>
153<li><code>"null"</code> - The string "null" is used to set the default LookAndFeel determined by Java (no extra classes required)</li>
154<li><code>"jgoodies"</code> - Used to set the default LookAndFeel for AntInstaller org.tp23.jgoodies.plaf.plastic.PlasticXPLookAndFeel
155(<code>jgoodies-edited-1_2_2.jar</code> or it contents must be on the classpath)</li>
156<li><code>"native"</code> - Used to set the native LookAndFeel for the runtime Operating System (no extra classes required)</li>
157<li><code>"greymetal"</code> - Used to set the cutdown MetalLookAndFeel included with AntInstaller. This is the same as MetalLookAndFeel witha grey theme and no bold fonts unless specified in the <code>antinstall-config.xml</code> file (no extra classes required)</li>
158</ul>
159If the lookAndFeel attribute is missing <code>jgoodies</code> is assumed. If the LookAndFeel can not be loaded a message will be added to the log file and the install will continue with the Java default.
160 </td>
161 <td>
162 net.sourceforge.mlf.metouia.<br/>MetouiaLookAndFeel<br/><br/>
163 jgoodies</td>
164 </tr>
165 <tr>
166 <td>name</td>
167 <td>The name of the installer, this will appear in the
168title of the installer GUI window.</td>
169 <td>My Installer</td>
170 </tr>
171 <tr>
172 <td>windowIcon</td>
173 <td>This is the resource name of the icon for the
174installer window. It is a string that is used to load the resource from
175the classpath so the image must be in one of the jars on the classpath
176of the install start script. In the self installer it must be in the correct directory
177of the Jar.</td>
178 <td>/resources/gkmain_inv.png</td>
179 </tr>
180 <tr>
181 <td>defaultImageResource</td>
182 <td>This is the resource image used for the top of the
183installer GUI by default, it can be overridden for individual pages.</td>
184 <td>/resources/greens.png</td>
185 </tr>
186 <tr>
187 <td>minJavaVersion</td>
188 <td>The minimum Java version for the installer, this is
189currently not supported, but will be in future versions.</td>
190 <td>1.4</td>
191 </tr>
192 <tr>
193 <td>finishButtonText</td>
194 <td>The text displayed on the install button. If not specified, the default is "Install". This has been
195 added since Antinstaller can be used as a GUI for other Ant builds, in which case "Build" would
196 be more appropriate.</td>
197 <td>Install</td>
198 </tr>
199 <tr>
200 <td>antialiased</td>
201 <td>If this attribute is set to <code>true</code> and the LookAndFeel is <code>org.tp23.jgoodies.plaf.plastic.PlasticXPLookAndFeel</code> or <code>jgoodies</code> the Swing GUI will render using Java 2D antialiasing for the text. This is resource intensive and may slow
202 the GUI down unacceptably on older PCs, but does look better.</td>
203 <td>false</td>
204 </tr>
205 </tbody>
206 </table>
207 <br>
208 <br>
209 <table class="manual" cellspacing="0">
210 <tbody>
211 <tr class="tpheader">
212 <th class="manual" colspan="3"><a name="page">&lt;page&gt;</a></th>
213 </tr>
214 <tr>
215 <td colspan="3">Pages entries in the XML file represent a
216single window in the installer moved through by the user by selecting
217"Next &gt;&gt;" (or pressing enter) all pages have the following
218atributes.</td>
219 </tr>
220 <tr class="tpheader">
221 <th class="manual2">Attribute</th>
222 <th class="manual2">Description</th>
223 <th class="manual2">Example</th>
224 </tr>
225 <tr>
226 <td><b>type</b></td>
227 <td>The type of page one of four options, progress,
228license, splash or input.</td>
229 <td>input</td>
230 </tr>
231 <tr>
232 <td>name</td>
233 <td>A unique name for the page.</td>
234 <td>User properties</td>
235 </tr>
236 <tr>
237 <td>displayText</td>
238 <td>The text to be shown at the top of the page.</td>
239 <td>Install Options</td>
240 </tr>
241 <tr>
242 <td>imageResource</td>
243 <td>The image to be shown at the top of the page, overriding the defaultImageResource defined
244 in the installer element.</td>
245 <td>Install Options</td>
246 </tr>
247 <tr>
248 <td>target</td>
249 <td>An ant target that will always be run from the <code>build.xml</code>
250file. This attribute is optional see the Target input type if you wish
251to show a targets that can be selected by the user.</td>
252 <td>clean</td>
253 </tr>
254 </tbody>
255 </table>
256 <br>
257 <br>
258 <table class="manual" cellspacing="0">
259 <tbody>
260 <tr class="tpheader">
261 <th class="manual" colspan="3"><a name="splash">&lt;page
262type="splash"&gt;</a></th>
263 </tr>
264 <tr>
265 <td colspan="3">Displays a graphical image page in the Swing GUI</td>
266 </tr>
267 <tr class="tpheader">
268 <th class="manual2">Attribute</th>
269 <th class="manual2">Description</th>
270 <th class="manual2">Example</th>
271 </tr>
272 <tr>
273 <td>splashResource</td>
274 <td>The image resource used for the splash image. The resource must be available on the classpath
275 at runtime.</td>
276 <td>/resources/large-logo-image.png</td>
277 </tr>
278 <tr>
279 <td>altText</td>
280 <td>Alternative text for the console mode</td>
281 <td>Welcome to the installer app</td>
282 </tr>
283 </tbody>
284 </table>
285 <br>
286 <br>
287 <table class="manual" cellspacing="0">
288 <tbody>
289 <tr class="tpheader">
290 <th class="manual" colspan="3"><a name="pagelicense">&lt;page
291type="license"&gt;</a></th>
292 </tr>
293 <tr>
294 <td colspan="3">Shows a single license file in a
295scrollable window to the user.</td>
296 </tr>
297 <tr class="tpheader">
298 <th class="manual2">Attribute</th>
299 <th class="manual2">Description</th>
300 <th class="manual2">Example</th>
301 </tr>
302 <tr>
303 <td>resource</td>
304 <td>The license text file resource, must be on the
305classpath.</td>
306 <td>/resources/GPL.txt</td>
307 </tr>
308 <tr>
309 <td>usePaging</td>
310 <td>In text mode this parameter stops the scrolling of the license text at 20 lines,
311 and provides options to view the next page or skip to the end. The default is false.</td>
312 <td>true</td>
313 </tr>
314 </tbody>
315 </table>
316 <br>
317 <br>
318 <table class="manual" cellspacing="0">
319 <tbody>
320 <tr class="tpheader">
321 <th class="manual" colspan="3"><a name="pageinput">&lt;page
322type="input"&gt;</a>
323 </th>
324 <tr>
325 <td colspan="3">A page for adding input types listed
326below. An installer can have as many input pages as desired. </td>
327 </tr>
328 <tr class="tpheader">
329 <th class="manual2">Attribute</th>
330 <th class="manual2">Description</th>
331 <th class="manual2">Example</th>
332 </tr>
333 <tr>
334 <td>ifTarget</td>
335 <td>This page will be show if the named target has previously been selected. This can be used to
336 conditionally show installation pages when certain parts of the <code>build.xml</code> script are to be run and not
337 if they are to be omitted.</td>
338 <td>documentation</td>
339 </tr>
340 <tr>
341 <td>ifProperty</td>
342 <td>This page will be shown if the property has the correct value. This can be used to
343 conditionally show installation pages when certain properties match
344 The format of the property is simple <code>${name}=value</code>. There must be no spaces
345 and both the property and value are case sensitive. It is a good idea to use a <code>select</code> input type
346 for the value since free text entered by the user is unlikely to match exactly in case and whitespace or use validated
347 text fields.
348N.B. to run tasks based on properties consider the <a href="http://ant-contrib.sourceforge.net">ant-contrib</a> packages. <br/>
349 The new syntax allows for environment variable checks such as <code>${env.DISPLAY}=:0.0</code>
350 <br/><br/>
351 <b>N.B. the old syntax <code>name=value</code> is deprecated.</b> Until the old syntax is removed it is <b>not</b> possible to
352 place and = sign as a property name.<br/>
353 e.g. <code>${prop.col=back}=#0000FF</code> will break the simple parser.
354 <br/><br/>
355 The following operators are supported
356 <ul>
357 <li> = equals. not assignment as in Java</li>
358 <li> == equals same as above for those that wish to be specific</li>
359 <li> != not equals or null</li>
360 <li> $= ends with, the $ is used from regex for end of line</li>
361 <li> ^= starts with, again ^from regular expressions</li>
362 <li> += greater than, only for numbers</li>
363 <li> -= less than, only for numbers. The installer should validate to ensure the property is a valid number
364 or exceptions will be thrown. The rather strange -= and += syntax is used because &gt; and &lt;
365 must be escaped to &amp;gt; and &amp;lt; in XML attributes and the legibility
366 of the configuration files would be impared.</li>
367 <li> !=null not null, the property must be specified. This is usefull for testing the existence of environment variable for example ${env.ANT_HOME}!=null. N.B. the empty string "" also tests to null, if a property exists
368 in the config file it <b>is</b> possible for the user to set the value to null by erasing the text in
369 a text entry type</li>
370 <li> ==null is null or empty</li>
371 </ul>
372 It is probably a bad idea to use any character that is not a letter or number in a property name
373 because these operators may be extended in the future
374 </td>
375 <td>${myProperty}=value23</td>
376 </tr>
377 </tbody>
378 </table>
379 <br>
380 <br>
381 <table class="manual" cellspacing="0">
382 <tbody>
383 <tr class="tpheader">
384 <th class="manual" colspan="3"><a name="pageprogress">&lt;page
385type="progress"&gt;</a></th>
386 </tr>
387 <tr>
388 <td colspan="3">A page for showing the user the progress
389of the installation. This page contains the "Install" Button, so all
390installers should end with a progress page. Currently it is not checked
391that an installer ends with a progress page so the creator of the <code>antinstall-config.xml</code>
392should ensure it does.</td>
393 </tr>
394 <tr>
395 <td>showTargets</td>
396 <td>When this flag is true, in the Swing GUI, a graphical representation of
397 the targets being run and the dependent targets found is displayed.</td>
398 <td>true</td>
399 </tr>
400 </tbody>
401 </table>
402<br><a name="inputtypes"></a><h3>Input Types</h3>
403Input types represent fields in which users can input values or make selections. <br>
404The input type element is
405also used to display text to the user. While there is no limit to the number of comments or text you can add in the
406config file, the GUI only has a limited amount of space. Check your config with your choosen Look And Feel to ensure
407that instructions are not cropped.<br>
408All input types accept the <code>explanatoryText</code> attribute, where multi-line comments can be added.
409The GUI has a fixed width available for the <code>displayText</code> attribute which often does not provide much space.
410Single line comments can be added with the <code>comment</code> type.<br>
411If anyone has a serious requirement to include more text that is currently possible post an RFE and I will look into
412tool tip popups or a scrollable text box or perhaps instructions that can launch in a help window. This has not been added yet
413since it is much more difficult to implement in the command line UI, and as yet we have no requirement.
414<br><br>
415 <table class="manual" cellspacing="0">
416 <tbody>
417 <tr class="tpheader">
418 <th class="manual" colspan="3"><a name="checkbox">&lt;checkbox&gt;</a></th>
419 </tr>
420 <tr>
421 <td colspan="3">The check box input is used for boolean
422input, a check box in the gui and a true false option on the command
423line.</td>
424 </tr>
425 <tr class="tpheader">
426 <th class="manual2">Attribute</th>
427 <th class="manual2">Description</th>
428 <th class="manual2">Example</th>
429 </tr>
430 <tr>
431 <td>property</td>
432 <td>The name of the property to be set in the <code>ant.install.properties</code>
433file the value will be true or false.</td>
434 <td>my.property</td>
435 </tr>
436 <tr>
437 <td>displayText</td>
438 <td>The text to be shown describing the option.</td>
439 <td>Enable all security options</td>
440 </tr>
441 <tr>
442 <td>defaultValue</td>
443 <td>The default for the check box.</td>
444 <td>true</td>
445 </tr>
446 <tr>
447 <td>force</td>
448 <td>Force the option selected to be the default value.
449This can be used to indicate that the option is required. For example,
450an installer could be delivered where "Enable all security options" is
451always selected.</td>
452 <td>false</td>
453 </tr>
454 </tbody>
455 </table>
456 <br/>
457 <table class="manual" cellspacing="0">
458 <tbody>
459 <tr class="tpheader">
460 <th class="manual" colspan="3"><a name="comment">&lt;comment&gt;</a></th>
461 </tr>
462 <tr>
463 <td colspan="3">The comment input displays text to the
464user and does not accept any type of input.</td>
465 </tr>
466 <tr class="tpheader">
467 <th class="manual2">Attribute</th>
468 <th class="manual2">Description</th>
469 <th class="manual2">Example</th>
470 </tr>
471 <tr>
472 <td>displayText</td>
473 <td>The text to be shown describing the option.</td>
474 <td>W</td>
475 </tr>
476 <tr>
477 <td>bold</td>
478 <td>Display the comment in bold, in the GUI version.</td>
479 <td>true</td>
480 </tr>
481 <tr>
482 <td>title</td>
483 <td>Display the comment in a larger font in the GUI or in
484capitals in the command line.</td>
485 <td>false</td>
486 </tr>
487 </tbody>
488 </table>
489 <br/>
490 <table class="manual" cellspacing="0">
491 <tbody>
492 <tr class="tpheader">
493 <th class="manual" colspan="3"><a name="directory">&lt;directory&gt;</a></th>
494 </tr>
495 <tr>
496 <td colspan="3">The directory input allows the user to
497select a directory.</td>
498 </tr>
499 <tr class="tpheader">
500 <th class="manual2">Attribute</th>
501 <th class="manual2">Description</th>
502 <th class="manual2">Example</th>
503 </tr>
504 <tr>
505 <td>property</td>
506 <td>The name of the property to be set in the <code>ant.install.properties</code>
507file the value will be the absolute path to the directory.</td>
508 <td>file.property</td>
509 </tr>
510 <tr>
511 <td>displayText</td>
512 <td>The text to be shown describing the option.</td>
513 <td>Select an installation directory</td>
514 </tr>
515 <tr>
516 <td>defaultValue</td>
517 <td>The default for the directory.</td>
518 <td>/var/log</td>
519 </tr>
520 <tr>
521 <td>defaultValueWin</td>
522 <td>The default for the directory for windows installations.</td>
523 <td>C:\Program Files\myapp</td>
524 </tr>
525 <tr>
526 <td>create</td>
527 <td>If this is true and the directory entered does not
528exist the user will be asked if the directory should be created.</td>
529 <td>true</td>
530 </tr>
531 <tr>
532 <td>checkExists</td>
533 <td>If true the installation will not continue unless the
534directory selected exists. The user will have to select a directory
535that does exist, create it or cancel the install. If create is true and
536the directory does not exist the user simply has to agree to have the
537directory created.</td>
538 <td>false</td>
539 </tr>
540 </tbody>
541 </table>
542 <br/>
543 <table class="manual" cellspacing="0">
544 <tbody>
545 <tr class="tpheader">
546 <th class="manual" colspan="3"><a name="app-root">&lt;app-root&gt;</a></th>
547 </tr>
548 <tr>
549 <td colspan="3">The directory input allows the user to
550select a directory. The existence of files is then checked during
551validation to ensure the user has selected the correct directory. This
552can be used so a user can select the installation directory of a
553previously installed application. The directory can then be validated
554against 2 known files and 2 known directories that should exist.</td>
555 </tr>
556 <tr class="tpheader">
557 <th class="manual2">Attribute</th>
558 <th class="manual2">Description</th>
559 <th class="manual2">Example</th>
560 </tr>
561 <tr>
562 <td>property</td>
563 <td>The name of the property to be set in the <code>ant.install.properties</code>
564file the value will be the absolute path to the directory.</td>
565 <td>file.property</td>
566 </tr>
567 <tr>
568 <td>displayText</td>
569 <td>The text to be shown describing the option.</td>
570 <td>Select an installation directory</td>
571 </tr>
572 <tr>
573 <td>defaultValue</td>
574 <td>The default for the directory.</td>
575 <td>/usr/local/jakarta-tomcat-4.0.1</td>
576 </tr>
577 <tr>
578 <td>defaultValueWin</td>
579 <td>The default for the directory for windows installations.</td>
580 <td>C:\Program Files\Existing Application</td>
581 </tr>
582 <tr>
583 <td>checkFile1</td>
584 <td>The relative path of a file based on the user
585selected directory. When the installer is run this file will be checked
586to see if it exists (optional).</td>
587 <td>conf/server.xml</td>
588 </tr>
589 <tr>
590 <td>checkFile2</td>
591 <td>A second file to check (optional).</td>
592 <td>conf/server.xml</td>
593 </tr>
594 <tr>
595 <td>checkDir1</td>
596 <td>The relative path of a directory based on the user
597selected directory (optional).</td>
598 <td>webapps</td>
599 </tr>
600 <tr>
601 <td>checkDir2</td>
602 <td>A second directory to check (optional).</td>
603 <td>conf</td>
604 </tr>
605 </tbody>
606 </table>
607 <br/>
608 <table class="manual" cellspacing="0">
609 <tbody>
610 <tr class="tpheader">
611 <th class="manual" colspan="3"><a name="file">&lt;file&gt;</a></th>
612 </tr>
613 <tr>
614 <td colspan="3">The file input allows the user to select
615a file</td>
616 </tr>
617 <tr class="tpheader">
618 <th class="manual2">Attribute</th>
619 <th class="manual2">Description</th>
620 <th class="manual2">Example</th>
621 </tr>
622 <tr>
623 <td>property</td>
624 <td>The name of the property to be set in the <code>ant.install.properties</code>
625file the value will be the absolute path to the file.</td>
626 <td>file.property</td>
627 </tr>
628 <tr>
629 <td>displayText</td>
630 <td>The text to be shown describing the option.</td>
631 <td>Select the weblogic configuration file</td>
632 </tr>
633 <tr>
634 <td>defaultValue</td>
635 <td>The default for the file.</td>
636 <td>/var/log</td>
637 </tr>
638 <tr>
639 <td>defaultValueWin</td>
640 <td>The default for the file when installing on windows.</td>
641 <td>C:\log</td>
642 </tr>
643 <tr>
644 <td>checkExists</td>
645 <td>If true the installation will not continue unless the
646file selected exists. The user will have to select a file that does
647exist, create the file or cancel the install. If you want to create the
648file during the install if it does not exist use Ant.</td>
649 <td>false</td>
650 </tr>
651 </tbody>
652 </table>
653 <br/>
654 <table class="manual" cellspacing="0">
655 <tbody>
656 <tr class="tpheader">
657 <th class="manual" colspan="3"><a name="select">&lt;select&gt;</a></th>
658 </tr>
659 <tr>
660 <td colspan="3">The select input allows the user to
661select from a list of options. This will be represented as a group of
662radio buttons or a numbered list on the command line. An input type of
663select should have at least two child elements called <code>&lt;option&gt;</code> with the
664attributes <code>text</code> and <code>value</code>. The text is displayed next to the option and
665the value is the value set into the property. <br/>
666N.B. the defaultValue
667should be blank or one of the values in one of the options. This is not checked by AntInstaller
668but is a requirement, there are no guarantees if you don't RTFM.</td>
669 </tr>
670 <tr class="tpheader">
671 <th class="manual2">Attribute</th>
672 <th class="manual2">Description</th>
673 <th class="manual2">Example</th>
674 </tr>
675 <tr>
676 <td>property</td>
677 <td>The name of the property to be set in the <code>ant.install.properties</code>
678file. The value will be the text of one of the option value attributes.</td>
679 <td>file.property</td>
680 </tr>
681 <tr>
682 <td>displayText</td>
683 <td>The text to be shown describing the options available.</td>
684 <td>Select your favorite colour</td>
685 </tr>
686 <tr>
687 <td>defaultValue</td>
688 <td>The default for the option this should match one of
689the options values.</td>
690 <td>#FF0000</td>
691 </tr>
692 </tbody>
693 </table>
694 <br/>
695 <table class="manual" cellspacing="0">
696 <tbody>
697 <tr class="tpheader">
698 <th class="manual" colspan="3"><a name="target-select">&lt;target-select&gt;</a></th>
699 </tr>
700 <tr>
701 <td colspan="3">The target-select input allows the user to
702select targets from a list of options. This will be represented as a group of
703radio buttons or a numbered list on the command line. This input type is almost identical to the select
704input type but the value as well as being recorded as a property is set as a target.<br/>
705An input type of target-select should have at least two child elements called <code>&lt;option&gt;</code> with the
706attributes <code>text</code> and <code>value</code>. The text is displayed next to the option and
707the value is the target to be run (and the value set into the property).
708N.B. the defaultValue
709should be blank or one of the values in one of the options. This is not checked by AntInstaller at runtime
710but is a requirement, there are no guarantees if you don't RTFM. You should use the checkConfig script to validate the config.</td>
711 </tr>
712 <tr class="tpheader">
713 <th class="manual2">Attribute</th>
714 <th class="manual2">Description</th>
715 <th class="manual2">Example</th>
716 </tr>
717 <tr>
718 <td>property</td>
719 <td>The name of the property to be set in the <code>ant.install.properties</code>
720file. The value will be the text of one of the option value attributes and will be the target that is run.</td>
721 <td>target.property</td>
722 </tr>
723 <tr>
724 <td>displayText</td>
725 <td>The text to be shown describing the options available.</td>
726 <td>Select your favorite colour</td>
727 </tr>
728 <tr>
729 <td>defaultValue</td>
730 <td>The default for the option this should match one of
731the options values.</td>
732 <td>fulldocs</td>
733 </tr>
734 </tbody>
735 </table>
736 <br/>
737 <table class="manual" cellspacing="0">
738 <tbody>
739 <tr class="tpheader">
740 <th class="manual" colspan="3"><a name="large-select">&lt;large-select&gt;</a></th>
741 </tr>
742 <tr>
743 <td colspan="3">The large select has identical options to the <code>select</code> input above.
744 Large select enables the list of options to be greater and is displayed differently.
745 In the Swing GUI the options are rendered as a drop-down list. In the text/console UI
746 the options are shown to the user 20 lines at a time.</td>
747 </tr>
748 </tbody>
749 </table>
750 <br/>
751 <table class="manual" cellspacing="0">
752 <tbody>
753 <tr class="tpheader">
754 <th class="manual" colspan="3"><a name="target">&lt;target&gt;</a></th>
755 </tr>
756 <tr>
757 <td colspan="3">The target input shows a check box, if
758the user selects the target the Ant target will be run when the
759installation starts. The order of the targets in the list is
760significant, and the targets will be run in that order. If there is
761more than one Page with target entry types or there is a page with a
762target attribute the targets will be run in the order they appear in
763the config file.</td>
764 </tr>
765 <tr class="tpheader">
766 <th class="manual2">Attribute</th>
767 <th class="manual2">Description</th>
768 <th class="manual2">Example</th>
769 </tr>
770 <tr>
771 <td>target</td>
772 <td>The name of the target to be run it must exist in the
773build.xml file delivered with the install.</td>
774 <td>installSource</td>
775 </tr>
776 <tr>
777 <td>displayText</td>
778 <td>The text to be shown describing the options available.</td>
779 <td>Do you want to install the source code.</td>
780 </tr>
781 <tr>
782 <td>defaultValue</td>
783 <td>true or false, determines if the check box is
784selected by default.</td>
785 <td>true</td>
786 </tr>
787 <tr>
788 <td>force</td>
789 <td>If true the checkbox will not be editable and will be
790set to the value in the defaultValue attribute. This can be used to indicate that installing
791this component is not optional.</td>
792 <td>false</td>
793 </tr>
794 <tr>
795 <td>osSpecific</td>
796 <td>If the osSpecific flag is set the Operating System of the current system will
797be appended to the name of the target actually run by Ant so that different
798targets can be run according to the final deployment platform.
799This feature goes against the principles of
800building cross platform installers, but is provided so that common installer
801tasks such as creating icons and shortcuts can be run using the platform specific executables.
802</td>
803 <td>false</td>
804 </tr>
805 <tr>
806 <td>strict</td>
807 <td>Currently there are two modes for OS specific targets strict and not strict (lax). <br/>
808Strict target will return the target name plus the exact String in the
809System Property "os.name" this means you will have to provide targets for
810every possible OS version. See
811<a href="http://lopica.sourceforge.net/os.html">this page</a> for a list of possible values.
812There are a great many but you may not want to consider some of the options.<br/><br/>
813Lax target will return one of the following strings only
814<ul>
815 <li>"[target-name]-linux" - Linux </li>
816 <li>"[target-name]-mac" - Mac OS and Mac OS X</li>
817 <li>"[target-name]-sun" - SunOS and Solaris</li>
818 <li>"[target-name]-win" - Windows</li>
819 <li>"[target-name]-other" - any thing else</li>
820</ul>
821so you only have to create 5 ant targets to support all the cases. It is pretty hard
822to support windows bit with this system, if anyone needs to specifically support this and does not
823want to use the existing strict mechanism, get in touch. JDK1.4 on Win16 boxes strikes me as
824an unlikely combination ;)
825 </td>
826 <td>false</td>
827 </tr>
828 </tbody>
829 </table>
830 <br/>
831 <table class="manual" cellspacing="0">
832 <tbody>
833 <tr class="tpheader">
834 <th class="manual" colspan="3"><a name="text">&lt;text&gt;</a></th>
835 </tr>
836 <tr>
837 <td colspan="3">An text input entry is a field into which
838the user can write any text (or no text).</td>
839 </tr>
840 <tr class="tpheader">
841 <th class="manual2">Attribute</th>
842 <th class="manual2">Description</th>
843 <th class="manual2">Example</th>
844 </tr>
845 <tr>
846 <td>property</td>
847 <td>The name of the property to be set in the <code>ant.install.properties</code>
848file, the value will be the text entered by the user.</td>
849 <td>name.property</td>
850 </tr>
851 <tr>
852 <td>displayText</td>
853 <td>The text to be shown describing the text to be
854entered.</td>
855 <td>Enter your name</td>
856 </tr>
857 <tr>
858 <td>defaultValue</td>
859 <td>The default value if the user enters no text or displayed as a default in the GUI.</td>
860 <td>${java.user.name}</td>
861 </tr>
862 </tbody>
863 </table>
864 <br/>
865 <table class="manual" cellspacing="0">
866 <tbody>
867 <tr class="tpheader">
868 <th class="manual" colspan="3"><a name="validated">&lt;validated&gt;</a></th>
869 </tr>
870 <tr>
871 <td colspan="3">A validated text input entry is a text
872field into which the user can write any text but the installation will
873not continue unless the text entered matches a regular expression
874provided.</td>
875 </tr>
876 <tr class="tpheader">
877 <th class="manual2">Attribute</th>
878 <th class="manual2">Description</th>
879 <th class="manual2">Example</th>
880 </tr>
881 <tr>
882 <td>property</td>
883 <td>The name of the property to be set in the <code>ant.install.properties</code>
884file, the value will be the text entered by the user.</td>
885 <td>server.url</td>
886 </tr>
887 <tr>
888 <td>displayText</td>
889 <td>The text to be shown describing the text to be
890entered.</td>
891 <td>Enter your name</td>
892 </tr>
893 <tr>
894 <td>defaultValue</td>
895 <td>The default value if the user enters no text, this
896should be valid according to the regular expression.</td>
897 <td>true</td>
898 </tr>
899 <tr>
900 <td>regex</td>
901 <td>The regular expression used to validate the text, the
902whole regex should match the text entered.</td>
903 <td>^[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9]$</td>
904 </tr>
905 </tbody>
906 </table>
907
908 <br/>
909 <table class="manual" cellspacing="0">
910 <tbody>
911 <tr class="tpheader">
912 <th class="manual" colspan="3"><a name="extvalidated">&lt;ext-validated&gt;</a></th>
913 </tr>
914 <tr>
915 <td colspan="3">An externally validated text input entry is a text
916field into which the user can write any text but the installation will
917not continue unless the text entered passes a validation function. The validation function is not part
918of AntInstaller, a fully qualified classname (that is on the classpath at runtime) is specified which AntInstaller
919executes to validate. One instance will be created per input element which should conform to the interface
920<code>org.tp23.antinstaller.input.Validator</code>. <br/>
921This feature is not tested but does provide flexibility in validating input, if you use this feature please
922report back you results (success or failures) to the AntInstaller project pages. We wish to discuss
923integrating external validation into the Localization of the installers (when it happens) with
924active users of this feature.</td>
925 </tr>
926 <tr class="tpheader">
927 <th class="manual2">Attribute</th>
928 <th class="manual2">Description</th>
929 <th class="manual2">Example</th>
930 </tr>
931 <tr>
932 <td>property</td>
933 <td>The name of the property to be set in the <code>ant.install.properties</code>
934file, the value will be the text entered by the user.</td>
935 <td>server.url</td>
936 </tr>
937 <tr>
938 <td>displayText</td>
939 <td>The text to be shown describing the text to be entered.</td>
940 <td>Choose an open network port</td>
941 </tr>
942 <tr>
943 <td>defaultValue</td>
944 <td>The default value if the user enters no text, this
945should be valid according to the external validator.</td>
946 <td>true</td>
947 </tr>
948 <tr>
949 <td>validationClass</td>
950 <td>The class used as a Validator</td>
951 <td>com.me.val.PortOpenValidator</td>
952 </tr>
953 </tbody>
954 </table>
955
956
957 <br/>
958 <table class="manual" cellspacing="0">
959 <tbody>
960 <tr class="tpheader">
961 <th class="manual" colspan="3"><a name="date">&lt;date&gt;</a></th>
962 </tr>
963 <tr>
964 <td colspan="3">A text input entry that must be a valid
965date. The dateformat string must be compatible with <code>java.text.SimpleDateformat</code>
966By default the format is english dates <code>dd/MM/yyyy</code> but can be
967changed to any valid format. If the date field is used in an installer it is not possible to enter blank dates.</td>
968 </tr>
969 <tr class="tpheader">
970 <th class="manual2">Attribute</th>
971 <th class="manual2">Description</th>
972 <th class="manual2">Example</th>
973 </tr>
974 <tr>
975 <td>property</td>
976 <td>The name of the property to be set in the <code>ant.install.properties</code>
977file, the value will be the date entered by the user.</td>
978 <td>mydate.property</td>
979 </tr>
980 <tr>
981 <td>displayText</td>
982 <td>The text to be shown describing the date to be
983entered.</td>
984 <td>Enter your name</td>
985 </tr>
986 <tr>
987 <td>defaultValue</td>
988 <td>The default value if the user enters no text, this
989should be valid according to the date format. Alternatively the String <code>TODAY</code>
990may be entered and the default value will be the time the installer is
991run.</td>
992 <td>true</td>
993 </tr>
994 <tr>
995 <td>dateFormat</td>
996 <td>The expression used to create the DateFormat.</td>
997 <td>dd-MM-yy</td>
998 </tr>
999 </tbody>
1000 </table>
1001 <br/>
1002 <table class="manual" cellspacing="0">
1003 <tbody>
1004 <tr class="tpheader">
1005 <th class="manual" colspan="3"><a name="password">&lt;password&gt;</a></th>
1006 </tr>
1007 <tr>
1008 <td colspan="3">A password text input is identical to a
1009validated text input except that the display does not echo in the Swing
1010Version (If anyone knows how to prevent the console echoing please get
1011in touch) This password field is VERY INSECURE so dont blame me. </td>
1012 </tr>
1013 <tr class="tpheader">
1014 <th class="manual2">Attribute</th>
1015 <th class="manual2">Description</th>
1016 <th class="manual2">Example</th>
1017 </tr>
1018 <tr>
1019 <td>property</td>
1020 <td>The name of the property to be sent to Ant the
1021password will not feature in <code>ant.install.properties</code> file,
1022the value will be the text entered by the user. If the installer is in
1023verbose mode the properties file will contain the property name but not
1024the value entered by the user.</td>
1025 <td>password.property</td>
1026 </tr>
1027 <tr>
1028 <td>displayText</td>
1029 <td>The text to be shown describing the password to be
1030entered.</td>
1031 <td>Enter your name</td>
1032 </tr>
1033 <tr>
1034 <td>defaultValue</td>
1035 <td>The default value if the user enters no text, this
1036should be valid according to the regular expression. This will be shown
1037as an example if the user enters an invalid password.</td>
1038 <td>pa55word</td>
1039 </tr>
1040 <tr>
1041 <td>regex</td>
1042 <td>The regular expression used to validate the text, the
1043whole regex should match the text entered.</td>
1044 <td>^[a-zA-Z_0-9]{8}$</td>
1045 </tr>
1046 <tr>
1047 <td>textMask</td>
1048 <td>When set to <code>true</code> an attempt is made to hide the password on the command line.
1049 This feature is optional and has not been tested on different platforms.
1050 It is a pure Java solution using a masking thread so there
1051 is a theoretical requirement for some CPU head room to function correctly.
1052 It does not work where \r is not supported for example the eclipse console.<br/><br/>
1053 see SUN's proposed solution
1054 <a href="http://java.sun.com/features/2002/09/pword_mask.html"
1055 >http://java.sun.com/features/2002/09/pword_mask.html</a><br/>
1056 see also, the embarrasing bug report on SUNs site
1057 <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4050435"
1058 >http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4050435</a><br/>
1059 see also, Ant's bug report
1060 <a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6687"
1061 >http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6687</a><br/>
1062 </td>
1063 <td>true</td>
1064 </tr>
1065 </tbody>
1066 </table>
1067 <br>
1068 <br>
1069To edit the file with the above properties a good XML editor is
1070recommended. A DTD exists to aid debugging this file. If you find errors in the DTD please <a href="http://sourceforge.net/tracker/?group_id=123466">report them</a>.<br>
1071 <br><a name="configbuild"></a>
1072 <h3><code>build.xml</code></h3>
1073
1074Once the <code>antinstall-config.xml</code> file is created you need
1075to create an Ant <code>build.xml</code> file with targets that match
1076the targets available in the install config. There are tools to help
1077you create these files.<br>
1078
1079 <br><a name="scripts"></a>
1080 <h3><code>install.sh</code> Start scripts</h3>
1081
1082With the two XML scripts ready you need to package the components you want
1083to install. Create a new directory and prepare the files as you would
1084for a normal Ant build. You can include the <code>install.sh</code>
1085and <code>install.cmd</code> files from the demo app to launch the
1086installer. These scripts can be launched in a GUI by double clicking on
1087them, but they will requrie editing to set you classpath and resources correctly.<br>
1088The main class (<code>org.tp23.antinstaller.runtime.ExecInstall</code>) that starts the installer takes two, and only two, parameters
1089on the command line which should be set in the start script.<br>
1090The first is the default
1091GUI mode (either swing or text). If swing is selected and there is no X environment or Windows
1092the system will default back to text mode.<br>
1093The second is the Ant basedir and typically it should be just "." the current directory.
1094This directory will be the basedir of the ant script no matter what it says in the <code>build.xml</code> file.
1095 <br>
1096The Ant runner currently passes the directory called <code>antlib</code>
1097in which
1098you can add any Ant optional jars to get them to auto load. You
1099can also load them on classpath of the install scripts.<br>
1100 <br>
1101There are other tools to create binary executables that launch Java
1102Apps, JBuilder has one built in. If you are deploying to Unix consider
1103a tar.gz for the installer package to save the user the task of
1104chmodding the executable.
1105 <br><a name="extractor"></a>
1106 <h3>Self Extracting Jars</h3>
1107 See <a href="installertask.html">Installer Ant Task</a> to script creation of SelfExtracting jars. <br/><br/>
1108 There is a mechanism to create a self extracting Jar where the entire installer,
1109 all requried Java code, and the resources to install can be packaged into a single Jar.
1110 The Jar is launched by double clicking on it (if the <code>.jar</code> extension is registered properly by Java) or by calling
1111 the command <code>java -jar [jar_name].jar</code>.<br>
1112 In windows if the extension <code>.jar</code> has been re-registered (e.g. to open with winzip) right clicking on the jar
1113 and selecting <code>Open With</code> then <code>javaw</code> will also run the installer.<br>
1114 Packaging a self extracting jar is more difficult, since all the included libraries need to be first expanded into files
1115 and then repackaged back into a single Jar. This can be achieved with Ant, and there are Maven tasks to make creating
1116 executable Jars easy if you already have a Maven build.
1117 The build file should not include any relative file references. The <code>${basedir}</code> property is required since
1118 the file is excracted a new empty temporary directory that is not know when
1119 the <code>build.xml</code> file is being written. This directory will be the value of <code>${basedir}</code>
1120 when the installer is run. There will be more instructions for this when the system is more
1121 stable. One thing to remember is that the main class changes for a self extracting Jar. <br>
1122 Here is an example <code>MANIFEST.MF</code> file.<br>
1123 <pre>
1124Manifest-Version: 1.0
1125Main-Class: org.tp23.antinstaller.selfextract.SelfExtractor
1126Look-And-Feel: org.tp23.jgoodies.plaf.plastic.PlasticXPLookAndFeel
1127 </pre>
1128 The Look And Feel is also required in the <code>MANIFEST.MF</code> file since the autoextract code shows a progress bar using Swing.
1129 The value should be the same Look And Feel used in the main Swing GUI specified in the installer element of <code>antinstall-config.xml</code>. If not, ensure the main Look And Feel fully supports updateing the UI, not LAFs
1130 all do.
1131 <br>
1132 <br>If a resource is included called <code>/resources/extract-image.png</code> it will be displayed during the
1133 extraction process. You can remove the image from the classpath if you don't like it or change it to any other
1134 png image of the same size.<br>
1135 <img src="images/extract-image-example.png" alt="example extract image"/>
1136 <br>
1137 <br>
1138 <br><a name="non-extractor"></a>
1139 <h3>Non Extracting Jars</h3>
1140 See <a href="installertask.html">Installer Ant Task</a> to script creation of NonExtracting jars. <br/><br/>
1141 As of version 0.7.2 a new feature has been added to load the installer without having to extract any files untill the
1142 Ant build is run. This has the advantage of not having to unjar AntInstaller itself or its dependencies such as Ant, Xerces
1143 and the look and feel.
1144 In order to specify that the NonExtractor should be used the Jar <code>META-INF/MANIFEST.MF</code> file should specify
1145 <code>org.tp23.antinstaller.selfextract.Nonextractor</code>. Since the NonExtractor does not need to show
1146 the progress bar for the extraction no look and feel is required in the manifest.
1147 An example <code>META-INF/MANIFEST.MF</code>
1148 <pre>
1149Manifest-Version: 1.0
1150Main-Class: org.tp23.antinstaller.selfextract.NonExtractor
1151 </pre>
1152 The NonExctractor still creates temporary space on the deployment system and still sets the <code>${basedir}</code>
1153 to this space.
1154 The <code>build.xml</code> file and the <code>antinstall-config.xml</code> are read from inside the Jar and all
1155 properties are passed directly
1156 to Ant. The properties file is still readable for debuging installers. In order to access resources inside the Jar
1157 alternative Ant tasks are required. instead of moving files they must be un-jared from the install archive. In order
1158 to identify the Jar file a new property has been added to the Ant build <code>${antinstaller.jar}</code>.
1159 The following example
1160 extracts a file called <code>myresource.zip</code> into the temporary directory (from there it could be unzipped
1161 to the deployment directory)
1162 <pre>
1163&lt;unzip src="${antinstaller.jar}" dest="${basedir}"&gt;
1164 &lt;patternset&gt;
1165 &lt;include name="myresource.zip"/&gt;
1166 &lt;/patternset&gt;
1167&lt;/unzip&gt;</pre>
1168 A more likely example is to unzip all the files in your application to the installation directory selected by the user.
1169 <pre>
1170&lt;unzip src="${antinstaller.jar}" dest="${my.installation.dir}"&gt;
1171 &lt;patternset&gt;
1172 &lt;include name="bin/*"/&gt;
1173 &lt;include name="classes/*"/&gt;
1174 &lt;include name="help/*"/&gt;
1175 &lt;include name="doc/*"/&gt;
1176 &lt;/patternset&gt;
1177&lt;/unzip&gt;</pre>
1178 Remember all the classes for AntInstaller need to be in the root of the Jar for the JVM to find them when the
1179 Jar is first loaded so it is probably best to put all the deployable resources in a subdirectory inside the Jar
1180 and move them on the target system with Ant if required. Moving files on the same filesystem is not time consuming. <br/>
1181
1182 <a name="refs"></a>
1183 <h3>Dynamic References</h3>
1184 As of version beta 0.5 in certain circumstances the default values of input fields can be based on existing properties. To reference collected input values use the Ant property syntax <code>${property.reference}</code>.
1185 References can be mixed with normal text as in Ant. <br>
1186 For example, <br>
1187<pre>
1188&lt;text
1189 property="new.property"
1190 displayText="Enter the installation directory"
1191 defaulValue="/usr/local/${project.short.name}"
1192 defaultValueWin="C:\Program Files\${project.short.name}"
1193 create="true"
1194/&gt;
1195</pre>
1196 As of version beta 0.7 the default values of input fields can be based on environment variables. To reference collected input values use the normal Ant syntax <code>${env.ENVIRONMENT_VARIABLE}</code>.<br>
1197 The prefix is always <code>env.</code> since this is not set with an Ant <code>&lt;property&gt;</code> task, it is part of the AntInstaller runtime. The results will be identical to <code>&lt;property environment="env."&gt;</code> since AntInstaller make direct calls to the Ant APIs.<br>
1198 The environment is NOT added by default to the build.xml or the installer when Ant runs, if you need the environment
1199 in the <code>build.xml</code> file call it in the usual way
1200 Also the java system properties are included prefixed by "java.". For example, <code>${java.user.name}</code> returns the user currently running the installer.
1201<br><br>
1202 Dynamic references have the following limitations<br>
1203 <br>
1204 <ul>
1205 <li>Dynamic references can only be added to <code>defaultValue</code> and <code>defaultValueWin</code> (currently)</li>
1206 <li>The properties must have been set in previous pages not in the current page (or future pages)</li>
1207 <li>Unlike Ant if the property has not been evalutated a blank string "" will be inserted instead of the reference.
1208 This means accidents like <code>/usr/local/${non.prop}</code> should not happen but will use <code>/usr/local</code>, generally neither case
1209 is desired, so as with Ant check the effects of absent properties before releasing your installer. Alternativly use a validated text field and specify a minimum length in the regular expression to ensure that blank values do not
1210 get accepted.</li>
1211 <li>Once a user has edited a field the evaluation stops.<br>
1212 For example, on the first page <code>${proj.short.name}</code> is set
1213 and on a subsequent page <code>${proj.short.name}/lib</code> and <code>${proj.short.name}/classes</code>. If the user changes one field to
1214 <code>[value of ${proj.short.name}]/myclasses</code> and then goes back and changes the first page when the subsequent pages are shown the value will <b>not</b> update to <code>[new value of ${proj.short.name}]/myclasses</code>. This only applies to the Swing GUI since in the command line the user can not go back.</li>
1215 </ul>
1216
1217 <br>
1218 <br>
1219 <a name="pagedisplay"></a>
1220 <h3>Page Displaying</h3>
1221 It is a common requirement to have a few options at the start of the installer and only show certain other pages if the user selected one of the initial options. For example, an option to install the source code, if the user is going to install the source code show a page with options to decide where to put the code, the documents and perhaps a checkbox if icons for the documents should be created. This page should not be shown to people who are not installing the source code. This feature has been available from the start but it seems some people have missed this bit of the documents. The trick is to use a <code>target</code> input and then add <code>ifTarget</code> attributes to the subsequent page elements.
1222 <br><br>
1223 As of beta0.7 it is possible to base pages on the existence of properties. Since both the System Properties from Java and the users environment variables are available as properties it is now possible to base pages on the existence of certain properties for example if CATALINA_HOME is set it is a safe bet the user already has tomcat installed. Also if ProgramFiles is present it is probably a windows system. N.B. for more a more accurate way to run tasks based on the operating system of the user the target tag has been enhanced to run osSpecific targets.
1224
1225 Later versions can also base the decision to display pages on the existence of or values in properties. see the ifProperty attribute of the <a href="#pageinput">InputPage</a> type.
1226
1227 <br><br>
1228
1229 <a href="index.html"><img class="but" src="images/ant-install-small.png"></a>
1230 <!-- content end [segment-end]-->
1231
1232 </div>
1233 </td>
1234 </tr>
1235 </tbody>
1236</table>
1237</body>
1238</html>
Note: See TracBrowser for help on using the repository browser.