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

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

initial import of LiRK3
File size: 77.3 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.css" type="text/css" rel="stylesheet">
6 <link href="css/nav.css" rel="stylesheet" type="text/css">
7 <link rel="SHORTCUT ICON" type="image/png" href="images/antinstaller-icon.png">
8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 <meta name="keywords"
10 content="Ant, installer, AntInstall, gui, console, input, parameters, properties, swing, user interface, validation, configuration">
11 <script type="text/javascript" src="js/menu.js"></script>
12 <script type="text/javascript" src="js/sstree.js"></script>
13 <script type="text/javascript" src="js/winfix.js"></script>
14</head>
15<body onload="collapseAll('contents-panel', ['ol']); "><div id="tpallcontent">
16<table cellspacing="0" width="100%">
17 <tbody>
18 <tr class="tpheader">
19 <th class="tpleft">
20 <a target="_top" href="index.html" title="home"><img src="images/ant-install-small.png" alt="AntInstaller" id="logo" width="76" height="50"/></a>
21 <script type="text/javascript">winFix();</script>
22 </th>
23 <th class="tptop" valign="bottom">
24 <img src="space.gif" height="1" width="440" alt="spacer"/><br/>
25
26 <table>
27 <tr>
28 <td valign="top">
29 <div class="tpheadertitle">AntInstaller</div>
30 <!--img src="images/ant-install-title.png" alt="AntInstaller"/-->
31 </td>
32 <td width="100%" align="right" valign="bottom" nowrap="NOWRAP">
33 <div class="tpraised">
34 <a class="tpbutton" target="_top" href="index.html">home</a>
35 <a class="tpbutton" target="_top" href="http://sourceforge.net/project/showfiles.php?group_id=123466&amp;package_id=134917">download</a>
36 <a class="tpbutton" target="_top" href="http://sf.net">sourceforge</a>
37 <a class="tpbutton" target="_top" href="manual-ant.html">antmanual</a>
38 <a class="tpbutton" target="_top" href="http://sourceforge.net/tracker/?group_id=123466&amp;atid=696615">RFEs</a>
39 <a class="tpbutton" target="_top" href="http://sourceforge.net/tracker/?group_id=123466&amp;atid=696612">Bugs</a></div>
40 </td>
41 </tr>
42 </table>
43 </th>
44 </tr>
45 <tr class="tpbody">
46 <td class="tpleft" valign="bottom">
47 <br/>
48 <div id="logoset">
49 <a target="_top" href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=123466&amp;type=2" alt="SourceForge.net Logo" border="0" height="37" width="125"></a>
50 <br/><br/>
51 <a target="_top" href="http://sourceforge.net/donate/index.php?group_id=123466">
52 <img src="http://sourceforge.net/images/project-support.jpg" alt="donate to AntInstaller"/>
53 </a>
54 </div>
55 </td>
56 <td class="tpright" valign="top">
57 <div class="tpcontent">
58 <!--[segment-content] page content start -->
59 <div align="right">
60 <a href="manual-print.html">Printable version</a><br/>
61 <a href="contents.html" target="_search">Mozilla sidebar</a>
62 </div>
63<!-- Do not edit the following line used by manual-print.jsp -->
64<h2>Manual</h2>
65
66To set up an AntInstall there are a few requirements.
67 <ul>
68 <li>The <a href="#config"><code>antinstall-config.xml</code></a> file to describe
69 the installation</li>
70 <li>The <a href="#configbuild"><code>build.xml</code></a> ant script to run, with targets
71 that should match values in <code>antinstall-config.xml</code> </li>
72 <li>The resources to run the installer e.g. ant-installer.jar
73 and ant.jar</li>
74 <li>The binarires and resources to install for your application</li>
75 <li>The installer can be delivered as a <a href="#extractor">self extracting JAR</a> which extracts all the files on the target machine prior to running the installer.</li>
76 <li>The installer can be run directly from the Jar so the resources are not extracted until Ant is run. This is the recommended way to package an installer, see <a href="#non-extractor">non extracting JAR</a>.</li>
77 <li>All config files, classes and resources should then be packaged into a jar, this can be easily achieved with a dedicated <a href="installertask.html">Ant task</a>.</li>
78 <li>If not using a self or non extracting jar, <a href="#scripts">scripts</a> to run the installer would be required e.g. <code>install.sh</code></li>
79 </ul>
80 <a name="config"></a>
81 <h3><code>antinstall-config.xml</code></h3>
82
83This part of the guide is the reference manual for the
84configuration of <code>antinstall-config.xml</code>. The config file
85is an XML file that describes the pages to display to the user,
86and the input the user must enter. <br/>
87A simple example might be a License page to show the license of the
88software, followed by a page asking the user for their name and email.
89The next page would allow the user to choose the components to install
90(binaries, source, documentation) and the progress page with an install
91button to perform the installation. <br/>
92 <br/>
93The config file must always have a root element installer with some
94requried attributes as follows. <br/>
95 <br/>
96 <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/> </pre>
97The file is then made up of <code>page</code> elements containing <code>input</code>
98elements.
99<br/>The last page of the installer must be a <a href="#pageprogress">Progress Page</a>.
100If packaging the installer with the <a href="installertask.html">Ant task</a> the <code>antinstall-config.xml</code> file can be validated.<br/>
101When setting values, similar to Ant, ${my.property} syntax can be used for default values and comments, see <a href="#refs">dynamic references</a>.<br/>
102To determin which pages are shown and which are ommitted, see <a href="#pagedisplay">Page displaying</a>.<br/><br/>
103<div class="tpnoprint">
104An example antinstall-config.xml file can be seen <a href="antinstall-config-example.html" title="Example config" >here</a>.
105
106 <br/><br/>
107 <ul>
108 <li><a href="#installer">Installer</a></li>
109 <li><a href="#page">Pages</a>
110 <ul>
111 <li><a href="#pagesplash">Splash Page</a></li>
112 <li><a href="#pagelicense">License Page</a></li>
113 <li><a href="#pageinput">Input Page</a></li>
114 <li><a href="#pageprogress">Progress Page</a></li>
115 </ul>
116 </li>
117 <li><a href="#inputtypes">Input types</a>
118 <ul>
119 <li>Text fields
120 <ul>
121 <li><a href="#comment">Comment</a></li>
122 <li><a href="#text">Unvalidated Text</a></li>
123 <li><a href="#validated">Validated Text</a></li>
124 <li><a href="#extvalidated">Externally Validated Text</a></li>
125 <li><a href="#date">Date</a></li>
126 <li><a href="#password">Password Text</a></li>
127 <li><a href="#password-confirm">Confirm Password</a></li>
128 </ul>
129 </li>
130 <li>Target fields
131 <ul>
132 <li><a href="#target">Target</a></li>
133 <li><a href="#target-select">Target Select</a></li>
134 </ul>
135 </li>
136 <li>File fields
137 <ul>
138 <li><a href="#file">File</a></li>
139 <li><a href="#directory">Directory</a></li>
140 <li><a href="#app-root">Application Root</a></li>
141 </ul>
142 </li>
143 <li>Selection fields
144 <ul>
145 <li><a href="#checkbox">Checkbox</a></li>
146 <li><a href="#select">Select</a></li>
147 <li><a href="#large-select">Large Select</a></li>
148 </ul>
149 </li>
150 </ul>
151 </li>
152 <li><a href="#hiddentypes">Hidden elements</a>
153 <ul>
154 <li><a href="#conditional">Conditional</a></li>
155 <li><a href="#hidden">Hidden</a></li>
156 </ul>
157 </li>
158 </ul>
159</div>
160 <br/>
161 <table class="manual" cellspacing="0">
162 <tbody>
163 <tr class="tpheader">
164 <th class="manual" colspan="3"><a name="installer">&lt;installer&gt;</a></th>
165 </tr>
166 <tr>
167 <td colspan="3">The <code>installer</code> element is
168the root element of the config and has the following attributes.</td>
169 </tr>
170 <tr class="tpheader">
171 <th class="manual2">Attribute</th>
172 <th class="manual2">Description</th>
173 <th class="manual2">Example</th>
174 </tr>
175 <tr>
176 <td>ui</td>
177 <td>Indicates the supported installation modes from the following four values <i>text</i>, <i>swing</i>, <i>swing-auto</i> and <i>text-auto</i>. <i>swing</i> indicates the GUI can be shown, <i>text</i> means the commandline interface can be shown. <a href="auto.html" title="-auto installs"><i>-auto</i> installs</a> are silent installs that read the properties from a file, if available, instead of running the full UI. Ensure you understand the consequences before enabling <i>-auto</i> builds. <br/>
178 This attribute should be a comma separated list of values (whitespace is stripped).</td>
179 <td>swing,text, text-auto,swing-auto</td>
180 </tr>
181 <tr>
182 <td>loadDefaults</td>
183 <td>This flag can be true, false or prompt. Indicates what AntInstaller should do
184 if it finds existing properties in a file.</td>
185 <td>false</td>
186 </tr>
187 <tr>
188 <td>verbose</td>
189 <td>Print more info the the install log file and more
190info in the <code>ant.install.properties</code> file. N.B. the properties file may not be written if the installer
191can not write to the current directory.</td>
192 <td>true</td>
193 </tr>
194 <tr>
195 <td>debug</td>
196 <td>Setting this flag prevents the temporary directory from being deleted on exit, this is useful for debugging
197 install scripts. It should normally be set to false or ommited for a final installer. </td>
198 <td>false</td>
199 </tr>
200 <tr>
201 <td>lookAndFeel</td>
202 <td>The <a href="lookandfeels.html" title="LookAndFeel">LookAndFeel</a> class for the installer or one of the following special values.
203<ul>
204 <li><code>"null"</code> - The string "null" is used to set the default LookAndFeel determined by Java (no extra classes required)</li>
205 <li><code>"jgoodies"</code> - Used to set the default LookAndFeel for AntInstaller org.tp23.jgoodies.plaf.plastic.PlasticXPLookAndFeel
206 (<code>jgoodies-edited-1_2_2.jar</code> or it contents must be on the classpath)</li>
207 <li><code>"native"</code> - Used to set the native LookAndFeel for the runtime Operating System (no extra classes required)</li>
208 <li><code>"greymetal"</code> - Used to set the cutdown MetalLookAndFeel included with AntInstaller. This is the same as MetalLookAndFeel with a grey theme and no bold fonts unless specified in the <code>antinstall-config.xml</code> file (no extra classes required)</li>
209</ul>
210If 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.
211 </td>
212 <td>
213 greymetal<br/>
214 jgoodies</td>
215 </tr>
216 <tr>
217 <td>name</td>
218 <td>The name of the installer, this will appear in the
219title of the installer GUI window.</td>
220 <td>My Installer</td>
221 </tr>
222 <tr>
223 <td>windowIcon</td>
224 <td>This is the resource name of the icon for the
225installer window. It is a string that is used to load the resource from
226the classpath so the image must be in one of the jars on the classpath
227of the install start script. In the self installer it must be in the correct directory
228of the Jar.</td>
229 <td>/resources/gkmain_inv.png</td>
230 </tr>
231 <tr>
232 <td>defaultImageResource</td>
233 <td>This is the resource image used for the top of the
234installer GUI by default, it can be overridden for individual pages.</td>
235 <td>/resources/greens.png</td>
236 </tr>
237 <tr>
238 <td>minJavaVersion</td>
239 <td>The minimum Java version for the installer, this is
240supported as of AntInstaller 0.8beta do disable this feature remove the attribute.</td>
241 <td>1.4</td>
242 </tr>
243 <tr>
244 <td>finishButtonText</td>
245 <td>The text displayed on the install button. If not specified, the default is "Install". This has been
246 added since Antinstaller can be used as a GUI for other Ant builds, in which case "Build" would
247 be more appropriate.</td>
248 <td>Install</td>
249 </tr>
250 <tr>
251 <td>antialiased</td>
252 <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 the GUI down unacceptably on older PCs, but does look better.</td>
253 <td>false</td>
254 </tr>
255 <tr>
256 <td>wide</td>
257 <td>If this attribute is set the width of the installer GUI can be configured. The format is
258 <code>[window-size]:[label-width]</code></td>
259 <td>600:275</td>
260 </tr>
261 <tr>
262 <td>version</td>
263 <td>Defines a version for the installer, this attribute is optional and defaults to "0.0". However, if you want to support <a href="auto.html">automatic installs</a> (ui includes text-auto or swing-auto) this can be used to indicate that a new installer is not compatible with previous properties files. If a new installer for an application is developed that requires new properties increment the major version and old properties files will not be loaded. Increment the minor version if the properties are compatible but additional properties have been added and must be maually entered, text-auto and swing-auto builds will be forbidden. <br/>
264 If the new version of the installer is a compatible version with the properties file found, it will load without errors. No checking is done to ensure that this is logical. When delivering upgraded installers you should ensure that old properties file versions are compatible if you do not increment the version and support automatic installs.</td>
265 <td>1.0.2</td>
266 </tr>
267 </tbody>
268 </table>
269 <br/>
270 <br/>
271 <table class="manual" cellspacing="0">
272 <tbody>
273 <tr class="tpheader">
274 <th class="manual" colspan="3"><a name="page">&lt;page&gt;</a></th>
275 </tr>
276 <tr>
277 <td colspan="3">Pages entries in the XML file represent a
278single window in the installer moved through by the user by selecting
279"Next &gt;&gt;" (or pressing enter) all pages have the following
280atributes.</td>
281 </tr>
282 <tr class="tpheader">
283 <th class="manual2">Attribute</th>
284 <th class="manual2">Description</th>
285 <th class="manual2">Example</th>
286 </tr>
287 <tr>
288 <td><b>type</b></td>
289 <td>The type of page one of four options, progress,
290license, splash or input.</td>
291 <td>input</td>
292 </tr>
293 <tr>
294 <td>name</td>
295 <td>A unique name for the page.</td>
296 <td>User properties</td>
297 </tr>
298 <tr>
299 <td>displayText</td>
300 <td>The text to be shown at the top of the page.</td>
301 <td>Install Options</td>
302 </tr>
303 <tr>
304 <td>imageResource</td>
305 <td>The image to be shown at the top of the page, overriding the defaultImageResource defined
306 in the installer element.</td>
307 <td>Install Options</td>
308 </tr>
309 <tr>
310 <td>target</td>
311 <td>An ant target that will always be run from the <code>build.xml</code>
312file. This attribute is optional see the Target input type if you wish
313to show a targets that can be selected by the user.</td>
314 <td>clean</td>
315 </tr>
316 <tr>
317 <td>overflow</td>
318 <td>Setting this to true causes the Swing GUI to allow the page to extend past the normal height and for scrollbars
319 to be shown when the page overflows.</td>
320 <td>true</td>
321 </tr>
322 </tbody>
323 </table>
324 <br/>
325 <br/>
326 <table class="manual" cellspacing="0">
327 <tbody>
328 <tr class="tpheader">
329 <th class="manual" colspan="3"><a name="pagesplash">&lt;page
330type="splash"&gt;</a></th>
331 </tr>
332 <tr>
333 <td colspan="3">Displays a graphical image page in the Swing GUI</td>
334 </tr>
335 <tr class="tpheader">
336 <th class="manual2">Attribute</th>
337 <th class="manual2">Description</th>
338 <th class="manual2">Example</th>
339 </tr>
340 <tr>
341 <td>splashResource</td>
342 <td>The image resource used for the splash image. The resource must be available on the classpath
343 at runtime.</td>
344 <td>/resources/large-logo-image.png</td>
345 </tr>
346 <tr>
347 <td>altText</td>
348 <td>Alternative text for the console mode</td>
349 <td>Welcome to the installer app</td>
350 </tr>
351 </tbody>
352 </table>
353 <br/>
354 <br/>
355 <table class="manual" cellspacing="0">
356 <tbody>
357 <tr class="tpheader">
358 <th class="manual" colspan="3"><a name="pagetext">&lt;page
359type="text"&gt;</a></th>
360 </tr>
361 <tr>
362 <td colspan="3">Displays an HTML page in swing and a text file in text mode.</td>
363 </tr>
364 <tr class="tpheader">
365 <th class="manual2">Attribute</th>
366 <th class="manual2">Description</th>
367 <th class="manual2">Example</th>
368 </tr>
369 <tr>
370 <td>htmlResource</td>
371 <td>The resource used for the html page. The resource must be available on the classpath at runtime. <br/>
372 The HTML support is that of the Swing JTextPane which is very basic. Embeded images and style sheets are refereced from the classpath. The following HTML will display an image from the classpath. <br/>
373 <code>&lt;img src="/resources/image.png"&gt;</code><br/>
374 Property values are expanded in the file if variables of the form <code>${java.user.name}</code> are found.<br/>
375 </td>
376 <td>/resources/text.html</td>
377 </tr>
378 <tr>
379 <td>textResource</td>
380 <td>Alternative text for the console mode. <br/>
381 Property values are expanded in the file if a variable of the form ${java.user.name} are found.<br/></td>
382 <td>/resources/text.text</td>
383 </tr>
384 </tbody>
385 </table>
386 <br/>
387 <br/>
388 <table class="manual" cellspacing="0">
389 <tbody>
390 <tr class="tpheader">
391 <th class="manual" colspan="3"><a name="pagelicense">&lt;page
392type="license"&gt;</a></th>
393 </tr>
394 <tr>
395 <td colspan="3">Shows a single license file in a
396scrollable window to the user.</td>
397 </tr>
398 <tr class="tpheader">
399 <th class="manual2">Attribute</th>
400 <th class="manual2">Description</th>
401 <th class="manual2">Example</th>
402 </tr>
403 <tr>
404 <td>resource</td>
405 <td>The license text file resource, must be on the
406classpath.</td>
407 <td>/resources/GPL.txt</td>
408 </tr>
409 <tr>
410 <td>usePaging</td>
411 <td>In text mode this parameter stops the scrolling of the license text at 20 lines,
412 and provides options to view the next page or skip to the end. The default is false.</td>
413 <td>true</td>
414 </tr>
415 </tbody>
416 </table>
417 <br/>
418 <br/>
419 <table class="manual" cellspacing="0">
420 <tbody>
421 <tr class="tpheader">
422 <th class="manual" colspan="3"><a name="pageinput">&lt;page
423type="input"&gt;</a>
424 </th>
425 <tr>
426 <td colspan="3">A page for adding input types listed
427below. An installer can have as many input pages as desired. </td>
428 </tr>
429 <tr class="tpheader">
430 <th class="manual2">Attribute</th>
431 <th class="manual2">Description</th>
432 <th class="manual2">Example</th>
433 </tr>
434 <tr>
435 <td>ifTarget</td>
436 <td>This page will be show if the named target has previously been selected. This can be used to
437 conditionally show installation pages when certain parts of the <code>build.xml</code> script are to be run and not
438 if they are to be omitted.</td>
439 <td>documentation</td>
440 </tr>
441 <tr>
442 <td><a name="ifproperty">ifProperty</a></td>
443 <td>This page will be shown if the property has the correct value. This can be used to
444 conditionally show installation pages when certain properties match
445 The format of the property can be as simple as <code>${name}=value</code> or can combine tests on multiple properties such as <code>(${name}!=value) AND (${name2}^=value2)</code>. There must be no spaces
446 and both the property and value are case sensitive. It is a good idea to use a <code>select</code> input type
447 for the value since free text entered by the user is unlikely to match exactly in case and whitespace or use validated
448 text fields.
449N.B. to run tasks based on properties consider the <a href="http://ant-contrib.sourceforge.net">ant-contrib</a> packages. <br/>
450 The new syntax allows for environment variable checks such as <code>${env.DISPLAY}=:0.0</code>
451 <br/><br/>
452 <b>N.B. the old syntax <code>name=value</code> does not work any more.</b> It is <b>not</b> possible to
453 place an = sign in a property name.<br/>
454 e.g. <code>${prop.col=back}=#0000FF</code> will break the simple parser.
455 <br/><br/>
456 The following operators are supported:
457 <ul>
458 <li> = equals. not assignment as in Java</li>
459 <li> == equals same as above for those that wish to be specific</li>
460 <li> != not equals or null</li>
461 <li> $= ends with, the $ is used from regex for end of line</li>
462 <li> ^= starts with, again ^from regular expressions</li>
463 <li> += greater than, only for numbers</li>
464 <li> -= less than, only for numbers. The installer should validate to ensure the property is a valid number
465 or exceptions will be thrown. The rather strange -= and += syntax is used because &gt; and &lt;
466 must be escaped to &amp;gt; and &amp;lt; in XML attributes and the legibility
467 of the configuration files would be impared.</li>
468 <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
469 in the config file it <b>is</b> possible for the user to set the value to null by erasing the text in
470 a text entry type</li>
471 <li> ==null is null or empty</li>
472 </ul>
473 <br/><br/>
474 The following logical operators are supported when combining property tests:
475 <ul>
476 <li>AND</li>
477 <li>OR</li>
478 </ul>
479 If logical operators are being used, each simple test must be enclosed in parentheses.<br/>
480 It is probably a bad idea to use any character that is not a letter or number in a property name
481 because these operators may be extended in the future
482 </td>
483 <td>${myProperty}=value23<br/>
484 (${myFirstProperty}=6) OR (${mySecondProperty}+=12)
485 </td>
486 </tr>
487 <tr>
488 <td>postDisplayTarget</td>
489 <td>Post display targets are special Ant targets run after the page has been displayed. Certain rules apply see <a href="posttargets.html" title="post display targets">post display targets</a></td>
490 <td>antinstaller-pagename</td>
491 </tr>
492
493 </tbody>
494 </table>
495 <br/>
496 <br/>
497 <table class="manual" cellspacing="0">
498 <tbody>
499 <tr class="tpheader">
500 <th class="manual" colspan="3"><a name="pageprogress">&lt;page
501type="progress"&gt;</a></th>
502 </tr>
503 <tr>
504 <td colspan="3">A page for showing the user the progress
505of the installation. This page contains the "Install" Button, so all
506installers should end with a progress page. Currently it is not checked
507that an installer ends with a progress page so the creator of the <code>antinstall-config.xml</code>
508should ensure it does.</td>
509 </tr>
510 <tr>
511 <td>showTargets</td>
512 <td>When this flag is true, in the Swing GUI, a graphical representation of
513 the targets being run and the dependent targets found is displayed.</td>
514 <td>true</td>
515 </tr>
516 </tbody>
517 </table>
518<br/><a name="inputtypes"></a><h3>Input Types</h3>
519Input types represent fields in which users can input values or make selections. <br/>
520The input type element is
521also used to display text to the user. While there is no limit to the number of comments or text you can add in the
522config file, the GUI only has a limited amount of space. Check your config with your choosen Look And Feel to ensure
523that instructions are not cropped.<br/>
524All input types accept the <code>explanatoryText</code> attribute, where multi-line comments can be added.
525The GUI has a fixed width available for the <code>displayText</code> attribute which often does not provide much space.
526Single line comments can be added with the <code>comment</code> type.<br/>
527If anyone has a serious requirement to include more text that is currently possible post an RFE and I will look into
528tool tip popups or a scrollable text box or perhaps instructions that can launch in a help window. This has not been added yet
529since it is much more difficult to implement in the command line UI, and as yet we have no requirement.
530<br/><br/>
531 <table class="manual" cellspacing="0">
532 <tbody>
533 <tr class="tpheader">
534 <th class="manual" colspan="3"><a name="checkbox">&lt;checkbox&gt;</a></th>
535 </tr>
536 <tr>
537 <td colspan="3">The check box input is used for boolean
538input, a check box in the gui and a true false option on the command
539line.</td>
540 </tr>
541 <tr class="tpheader">
542 <th class="manual2">Attribute</th>
543 <th class="manual2">Description</th>
544 <th class="manual2">Example</th>
545 </tr>
546 <tr>
547 <td>property</td>
548 <td>The name of the property to be set in the <code>ant.install.properties</code>
549file the value will be true or false.</td>
550 <td>my.property</td>
551 </tr>
552 <tr>
553 <td>displayText</td>
554 <td>The text to be shown describing the option.</td>
555 <td>Enable all security options</td>
556 </tr>
557 <tr>
558 <td>defaultValue</td>
559 <td>The default for the check box.</td>
560 <td>true</td>
561 </tr>
562 <tr>
563 <td>force</td>
564 <td>Force the option selected to be the default value.
565This can be used to indicate that the option is required. For example,
566an installer could be delivered where "Enable all security options" is
567always selected.</td>
568 <td>false</td>
569 </tr>
570 </tbody>
571 </table>
572 <br/>
573 <table class="manual" cellspacing="0">
574 <tbody>
575 <tr class="tpheader">
576 <th class="manual" colspan="3"><a name="comment">&lt;comment&gt;</a></th>
577 </tr>
578 <tr>
579 <td colspan="3">The comment input displays text to the
580user and does not accept any type of input.</td>
581 </tr>
582 <tr class="tpheader">
583 <th class="manual2">Attribute</th>
584 <th class="manual2">Description</th>
585 <th class="manual2">Example</th>
586 </tr>
587 <tr>
588 <td>displayText</td>
589 <td>The text to be shown describing the option.</td>
590 <td>W</td>
591 </tr>
592 <tr>
593 <td>bold</td>
594 <td>Display the comment in bold, in the GUI version.</td>
595 <td>true</td>
596 </tr>
597 <tr>
598 <td>title</td>
599 <td>Display the comment in a larger font in the GUI or in
600capitals in the command line.</td>
601 <td>false</td>
602 </tr>
603 </tbody>
604 </table>
605 <br/>
606 <table class="manual" cellspacing="0">
607 <tbody>
608 <tr class="tpheader">
609 <th class="manual" colspan="3"><a name="directory">&lt;directory&gt;</a></th>
610 </tr>
611 <tr>
612 <td colspan="3">The directory input allows the user to
613select a directory.</td>
614 </tr>
615 <tr class="tpheader">
616 <th class="manual2">Attribute</th>
617 <th class="manual2">Description</th>
618 <th class="manual2">Example</th>
619 </tr>
620 <tr>
621 <td>property</td>
622 <td>The name of the property to be set in the <code>ant.install.properties</code>
623file the value will be the absolute path to the directory.</td>
624 <td>file.property</td>
625 </tr>
626 <tr>
627 <td>displayText</td>
628 <td>The text to be shown describing the option.</td>
629 <td>Select an installation directory</td>
630 </tr>
631 <tr>
632 <td>defaultValue</td>
633 <td>The default for the directory. Empty defaultValue is accepted as of version beta0.8 provided that create and checkExists are false.</td>
634 <td>/var/log</td>
635 </tr>
636 <tr>
637 <td>defaultValueWin</td>
638 <td>The default for the directory for windows installations.</td>
639 <td>C:\Program Files\myapp</td>
640 </tr>
641 <tr>
642 <td>create</td>
643 <td>If this is true and the directory entered does not
644exist the user will be asked if the directory should be created.</td>
645 <td>true</td>
646 </tr>
647 <tr>
648 <td>checkExists</td>
649 <td>If true the installation will not continue unless the
650directory selected exists. The user will have to select a directory
651that does exist, create it or cancel the install. If create is true and
652the directory does not exist the user simply has to agree to have the
653directory created.</td>
654 <td>false</td>
655 </tr>
656 </tbody>
657 </table>
658 <br/>
659 <table class="manual" cellspacing="0">
660 <tbody>
661 <tr class="tpheader">
662 <th class="manual" colspan="3"><a name="app-root">&lt;app-root&gt;</a></th>
663 </tr>
664 <tr>
665 <td colspan="3">The directory input allows the user to
666select a directory. The existence of files is then checked during
667validation to ensure the user has selected the correct directory. This
668can be used so a user can select the installation directory of a
669previously installed application. The directory can then be validated
670against 2 known files and 2 known directories that should exist.</td>
671 </tr>
672 <tr class="tpheader">
673 <th class="manual2">Attribute</th>
674 <th class="manual2">Description</th>
675 <th class="manual2">Example</th>
676 </tr>
677 <tr>
678 <td>property</td>
679 <td>The name of the property to be set in the <code>ant.install.properties</code>
680file the value will be the absolute path to the directory.</td>
681 <td>file.property</td>
682 </tr>
683 <tr>
684 <td>displayText</td>
685 <td>The text to be shown describing the option.</td>
686 <td>Select an installation directory</td>
687 </tr>
688 <tr>
689 <td>defaultValue</td>
690 <td>The default for the directory.</td>
691 <td>/usr/local/jakarta-tomcat-4.0.1</td>
692 </tr>
693 <tr>
694 <td>defaultValueWin</td>
695 <td>The default for the directory for windows installations.</td>
696 <td>C:\Program Files\Existing Application</td>
697 </tr>
698 <tr>
699 <td>checkFile1</td>
700 <td>The relative path of a file based on the user
701selected directory. When the installer is run this file will be checked
702to see if it exists (optional).</td>
703 <td>conf/server.xml</td>
704 </tr>
705 <tr>
706 <td>checkFile2</td>
707 <td>A second file to check (optional).</td>
708 <td>conf/server.xml</td>
709 </tr>
710 <tr>
711 <td>checkDir1</td>
712 <td>The relative path of a directory based on the user
713selected directory (optional).</td>
714 <td>webapps</td>
715 </tr>
716 <tr>
717 <td>checkDir2</td>
718 <td>A second directory to check (optional).</td>
719 <td>conf</td>
720 </tr>
721 </tbody>
722 </table>
723 <br/>
724 <table class="manual" cellspacing="0">
725 <tbody>
726 <tr class="tpheader">
727 <th class="manual" colspan="3"><a name="file">&lt;file&gt;</a></th>
728 </tr>
729 <tr>
730 <td colspan="3">The file input allows the user to select
731a file</td>
732 </tr>
733 <tr class="tpheader">
734 <th class="manual2">Attribute</th>
735 <th class="manual2">Description</th>
736 <th class="manual2">Example</th>
737 </tr>
738 <tr>
739 <td>property</td>
740 <td>The name of the property to be set in the <code>ant.install.properties</code>
741file the value will be the absolute path to the file.</td>
742 <td>file.property</td>
743 </tr>
744 <tr>
745 <td>displayText</td>
746 <td>The text to be shown describing the option.</td>
747 <td>Select the weblogic configuration file</td>
748 </tr>
749 <tr>
750 <td>defaultValue</td>
751 <td>The default for the file.</td>
752 <td>/var/log</td>
753 </tr>
754 <tr>
755 <td>defaultValueWin</td>
756 <td>The default for the file when installing on windows.</td>
757 <td>C:\log</td>
758 </tr>
759 <tr>
760 <td>checkExists</td>
761 <td>If true the installation will not continue unless the
762file selected exists. The user will have to select a file that does
763exist, create the file or cancel the install. If you want to create the
764file during the install if it does not exist use Ant.</td>
765 <td>false</td>
766 </tr>
767 </tbody>
768 </table>
769 <br/>
770 <table class="manual" cellspacing="0">
771 <tbody>
772 <tr class="tpheader">
773 <th class="manual" colspan="3"><a name="select">&lt;select&gt;</a></th>
774 </tr>
775 <tr>
776 <td colspan="3">The select input allows the user to
777select from a list of options. This will be represented as a group of
778radio buttons or a numbered list on the command line. An input type of
779select should have at least two child elements called <code>&lt;option&gt;</code> with the
780attributes <code>text</code> and <code>value</code>. The text is displayed next to the option and
781the value is the value set into the property. <br/>
782N.B. the defaultValue
783should be blank or one of the values in one of the options. This is not checked by AntInstaller
784but is a requirement, there are no guarantees if you don't RTFM.</td>
785 </tr>
786 <tr class="tpheader">
787 <th class="manual2">Attribute</th>
788 <th class="manual2">Description</th>
789 <th class="manual2">Example</th>
790 </tr>
791 <tr>
792 <td>property</td>
793 <td>The name of the property to be set in the <code>ant.install.properties</code>
794file. The value will be the text of one of the option value attributes.</td>
795 <td>file.property</td>
796 </tr>
797 <tr>
798 <td>displayText</td>
799 <td>The text to be shown describing the options available.</td>
800 <td>Select your favorite colour</td>
801 </tr>
802 <tr>
803 <td>defaultValue</td>
804 <td>The default for the option this should match one of
805the options values.</td>
806 <td>#FF0000</td>
807 </tr>
808 </tbody>
809 </table>
810 <br/>
811 <table class="manual" cellspacing="0">
812 <tbody>
813 <tr class="tpheader">
814 <th class="manual" colspan="3"><a name="target-select">&lt;target-select&gt;</a></th>
815 </tr>
816 <tr>
817 <td colspan="3">The target-select input allows the user to
818select targets from a list of options. This will be represented as a group of
819radio buttons or a numbered list on the command line. This input type is almost identical to the select
820input type but the value as well as being recorded as a property is set as a target.<br/>
821An input type of target-select should have at least two child elements called <code>&lt;option&gt;</code> with the
822attributes <code>text</code> and <code>value</code>. The text is displayed next to the option and
823the value is the target to be run (and the value set into the property).
824N.B. the defaultValue
825should be blank or one of the values in one of the options. This is not checked by AntInstaller at runtime
826but is a requirement, there are no guarantees if you don't RTFM. You should use the checkConfig script to validate the config.</td>
827 </tr>
828 <tr class="tpheader">
829 <th class="manual2">Attribute</th>
830 <th class="manual2">Description</th>
831 <th class="manual2">Example</th>
832 </tr>
833 <tr>
834 <td>property</td>
835 <td>The name of the property to be set in the <code>ant.install.properties</code>
836file. The value will be the text of one of the option value attributes and will be the target that is run.</td>
837 <td>target.property</td>
838 </tr>
839 <tr>
840 <td>displayText</td>
841 <td>The text to be shown describing the options available.</td>
842 <td>Select your favorite colour</td>
843 </tr>
844 <tr>
845 <td>defaultValue</td>
846 <td>The default for the option this should match one of
847the options values.</td>
848 <td>fulldocs</td>
849 </tr>
850 </tbody>
851 </table>
852 <br/>
853 <table class="manual" cellspacing="0">
854 <tbody>
855 <tr class="tpheader">
856 <th class="manual" colspan="3"><a name="large-select">&lt;large-select&gt;</a></th>
857 </tr>
858 <tr>
859 <td colspan="3">The large select has identical options to the <code>select</code> input above.
860 Large select enables the list of options to be greater and is displayed differently.
861 In the Swing GUI the options are rendered as a drop-down list. In the text/console UI
862 the options are shown to the user 20 lines at a time.</td>
863 </tr>
864 </tbody>
865 </table>
866 <br/>
867 <table class="manual" cellspacing="0">
868 <tbody>
869 <tr class="tpheader">
870 <th class="manual" colspan="3"><a name="target">&lt;target&gt;</a></th>
871 </tr>
872 <tr>
873 <td colspan="3">The target input shows a check box, if
874the user selects the target the Ant target will be run when the
875installation starts. The order of the targets in the list is
876significant, and the targets will be run in that order. If there is
877more than one Page with target entry types or there is a page with a
878target attribute the targets will be run in the order they appear in
879the config file.</td>
880 </tr>
881 <tr class="tpheader">
882 <th class="manual2">Attribute</th>
883 <th class="manual2">Description</th>
884 <th class="manual2">Example</th>
885 </tr>
886 <tr>
887 <td>target</td>
888 <td>The name of the target to be run it must exist in the
889build.xml file delivered with the install.</td>
890 <td>installSource</td>
891 </tr>
892 <tr>
893 <td>displayText</td>
894 <td>The text to be shown describing the options available.</td>
895 <td>Do you want to install the source code.</td>
896 </tr>
897 <tr>
898 <td>defaultValue</td>
899 <td>true or false, determines if the check box is
900selected by default.</td>
901 <td>true</td>
902 </tr>
903 <tr>
904 <td>force</td>
905 <td>If true the checkbox will not be editable and will be
906set to the value in the defaultValue attribute. This can be used to indicate that installing
907this component is not optional.</td>
908 <td>false</td>
909 </tr>
910 <tr>
911 <td>osSpecific</td>
912 <td>If the osSpecific flag is set the Operating System of the current system will
913be appended to the name of the target actually run by Ant so that different
914targets can be run according to the final deployment platform.
915This feature goes against the principles of
916building cross platform installers, but is provided so that common installer
917tasks such as creating icons and shortcuts can be run using the platform specific executables.
918</td>
919 <td>false</td>
920 </tr>
921 <tr>
922 <td>strict</td>
923 <td>Currently there are two modes for OS specific targets strict and not strict (lax). <br/>
924Strict target will return the target name plus the exact String in the
925System Property "os.name" this means you will have to provide targets for
926every possible OS version. See
927<a href="http://lopica.sourceforge.net/os.html">this page</a> for a list of possible values.
928There are a great many but you may not want to consider some of the options.<br/><br/>
929Lax target will return one of the following strings only
930<ul>
931 <li>"[target-name]-linux" - Linux </li>
932 <li>"[target-name]-mac" - Mac OS and Mac OS X</li>
933 <li>"[target-name]-sun" - SunOS and Solaris</li>
934 <li>"[target-name]-win" - Windows</li>
935 <li>"[target-name]-other" - any thing else</li>
936</ul>
937so you only have to create 5 ant targets to support all the cases. It is pretty hard
938to support windows bit with this system, if anyone needs to specifically support this and does not
939want to use the existing strict mechanism, get in touch. JDK1.4 on Win16 boxes strikes me as
940an unlikely combination ;)
941 </td>
942 <td>false</td>
943 </tr>
944 </tbody>
945 </table>
946 <br/>
947 <table class="manual" cellspacing="0">
948 <tbody>
949 <tr class="tpheader">
950 <th class="manual" colspan="3"><a name="text">&lt;text&gt;</a></th>
951 </tr>
952 <tr>
953 <td colspan="3">An text input entry is a field into which
954the user can write any text (or no text).</td>
955 </tr>
956 <tr class="tpheader">
957 <th class="manual2">Attribute</th>
958 <th class="manual2">Description</th>
959 <th class="manual2">Example</th>
960 </tr>
961 <tr>
962 <td>property</td>
963 <td>The name of the property to be set in the <code>ant.install.properties</code>
964file, the value will be the text entered by the user.</td>
965 <td>name.property</td>
966 </tr>
967 <tr>
968 <td>displayText</td>
969 <td>The text to be shown describing the text to be
970entered.</td>
971 <td>Enter your name</td>
972 </tr>
973 <tr>
974 <td>defaultValue</td>
975 <td>The default value if the user enters no text or displayed as a default in the GUI.</td>
976 <td>${java.user.name}</td>
977 </tr>
978 </tbody>
979 </table>
980 <br/>
981 <table class="manual" cellspacing="0">
982 <tbody>
983 <tr class="tpheader">
984 <th class="manual" colspan="3"><a name="validated">&lt;validated&gt;</a></th>
985 </tr>
986 <tr>
987 <td colspan="3">A validated text input entry is a text
988field into which the user can write any text but the installation will
989not continue unless the text entered matches a regular expression
990provided.</td>
991 </tr>
992 <tr class="tpheader">
993 <th class="manual2">Attribute</th>
994 <th class="manual2">Description</th>
995 <th class="manual2">Example</th>
996 </tr>
997 <tr>
998 <td>property</td>
999 <td>The name of the property to be set in the <code>ant.install.properties</code>
1000file, the value will be the text entered by the user.</td>
1001 <td>server.url</td>
1002 </tr>
1003 <tr>
1004 <td>displayText</td>
1005 <td>The text to be shown describing the text to be
1006entered.</td>
1007 <td>Enter your name</td>
1008 </tr>
1009 <tr>
1010 <td>defaultValue</td>
1011 <td>The default value if the user enters no text, this
1012should be valid according to the regular expression.</td>
1013 <td>true</td>
1014 </tr>
1015 <tr>
1016 <td>regex</td>
1017 <td>The regular expression used to validate the text, the
1018whole regex should match the text entered.</td>
1019 <td>^[0-9][0-9]-[0-9][0-9]-[0-9][0-9][0-9][0-9]$</td>
1020 </tr>
1021 </tbody>
1022 </table>
1023
1024 <br/>
1025 <table class="manual" cellspacing="0">
1026 <tbody>
1027 <tr class="tpheader">
1028 <th class="manual" colspan="3"><a name="extvalidated">&lt;ext-validated&gt;</a></th>
1029 </tr>
1030 <tr>
1031 <td colspan="3">An externally validated text input entry is a text
1032field into which the user can write any text but the installation will
1033not continue unless the text entered passes a validation function. The validation function is not part
1034of AntInstaller, a fully qualified classname (that is on the classpath at runtime) is specified which AntInstaller
1035executes to validate. One instance will be created per input element which should conform to the interface
1036<code>org.tp23.antinstaller.input.Validator</code>. <br/>
1037This feature is not tested but does provide flexibility in validating input, if you use this feature please
1038report back you results (success or failures) to the AntInstaller project pages. We wish to discuss
1039integrating external validation into the Localization of the installers (when it happens) with
1040active users of this feature.</td>
1041 </tr>
1042 <tr class="tpheader">
1043 <th class="manual2">Attribute</th>
1044 <th class="manual2">Description</th>
1045 <th class="manual2">Example</th>
1046 </tr>
1047 <tr>
1048 <td>property</td>
1049 <td>The name of the property to be set in the <code>ant.install.properties</code>
1050file, the value will be the text entered by the user.</td>
1051 <td>server.url</td>
1052 </tr>
1053 <tr>
1054 <td>displayText</td>
1055 <td>The text to be shown describing the text to be entered.</td>
1056 <td>Choose an open network port</td>
1057 </tr>
1058 <tr>
1059 <td>defaultValue</td>
1060 <td>The default value if the user enters no text, this
1061should be valid according to the external validator.</td>
1062 <td>true</td>
1063 </tr>
1064 <tr>
1065 <td>validationClass</td>
1066 <td>The class used as a Validator</td>
1067 <td>com.me.val.PortOpenValidator</td>
1068 </tr>
1069 </tbody>
1070 </table>
1071
1072
1073 <br/>
1074 <table class="manual" cellspacing="0">
1075 <tbody>
1076 <tr class="tpheader">
1077 <th class="manual" colspan="3"><a name="date">&lt;date&gt;</a></th>
1078 </tr>
1079 <tr>
1080 <td colspan="3">A text input entry that must be a valid
1081date. The dateformat string must be compatible with <code>java.text.SimpleDateformat</code>
1082By default the format is english dates <code>dd/MM/yyyy</code> but can be
1083changed to any valid format. If the date field is used in an installer it is not possible to enter blank dates.</td>
1084 </tr>
1085 <tr class="tpheader">
1086 <th class="manual2">Attribute</th>
1087 <th class="manual2">Description</th>
1088 <th class="manual2">Example</th>
1089 </tr>
1090 <tr>
1091 <td>property</td>
1092 <td>The name of the property to be set in the <code>ant.install.properties</code>
1093file, the value will be the date entered by the user.</td>
1094 <td>mydate.property</td>
1095 </tr>
1096 <tr>
1097 <td>displayText</td>
1098 <td>The text to be shown describing the date to be
1099entered.</td>
1100 <td>Enter your name</td>
1101 </tr>
1102 <tr>
1103 <td>defaultValue</td>
1104 <td>The default value if the user enters no text, this
1105should be valid according to the date format. Alternatively the String <code>TODAY</code>
1106may be entered and the default value will be the time the installer is
1107run.</td>
1108 <td>true</td>
1109 </tr>
1110 <tr>
1111 <td>dateFormat</td>
1112 <td>The expression used to create the DateFormat.</td>
1113 <td>dd-MM-yy</td>
1114 </tr>
1115 </tbody>
1116 </table>
1117 <br/>
1118 <table class="manual" cellspacing="0">
1119 <tbody>
1120 <tr class="tpheader">
1121 <th class="manual" colspan="3"><a name="password">&lt;password&gt;</a></th>
1122 </tr>
1123 <tr>
1124 <td colspan="3">A password text input is identical to a
1125validated text input except that the display does not echo in the Swing
1126Version (If anyone knows how to prevent the console echoing please get
1127in touch) This password field is VERY INSECURE so dont blame me. </td>
1128 </tr>
1129 <tr class="tpheader">
1130 <th class="manual2">Attribute</th>
1131 <th class="manual2">Description</th>
1132 <th class="manual2">Example</th>
1133 </tr>
1134 <tr>
1135 <td>property</td>
1136 <td>The name of the property to be sent to Ant the
1137password will not feature in <code>ant.install.properties</code> file,
1138the value will be the text entered by the user. If the installer is in
1139verbose mode the properties file will contain the property name but not
1140the value entered by the user.</td>
1141 <td>password.property</td>
1142 </tr>
1143 <tr>
1144 <td>displayText</td>
1145 <td>The text to be shown describing the password to be
1146entered.</td>
1147 <td>Enter password</td>
1148 </tr>
1149 <tr>
1150 <td>defaultValue</td>
1151 <td>The default value if the user enters no text, this
1152should be valid according to the regular expression. This will be shown
1153as an example if the user enters an invalid password.</td>
1154 <td>pa55word</td>
1155 </tr>
1156 <tr>
1157 <td>regex</td>
1158 <td>The regular expression used to validate the text, the
1159whole regex should match the text entered.</td>
1160 <td>^[a-zA-Z_0-9]{8}$</td>
1161 </tr>
1162 <tr>
1163 <td>textMask</td>
1164 <td>When set to <code>true</code> an attempt is made to hide the password on the command line.
1165 This feature is optional and has not been tested on different platforms.
1166 It is a pure Java solution using a masking thread so there
1167 is a theoretical requirement for some CPU head room to function correctly.
1168 It does not work where \r is not supported for example the eclipse console.<br/><br/>
1169 see SUN's proposed solution
1170 <a href="http://java.sun.com/features/2002/09/pword_mask.html"
1171 >http://java.sun.com/features/2002/09/pword_mask.html</a><br/>
1172 see also, the embarrasing bug report on SUNs site
1173 <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4050435"
1174 >http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4050435</a><br/>
1175 see also, Ant's bug report
1176 <a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6687"
1177 >http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6687</a><br/>
1178 </td>
1179 <td>true</td>
1180 </tr>
1181 </tbody>
1182 </table>
1183
1184 <br/>
1185 <table class="manual" cellspacing="0">
1186 <tbody>
1187 <tr class="tpheader">
1188 <th class="manual" colspan="3"><a name="password-confirm">&lt;password-confirm&gt;</a></th>
1189 </tr>
1190 <tr>
1191 <td colspan="3">A confirm password input is identical to a
1192password input except that to validate correctly a password field on the same page
1193with the property name specified in the origField attribute.</td>
1194 </tr>
1195 <tr class="tpheader">
1196 <th class="manual2">Attribute</th>
1197 <th class="manual2">Description</th>
1198 <th class="manual2">Example</th>
1199 </tr>
1200 <tr>
1201 <td>origField</td>
1202 <td>There must be a password field with its property set to this value on the same page.
1203</td>
1204 <td>password.property</td>
1205 </tr>
1206 <tr>
1207 <td>displayText</td>
1208 <td>The text to be shown describing the password to be
1209entered.</td>
1210 <td>Confirm password</td>
1211 </tr>
1212 <tr>
1213 <td>defaultValue</td>
1214 <td>The default value if the user enters no text, this
1215should be valid according to the regular expression. This will be shown
1216as an example if the user enters an invalid password.</td>
1217 <td>pa55word</td>
1218 </tr>
1219 <tr>
1220 <td>regex</td>
1221 <td>The regular expression used to validate the text, the
1222whole regex should match the text entered.</td>
1223 <td>^[a-zA-Z_0-9]{8}$</td>
1224 </tr>
1225 <tr>
1226 <td>textMask</td>
1227 <td>When set to <code>true</code> an attempt is made to hide the password on the command line.
1228 This feature is optional and has not been tested on different platforms.
1229 It is a pure Java solution using a masking thread so there
1230 is a theoretical requirement for some CPU head room to function correctly.
1231 It does not work where \r is not supported for example the eclipse console.<br/><br/>
1232 see SUN's proposed solution
1233 <a href="http://java.sun.com/features/2002/09/pword_mask.html"
1234 >http://java.sun.com/features/2002/09/pword_mask.html</a><br/>
1235 see also, the embarrasing bug report on SUNs site
1236 <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4050435"
1237 >http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4050435</a><br/>
1238 see also, Ant's bug report
1239 <a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6687"
1240 >http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6687</a><br/>
1241 </td>
1242 <td>true</td>
1243 </tr>
1244 </tbody>
1245 </table>
1246 <br/><br/>
1247 <a name="hiddentypes"></a><h3>Hidden Elements</h3>
1248 Hidden elements are those elements of pages which are not displayed to the user,
1249 but which can be used to set properties and apply conditional logic.<br/>
1250 <br/>
1251 <table class="manual" cellspacing="0">
1252 <tbody>
1253 <tr class="tpheader">
1254 <th class="manual" colspan="3"><a name="conditional">&lt;conditional&gt;</a></th>
1255 </tr>
1256 <tr>
1257 <td colspan="3">The conditional element allows the conditional execution of a nested element.
1258 Currently, only &lt;hidden&gt; elements may be nested within a conditional block.
1259 This can be useful for initialising properties or default values based on other user selections</td>
1260 </tr>
1261 <tr class="tpheader">
1262 <th class="manual2">Attribute</th>
1263 <th class="manual2">Description</th>
1264 <th class="manual2">Example</th>
1265 </tr>
1266 <tr>
1267 <td>ifProperty</td>
1268 <td>The nested <code>hidden</code> element(s) will be evaluated if the property has the correct value.
1269 This can be used to
1270 conditionally set properties when certain other properties match specific values.
1271 The format of the property can be as simple as <code>${name}=value</code> or can combine tests on multiple properties such as <code>(${name}!=value) AND (${name2}^=value2)</code>. There must be no spaces
1272 and both the property and value are case sensitive. See the <a href="#ifproperty">ifProperty description</a>
1273 for details of the comarisons supported.</td>
1274 <td>(${prop1}=1) OR (${prop2}=${prop3})</td>
1275 </tr>
1276 </table>
1277 <br/>
1278 <table class="manual" cellspacing="0">
1279 <tbody>
1280 <tr class="tpheader">
1281 <th class="manual" colspan="3"><a name="hidden">&lt;hidden&gt;</a></th>
1282 </tr>
1283 <tr>
1284 <td colspan="3">The hidden element allows a property to be set by virtue of the page being displayed or,
1285 when nested within a <code>conditional</code> block, if the condition is true.
1286 This can be useful for initialising properties or default values based on other user selections.</td>
1287 </tr>
1288 <tr class="tpheader">
1289 <th class="manual2">Attribute</th>
1290 <th class="manual2">Description</th>
1291 <th class="manual2">Example</th>
1292 </tr>
1293 <tr>
1294 <td>property</td>
1295 <td>The name of the property to be set in the <code>ant.install.properties</code></td>
1296 <td>my.property</td>
1297 </tr>
1298 <tr>
1299 <td>value</td>
1300 <td>The value to which the property will be set</td>
1301 <td>myvalue</td>
1302 </tr>
1303 </table>
1304 <br/>
1305To edit the <code>antinstall-config.xml</code> file with the above properties a good XML editor is
1306recommended. A DTD exists to aid debugging this file. Add the following doctype to enable validation
1307<code>
1308&lt;!DOCTYPE installer PUBLIC "-//tp23 //DTD Ant Installer Config//EN" "http://antinstaller.sf.net/dtd/antinstall-config-0.8.dtd"&gt;
1309</code>
1310If you find errors in the DTD please <a href="http://sourceforge.net/tracker/?group_id=123466">report them</a>.<br/>
1311 <br/><a name="configbuild"></a>
1312 <h3><code>build.xml</code></h3>
1313
1314Once the <code>antinstall-config.xml</code> file is created you need
1315to create an Ant <code>build.xml</code> file with targets that match
1316the targets available in the install config. The <code>build.xml</code> file is out of scope of this document. The Ant documentation is avaliable at the following URL. <br/>
1317<a href="http://antinstaller.sourceforge.net/manual/manual/index.html" title="Ant manual">http://antinstaller.sourceforge.net/manual/manual/index.html</a><br/>
1318There are many tools to help you create these files, for example, eclipse has built in support.<br/><br/>
1319
1320There are some recomendations for the <code>build.xml</code> file to be used inside an installer.
1321<ul>
1322 <li>It is not recommended to use <code>depends</code> attributes for targets, although they do work in most situations. The progress page graphic sometimes produces confusing results, for this reason it can be disabled. <code>depends</code> targets may be called more often than expected since all targets specified in the <code>antinstall-config.xml</code> file and selected by the user are called explicitly. For the same reason be carful with the <code>if</code> attribute in target elements.</li>
1323 <li>Classpath modifications are irrelevant if all classes are packaged in a self-extracting or non-extracting Jar. Any task dependencies should be packaged with into the Jar with the <code>zipgroupfileset</code> fileset type.
1324 <br/>for example <br/><code>&lt;zipgroupfileset dir="tasklibs" includes="*.jar"/&gt;</code></li>
1325 <li>The <code>basedir</code> attribute, if specifed in the project element, is ignored and set by AntInstaller. It is included in many AntInstaller examples since most tools expect this attribute to be present.</li>
1326 <li>The <code>${ant.home}</code> property should not be relied upon, The computer on which the installer is being run may not have Ant installed.</li>
1327 <li>Ant dependencies, for example Jars for optional tasks, should be explicitly added to the installer jar with a <code>zipgroupfileset</code>. </li>
1328 <li>Some other default Ant properties that relate to a presumed Ant configuration are not reliable due to the way Ant is launched in AntInstaller, for example <code>${ant.file}</code> </li>
1329 <li>Some complex output redirections do not work as expected since output is already redirected to the log files.</li>
1330</ul>
1331
1332 <br/><a name="scripts"></a>
1333 <h3><code>install.sh</code> Start scripts</h3>
1334It is recommended to run create installers as <a href="#extractor">self extracting jars</a>, but it is
1335possible to run the installer from scripts as a normal Java application.
1336Create a new directory and prepare the files as you would
1337for a normal Ant build. You can include the <code>install.sh</code>
1338and <code>install.cmd</code> files from the demo app to launch the
1339installer. These scripts can be launched in a GUI by double clicking on
1340them, but they will require editing to set your classpath and resources correctly.<br/>
1341The main class (<code><a href="java2html/antinstaller/org/tp23/antinstaller/runtime/ExecInstall.java.html">org.tp23.antinstaller.runtime.ExecInstall</a></code>) that starts the installer takes two parameters
1342on the command line which should be set in the start script.<br/>
1343The first is the default
1344GUI mode (either swing or text). <br/>
1345The second is the Ant basedir and typically it should be just "." the current directory.
1346This directory will be the basedir of the ant script no matter what it says in the <code>build.xml</code> file.
1347 <br/>
1348The Ant runner currently passes the directory called <code>antlib</code>
1349in which
1350you can add any Ant optional jars to get them to auto load. You
1351can also load them on classpath of the install scripts.<br/>
1352 <br/><a name="extractor"></a>
1353 <h3>Self Extracting Jars</h3>
1354 There is a mechanism to create a self extracting Jar where the entire installer,
1355 all requried Java code, and the resources to install can be packaged into a single Jar.
1356 The Jar is launched by double clicking on it (if the <code>.jar</code> extension is registered properly by Java) or by calling
1357 the command <code>java -jar [jar_name].jar</code>.<br/>
1358 In windows if the extension <code>.jar</code> has been re-registered (e.g. to open with winzip) right clicking on the jar
1359 and selecting <code>Open With</code> then <code>javaw</code> will also run the installer.<br/>
1360 Packaging a self extracting jar can be achieved with Ant.
1361 See <a href="installertask.html">Installer Ant Task</a> to automate creation of SelfExtracting jars. <br/><br/>
1362
1363 When the isntaller is run all the contents of the jar will be extracted to a temporary
1364 directory on the users machine. This temporary directoy is the base directory for the Ant
1365 build when run.
1366 The build.xml file should not include any relative file references. The <code>${basedir}</code> property is required since
1367 the file is excracted a new empty temporary directory that is not know when
1368 the <code>build.xml</code> file is being written. This directory will be the value of <code>${basedir}</code>
1369 when the installer is run. If packagine the self extractor manually without using the AntInstaller task the main class should be set in the manifest. <br/>
1370 Here is an example <code>MANIFEST.MF</code> file.<br/>
1371 <pre>
1372Manifest-Version: 1.0
1373Main-Class: <a href="java2html/antinstaller/org/tp23/antinstaller/selfextract/SelfExtractor.java.html">org.tp23.antinstaller.selfextract.SelfExtractor</a>
1374Look-And-Feel: org.tp23.jgoodies.plaf.plastic.PlasticXPLookAndFeel
1375 </pre>
1376 The Look And Feel is also required in the <code>MANIFEST.MF</code> file since the autoextract code shows a progress bar using Swing.
1377 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 updating the UI, not LAFs all do.
1378 <br/>
1379 <br/>If a resource is included called <code>/resources/extract-image.png</code> it will be displayed during the
1380 extraction process. You can remove the image from the classpath if you don't like it or change it to any other
1381 png image of the same size.<br/>
1382 <img src="images/extract-image-example.png" alt="example extract image"/>
1383 <br/>
1384 <br/>
1385 <br/><a name="non-extractor"></a>
1386 <h3>Non Extracting Jars</h3>
1387 As of version 0.7.2 a feature has been added to load the installer without having to extract any files until the
1388 Ant build is run. This has the advantage of not having to unjar AntInstaller itself or its dependencies such as Ant and the look and feel.
1389 See <a href="installertask.html">Installer Ant Task</a> to automate creation of NonExtracting jars. <br/><br/>
1390 If you are manually packaging the Jar in order to specify that the NonExtractor should be used the Jar <code>META-INF/MANIFEST.MF</code> file should specify
1391 <code><a href="java2html/antinstaller/org/tp23/antinstaller/selfextract/NonExtractor.java.html">org.tp23.antinstaller.selfextract.NonExtractor</a></code>. Since the NonExtractor does not need to show
1392 the progress bar for the extraction no look and feel is required in the manifest.
1393 An example <code>META-INF/MANIFEST.MF</code>
1394 <pre>
1395Manifest-Version: 1.0
1396Main-Class: <a href="java2html/antinstaller/org/tp23/antinstaller/selfextract/NonExtractor.java.html">org.tp23.antinstaller.selfextract.NonExtractor</a>
1397 </pre>
1398 The NonExctractor still creates temporary space on the deployment system and still sets the <code>${basedir}</code>
1399 to this space.
1400 The <code>build.xml</code> file and the <code>antinstall-config.xml</code> are read from inside the Jar and all
1401 properties are passed directly
1402 to Ant. The properties file is still readable for debuging installers. In order to access and extract resources inside the Jar the unzip or unjar Ant tasks should be used. In order to identify the Jar file in teh build.xml file a new property has been added <code>${antinstaller.jar}</code>.
1403 The following example
1404 extracts a file called <code>myresource.zip</code> into the temporary directory (from there it could be unzipped
1405 to the deployment directory)
1406 <pre>
1407&lt;unzip src="${antinstaller.jar}" dest="${basedir}"&gt;
1408 &lt;patternset&gt;
1409 &lt;include name="myresource.zip"/&gt;
1410 &lt;/patternset&gt;
1411&lt;/unzip&gt;</pre>
1412 A more likely example is to unzip all the files in your application to the installation directory selected by the user.
1413 <pre>
1414&lt;unzip src="${antinstaller.jar}" dest="${my.installation.dir}"&gt;
1415 &lt;patternset&gt;
1416 &lt;include name="bin/*"/&gt;
1417 &lt;include name="classes/*"/&gt;
1418 &lt;include name="help/*"/&gt;
1419 &lt;include name="doc/*"/&gt;
1420 &lt;/patternset&gt;
1421&lt;/unzip&gt;</pre>
1422 Remember all the classes for AntInstaller need to be in the root of the Jar for the JVM to find them when the
1423 Jar is first loaded so it is probably best to put all the deployable resources in a subdirectory inside the Jar
1424 This will prevent name clashes with the Jars contents which are in the <code>org</code>, <code>META-INF</code> and <code>resources</code> directories. <br/>
1425
1426 <a name="refs"></a>
1427 <h3>Dynamic References</h3>
1428 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>.
1429 References can be mixed with normal text as in Ant. <br/>
1430 For example, <br/>
1431<pre>
1432&lt;text
1433 property="new.property"
1434 displayText="Enter the installation directory"
1435 defaulValue="/usr/local/${project.short.name}"
1436 defaultValueWin="C:\Program Files\${project.short.name}"
1437 create="true"
1438/&gt;
1439</pre>
1440 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/>
1441 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/>
1442 The environment is NOT added by default to the build.xml or the installer when Ant runs, if you need the environment
1443 in the <code>build.xml</code> file call it in the usual way
1444 Also the java system properties are included prefixed by "java.". For example, <code>${java.user.name}</code> returns the user currently running the installer.
1445<br/><br/>
1446 Dynamic references can use nested property values. For example, if the value of <code>${target.server}</code> is <code>tomcat</code>,
1447 the following syntax can be used to set the default value of an input property to be the value of <code>${tomcat.default.http.port}</code><br/>
1448<pre>
1449&lt;validated
1450 property="http.port"
1451 displayText="HTTP port:"
1452 defaultValue="${${target.server}.default.http.port}"
1453 regex="^[0-9]{2,5}$"
1454/&gt;
1455</pre>
1456<br/>
1457 Dynamic references have the following limitations<br/>
1458 <br/>
1459 <ul>
1460 <li>Dynamic references can only be added to <code>defaultValue</code>, <code>defaultValueWin</code>, comment <code>displayText</code>, comment <code>explanatoryText</code> and text or html in a <a href="#pagetext" title="Text pages">text page</a> (currently)</li>
1461 <li>The properties must have been set in previous pages not in the current page (or future pages)</li>
1462 <li>Unlike Ant if the property has not been evaluated a blank string "" will be inserted instead of the reference.
1463 This means accidents like <code>/usr/local/${non.prop}</code> should not happen but will use <code>/usr/local</code>, generally neither case
1464 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 notget accepted.</li>
1465 <li>Once a user has edited a field the evaluation stops.<br/>
1466 For example, on the first page <code>${proj.short.name}</code> is set
1467 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
1468 <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>
1469 </ul>
1470
1471 <br/>
1472 <br/>
1473 <a name="pagedisplay"></a>
1474 <h3>Page Displaying</h3>
1475 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. Two mechanism are available to achieve this.
1476 <br/><br/>
1477 The first mechanism is to use a <code>target</code> input on a previous page and then add <code>ifTarget</code> attributes to the subsequent page elements.
1478
1479 The second mechanism uses the <code>ifProperty</code> attribute to conditionally show pages based on the existence or value 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.
1480
1481 See the ifProperty attribute of the <a href="#pageinput">InputPage</a> type.
1482
1483 <br/><br/>
1484 <a href="index.html"><img class="but" src="images/ant-install-small.png" alt="home"></a>
1485<!-- Do not edit the following line used by manual-print.jsp -->
1486 <!-- content end [segment-end]-->
1487 </div>
1488 </td>
1489 </tr>
1490 </tbody>
1491</table>
1492<div id="contents-panel">
1493<!--[segment-file://contents-include.html] menu start -->
1494<div id="contents-menu">
1495<ol class="sidebar" id="root">
1496 <li class="panel"><a href="#default" class="folder" onclick="toggle(this)"></a><b>Site map</b>
1497 <ol>
1498 <li class="sidebar"><a href="introduction.html">Introduction</a></li>
1499 <li class="panel"><a href="#default" class="folder" onclick="toggle(this)"></a><b>Developer References</b>
1500 <ol>
1501 <li class="sidebar"><a href="quickstart.html">Quick Start</a></li>
1502 <li class="panel"><a href="#default" class="folder" onclick="toggle(this)"></a><a href="manual.html">Manual</a>
1503 <ol class="init-hidden">
1504 <li class="sidebar"><a href="manual.html#config">antinstall-config.xml</a></li>
1505 <li class="panel"><a href="#default" class="folder" onclick="toggle(this)"></a><a href="manual.html#page">Pages</a>
1506 <ol class="init-hidden">
1507 <li class="sidebar"><a href="manual.html#pagesplash">Splash Page</a></li>
1508 <li class="sidebar"><a href="manual.html#pagetext">Text Page</a></li>
1509 <li class="sidebar"><a href="manual.html#pagelicense">License Page</a></li>
1510 <li class="sidebar"><a href="manual.html#pageinput">Input Page</a></li>
1511 <li class="sidebar"><a href="manual.html#pageprogress">Progress Page</a></li>
1512 </ol>
1513 </li>
1514 <li class="panel"><a href="#default" class="folder" onclick="toggle(this)"></a><a href="manual.html#inputtypes">Input types</a>
1515 <ol class="init-hidden">
1516 <li class="sidebar"><a href="manual.html#app-root">Application Root</a></li>
1517 <li class="sidebar"><a href="manual.html#checkbox">Checkbox</a></li>
1518 <li class="sidebar"><a href="manual.html#comment">Comment</a></li>
1519 <li class="sidebar"><a href="manual.html#date">Date</a></li>
1520 <li class="sidebar"><a href="manual.html#directory">Directory</a></li>
1521 <li class="sidebar"><a href="manual.html#file">File</a></li>
1522 <li class="sidebar"><a href="manual.html#large-select">Large Select</a></li>
1523 <li class="sidebar"><a href="manual.html#password">Password Text</a></li>
1524 <li class="sidebar"><a href="manual.html#password-confirm">Confirm Password</a></li>
1525 <li class="sidebar"><a href="manual.html#select">Select</a></li>
1526 <li class="sidebar"><a href="manual.html#target">Target</a></li>
1527 <li class="sidebar"><a href="manual.html#target-select">Target Select</a></li>
1528 <li class="sidebar"><a href="manual.html#text">Unvalidated Text</a></li>
1529 <li class="sidebar"><a href="manual.html#validated">Validated Text</a></li>
1530 <li class="sidebar"><a href="manual.html#extvalidated">Externally Validated Text</a></li>
1531 </ol>
1532 </li>
1533 <li class="sidebar"><a href="manual.html#extractor">Self Extractor</a></li>
1534 <li class="sidebar"><a href="manual.html#non-extractor">Non Extractor</a></li>
1535 <li class="sidebar"><a href="manual.html#scripts">Start Scripts</a></li>
1536 <li class="sidebar"><a href="manual.html#refs">Dynamic References</a></li>
1537 <li class="sidebar"><a href="manual.html#pagedisplay">Page Displaying</a></li>
1538 </ol>
1539 </li>
1540 <li class="sidebar"><a href="installertask.html">Installer Ant task</a></li>
1541 <li class="sidebar"><a href="validationofconfig.html">Validation of config</a></li>
1542 <li class="sidebar"><a href="lookandfeels.html">LookAndFeels</a> <br/>(inc screenshots)</li>
1543 <li class="sidebar"><a href="classpathresources.html">Resources/Classpath issues</a></li>
1544 <li class="sidebar"><a href="i18n.html">Internationalisation</a></li>
1545 <li class="sidebar"><a href="auto.html">Automated installs</a></li>
1546 <li class="sidebar"><a href="installtypes.html">Multiple install types</a></li>
1547 <li class="sidebar"><a href="posttargets.html">Post display targets</a></li>
1548 <li class="sidebar"><a href="icons.html">Button Icons</a></li>
1549 <li class="sidebar"><a href="antinstall-config-example.html">Example antinstall-config.xml</a></li>
1550 </ol>
1551 </li>
1552 <li class="sidebar"><a href="manual-ant.html">Ant Manual</a></li>
1553 <li class="sidebar"><a href="antlinks.html">Ant links</a></li>
1554 <li class="sidebar"><a href="userusage.html">User usage</a></li>
1555 <li class="sidebar"><a href="licenses.html">Licenses</a></li>
1556 <li class="sidebar"><a href="potentialuses.html">Potential uses</a></li>
1557 <li class="sidebar"><a href="roadmap.html">Road Map</a></li>
1558 <li class="sidebar"><a href="wanted.html">Wanted</a></li>
1559 <li class="sidebar"><a href="dtds.html">DTDs</a></li>
1560 <li class="sidebar"><a href="changelog.html">Changelog</a></li>
1561 <li class="sidebar"><a href="http://sourceforge.net/projects/antinstaller">Project page on SourceForge</a></li>
1562 <li class="sidebar"><a href="java2html/antinstaller/index.html">Java2HTML (main)</a></li>
1563 <li class="sidebar"><a href="java2html/ext/index.html">Java2HTML (extensions)</a></li>
1564 <li class="sidebar"><a href="http://antinstaller.cvs.sourceforge.net/antinstaller">Public CVS over HTTP</a></li>
1565 <li class="sidebar"><a href="http://sourceforge.net/sendmessage.php?touser=616485">Contact AntInstaller Admin</a></li>
1566 </ol>
1567 </li>
1568</ol>
1569<br/>
1570<br/>
1571</div>
1572
1573
1574<!-- menu end [segment-end]-->
1575</div>
1576<div id="contents-options">
1577<a id="toggle" href="#" onclick="toggleMenu(); return false;">show menu</a>
1578</div>
1579
1580</div>
1581</body>
1582</html>
Note: See TracBrowser for help on using the repository browser.