svn-gvsig-desktop / branches / v2_0_0_prep / build / distribution / IzPack / doc / izpack / html / node8.html @ 23393
History | View | Annotate | Download (46.3 KB)
| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|---|
| 2 |
|
| 3 |
<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
|
| 4 |
original version by: Nikos Drakos, CBLU, University of Leeds
|
| 5 |
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
|
| 6 |
* with significant contributions from:
|
| 7 |
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
|
| 8 |
<HTML>
|
| 9 |
<HEAD>
|
| 10 |
<TITLE>User Input</TITLE> |
| 11 |
<META NAME="description" CONTENT="User Input"> |
| 12 |
<META NAME="keywords" CONTENT="izpack-doc"> |
| 13 |
<META NAME="resource-type" CONTENT="document"> |
| 14 |
<META NAME="distribution" CONTENT="global"> |
| 15 |
|
| 16 |
<META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1"> |
| 17 |
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| 18 |
|
| 19 |
<LINK REL="STYLESHEET" HREF="izpack-doc.css"> |
| 20 |
|
| 21 |
<LINK REL="next" HREF="node9.html"> |
| 22 |
<LINK REL="previous" HREF="node7.html"> |
| 23 |
<LINK REL="up" HREF="izpack-doc.html"> |
| 24 |
<LINK REL="next" HREF="node9.html"> |
| 25 |
</HEAD>
|
| 26 |
|
| 27 |
<BODY > |
| 28 |
|
| 29 |
<DIV CLASS="navigation"><!--Navigation Panel--> |
| 30 |
<A NAME="tex2html479" |
| 31 |
HREF="node9.html"> |
| 32 |
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> |
| 33 |
<A NAME="tex2html475" |
| 34 |
HREF="izpack-doc.html"> |
| 35 |
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> |
| 36 |
<A NAME="tex2html469" |
| 37 |
HREF="node7.html"> |
| 38 |
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> |
| 39 |
<A NAME="tex2html477" |
| 40 |
HREF="node1.html"> |
| 41 |
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> |
| 42 |
<BR>
|
| 43 |
<B> Next:</B> <A NAME="tex2html480" |
| 44 |
HREF="node9.html">Custom Actions</A> |
| 45 |
<B> Up:</B> <A NAME="tex2html476" |
| 46 |
HREF="izpack-doc.html">izpack-doc</A> |
| 47 |
<B> Previous:</B> <A NAME="tex2html470" |
| 48 |
HREF="node7.html">Creating Your Own Panels</A> |
| 49 |
<B> <A NAME="tex2html478" |
| 50 |
HREF="node1.html">Contents</A></B> |
| 51 |
<BR>
|
| 52 |
<BR></DIV> |
| 53 |
<!--End of Navigation Panel-->
|
| 54 |
<!--Table of Child-Links-->
|
| 55 |
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A> |
| 56 |
|
| 57 |
<UL CLASS="ChildLinks"> |
| 58 |
<LI><A NAME="tex2html481" |
| 59 |
HREF="node8.html#SECTION00810000000000000000">The Basic XML Structure</A> |
| 60 |
<LI><A NAME="tex2html482" |
| 61 |
HREF="node8.html#SECTION00820000000000000000">Concepts and XML Elements Common to All Fields</A> |
| 62 |
<LI><A NAME="tex2html483" |
| 63 |
HREF="node8.html#SECTION00830000000000000000">Internationalization</A> |
| 64 |
<LI><A NAME="tex2html484" |
| 65 |
HREF="node8.html#SECTION00840000000000000000">Panel Title</A> |
| 66 |
<LI><A NAME="tex2html485" |
| 67 |
HREF="node8.html#SECTION00850000000000000000">Static Text</A> |
| 68 |
<LI><A NAME="tex2html486" |
| 69 |
HREF="node8.html#SECTION00860000000000000000">Visual Separation</A> |
| 70 |
<LI><A NAME="tex2html487" |
| 71 |
HREF="node8.html#SECTION00870000000000000000">Text Input</A> |
| 72 |
<LI><A NAME="tex2html488" |
| 73 |
HREF="node8.html#SECTION00880000000000000000">Radio Buttons</A> |
| 74 |
<LI><A NAME="tex2html489" |
| 75 |
HREF="node8.html#SECTION00890000000000000000">Combo Box</A> |
| 76 |
<LI><A NAME="tex2html490" |
| 77 |
HREF="node8.html#SECTION008100000000000000000">Check Box</A> |
| 78 |
<LI><A NAME="tex2html491" |
| 79 |
HREF="node8.html#SECTION008110000000000000000">Rule Input</A> |
| 80 |
<UL>
|
| 81 |
<LI><A NAME="tex2html492" |
| 82 |
HREF="node8.html#SECTION008111000000000000000">Layout and Input Rules</A> |
| 83 |
<LI><A NAME="tex2html493" |
| 84 |
HREF="node8.html#SECTION008112000000000000000">Setting Field Content</A> |
| 85 |
<LI><A NAME="tex2html494" |
| 86 |
HREF="node8.html#SECTION008113000000000000000">The Output Format</A> |
| 87 |
<LI><A NAME="tex2html495" |
| 88 |
HREF="node8.html#SECTION008114000000000000000">Validating the Field Content</A> |
| 89 |
<UL>
|
| 90 |
<LI><A NAME="tex2html496" |
| 91 |
HREF="node8.html#SECTION008114100000000000000">NotEmptyValidator</A> |
| 92 |
<LI><A NAME="tex2html497" |
| 93 |
HREF="node8.html#SECTION008114200000000000000">RegularExpressionValidator</A> |
| 94 |
<LI><A NAME="tex2html498" |
| 95 |
HREF="node8.html#SECTION008114300000000000000">Creation Your Own Custom Validator</A> |
| 96 |
</UL>
|
| 97 |
<LI><A NAME="tex2html499" |
| 98 |
HREF="node8.html#SECTION008115000000000000000">Processing the Field Content</A> |
| 99 |
<LI><A NAME="tex2html500" |
| 100 |
HREF="node8.html#SECTION008116000000000000000">Summary Example</A> |
| 101 |
</UL>
|
| 102 |
<BR>
|
| 103 |
<LI><A NAME="tex2html501" |
| 104 |
HREF="node8.html#SECTION008120000000000000000">Search</A> |
| 105 |
<UL>
|
| 106 |
<LI><A NAME="tex2html502" |
| 107 |
HREF="node8.html#SECTION008121000000000000000">Specification</A> |
| 108 |
<LI><A NAME="tex2html503" |
| 109 |
HREF="node8.html#SECTION008122000000000000000">Example</A> |
| 110 |
</UL></UL> |
| 111 |
<!--End of Table of Child-Links-->
|
| 112 |
<HR>
|
| 113 |
|
| 114 |
<H1><A NAME="SECTION00800000000000000000"></A><A NAME="chap:userinput"></A> |
| 115 |
<BR>
|
| 116 |
User Input |
| 117 |
</H1> (by Elmar G<SMALL>ROM</SMALL>) |
| 118 |
<BR>
|
| 119 |
<P>
|
| 120 |
Most of the panels that come with IzPack take user input in some form. |
| 121 |
In some panels this is through a simple user acknowledgment in others |
| 122 |
the user can enter text or select a directory through a file open |
| 123 |
dialog. In all of those cases the user input is used for the specific |
| 124 |
purpose needed by the panel that takes the input. However, if you need |
| 125 |
user input during installation that will later on be available to your |
| 126 |
application then you need to use the user input panel. |
| 127 |
<BR>
|
| 128 |
<P>
|
| 129 |
To use this panel, list it in the install file with the class name |
| 130 |
<TT>UserInputPanel</TT>. In addition, you must write a XML specification |
| 131 |
and add it to the install resources. The name of this resource must be |
| 132 |
<TT>userInputSpec.xml</TT>. |
| 133 |
<BR>
|
| 134 |
<P>
|
| 135 |
The user input panel is a blank panel that can be populated with UI |
| 136 |
elements through a XML specification file. The specification supports |
| 137 |
text labels, input elements, explanatory text and some minor formatting |
| 138 |
options. |
| 139 |
<BR>
|
| 140 |
<P>
|
| 141 |
The following types of user input elements are supported: |
| 142 |
|
| 143 |
<UL>
|
| 144 |
<LI>Text
|
| 145 |
</LI>
|
| 146 |
<LI>Combo Box
|
| 147 |
</LI>
|
| 148 |
<LI>Radio Buttons
|
| 149 |
</LI>
|
| 150 |
<LI>Check Box
|
| 151 |
</LI>
|
| 152 |
<LI>Rule Input Field
|
| 153 |
</LI>
|
| 154 |
<LI>Search Field
|
| 155 |
</LI>
|
| 156 |
</UL>
|
| 157 |
<P>
|
| 158 |
The way in which this panel conveys the user input to your application |
| 159 |
is through the variable substitution system. User input is not directly |
| 160 |
inserted into your configuration files but the variables that you |
| 161 |
specify for this panel are set in the variable substitution system. |
| 162 |
After this operation has taken place the variables and associated values |
| 163 |
are available for all substitutions made. This way of operation has a |
| 164 |
number of implications that you should be aware of. |
| 165 |
<BR>
|
| 166 |
<P>
|
| 167 |
First, not only can you set additional variables in this way but you can |
| 168 |
also modify variables that are defined elsewhere -even built in |
| 169 |
variables. For this reason you should be careful to avoid overlaps when |
| 170 |
choosing variable names. Although there might be cases when it seems |
| 171 |
useful to modify the value of other variables, it is generally not a |
| 172 |
good idea to do so. Because you might not exactly know when other |
| 173 |
variables are set and when and where they are used throughout the |
| 174 |
installation process, there might be unintended side effects. |
| 175 |
<BR>
|
| 176 |
<P>
|
| 177 |
Second, the panel must be shown at a point during the installation |
| 178 |
process before the variables are used. In most cases you will use the |
| 179 |
values to substitute variables in launch and configuration files that |
| 180 |
you supply with your installation. For this to work you place this panel |
| 181 |
before the install panel, because the install panel uses the variable |
| 182 |
substitutor to replace all such variables. Although using this panel any |
| 183 |
later in the process will correctly set the variables internally, there |
| 184 |
won't be any affect on the files written to disk. You can also use |
| 185 |
variables set in this way in other panels that you have written |
| 186 |
yourself. There is a section in the chapter on writing your own panel |
| 187 |
that explains how to do this. Also in this case it is important to place |
| 188 |
the associated input panel in the process before the variables are |
| 189 |
used. |
| 190 |
<BR>
|
| 191 |
<P>
|
| 192 |
At this point I would also like to mention that it is possible to hide |
| 193 |
select elements on the panel or the panel altogether if certain packs |
| 194 |
are not selected. For this to work you must place this panel after the |
| 195 |
packs panel. One side effect of using this feature is that it is not |
| 196 |
possible to step back once the user input panel is displayed. This is |
| 197 |
because the user might make changes in the packs selection that would |
| 198 |
require a complete rebuild of the UI. Unfortunately, building the UI is |
| 199 |
an irreversible process, therefore the user can not be allowed to go |
| 200 |
back to the packs panel. |
| 201 |
<BR>
|
| 202 |
<P>
|
| 203 |
|
| 204 |
<H1><A NAME="SECTION00810000000000000000"> |
| 205 |
The Basic XML Structure</A>
|
| 206 |
</H1>
|
| 207 |
|
| 208 |
<P>
|
| 209 |
The top level XML section is called <TT><userInput></TT>. For most |
| 210 |
panels it does not make sense to present them more than once, however |
| 211 |
you might want to present multiple user input panels -with different |
| 212 |
content of course. Therefore the <TT><userInput></TT> section can |
| 213 |
contain multiple tags that each specify the details for one panel |
| 214 |
instance. The tag name for this is <TT><panel></TT>. |
| 215 |
<BR>
|
| 216 |
<P>
|
| 217 |
The <TT><panel></TT> tag uses the following attributes: |
| 218 |
<BR>
|
| 219 |
<P>
|
| 220 |
<SPAN CLASS="textbf">order</SPAN> <TT>- required</TT> |
| 221 |
<BR>
|
| 222 |
<P>
|
| 223 |
This is the order number of the user input panel for which this |
| 224 |
specification should be used. Counting starts at 0 and increments by 1 |
| 225 |
for each instance of the user input panel. So if a spec should be used |
| 226 |
for the second occurrence of the user input panel use |
| 227 |
<TT>order="1"</TT>. |
| 228 |
<BR>
|
| 229 |
<P>
|
| 230 |
<SPAN CLASS="textbf">layout</SPAN> <TT>- optional</TT> |
| 231 |
<BR>
|
| 232 |
<P>
|
| 233 |
There are three general layout rules this panel uses, they are |
| 234 |
<TT>left</TT>, <TT>center</TT> and <TT>right</TT>. While I think left is |
| 235 |
most commonly used, you might want to experiment with this attribute and |
| 236 |
see which you like best. The default is <TT>left</TT>. |
| 237 |
<BR>
|
| 238 |
<P>
|
| 239 |
|
| 240 |
<H1><A NAME="SECTION00820000000000000000"> |
| 241 |
Concepts and XML Elements Common to All Fields</A>
|
| 242 |
</H1>
|
| 243 |
|
| 244 |
<P>
|
| 245 |
Before I dive into the details of defining the various UI elements I |
| 246 |
would like to present XML elements and general concepts that apply |
| 247 |
throughout. This saves me a lot of work in writing and you a lot of |
| 248 |
repetitive reading and maybe a tree or two. |
| 249 |
<BR>
|
| 250 |
<P>
|
| 251 |
The UI elements are generally laid out top to bottom in the order they |
| 252 |
appear in the XML file. The only exception to this rule is the title, |
| 253 |
which always appears at the very top. The layout pattern for the input |
| 254 |
fields is as follows: If a description is defined, it appears first, |
| 255 |
using the full available layout width. The input field is placed beneath |
| 256 |
the description. With fields such as the text field or the combo box, |
| 257 |
the label is placed to the left and the input field to the right. Fields |
| 258 |
such as radio buttons and check boxes are somewhat indented and have the |
| 259 |
label text appear to their right. |
| 260 |
<BR>
|
| 261 |
<P>
|
| 262 |
Each UI element is specified with a <TT><field></TT> tag. The |
| 263 |
<TT>type</TT> attribute is used to specify what kind of field you want |
| 264 |
to place. Obviously, the <TT>type</TT> attribute is not optional. |
| 265 |
<BR>
|
| 266 |
<P>
|
| 267 |
Each field that takes user input must also specify the variable that |
| 268 |
should be substituted. This is done with the <TT>variable</TT> |
| 269 |
attribute. |
| 270 |
<BR>
|
| 271 |
<P>
|
| 272 |
<A NAME="userInput:descriptiontag"></A>Almost all fields allow a description. When a description is allowed it |
| 273 |
is always added in the same way. The description is part of the data |
| 274 |
within the field tag. There can only be one description per field. If |
| 275 |
you add more than one, the first one is used and the others ignored. |
| 276 |
There are three attributes used with this tag. The text is specified |
| 277 |
through the <TT>txt</TT> or the <TT>id</TT> attribute. The details on |
| 278 |
using them are described below. The attributes are all optional but you |
| 279 |
must specify text to use, either directly or through the <TT>id</TT> |
| 280 |
attribute. In addition, you can set the text justification to |
| 281 |
<TT>left</TT>, <TT>center</TT> and <TT>right</TT> with the |
| 282 |
<TT>align</TT> attribute. |
| 283 |
<BR>
|
| 284 |
<P>
|
| 285 |
The following example illustrates the general pattern for field specification: |
| 286 |
<BR>
|
| 287 |
<P>
|
| 288 |
<PRE>
|
| 289 |
<field type="text" variable="myFirstVariable"> |
| 290 |
<description align="left" txt="A description" id="description 1"/> |
| 291 |
. |
| 292 |
. |
| 293 |
. |
| 294 |
</field> |
| 295 |
</PRE>
|
| 296 |
<P>
|
| 297 |
A very frequently used pattern is for the definition of text. Where ever |
| 298 |
text is needed (labels, descriptions, static text, choices etc.) it can |
| 299 |
be specified in place using the <TT>txt</TT> attribute. This is |
| 300 |
convenient if you are only supporting a single language. However, if you |
| 301 |
would like to separate your text definitions from the panel |
| 302 |
specification or if you need to support multiple languages you might |
| 303 |
want to use the <TT>id</TT> attribute instead to only specify an |
| 304 |
identifier. You can then add multiple XML files with the same name as |
| 305 |
this spec file (userInputSpec.xml) appended with an unserscore '_' and |
| 306 |
the the appropriate three letter ISO3 language code. The content of |
| 307 |
those files must conform to the specification for IzPack language |
| 308 |
packages. For more details on this topic see the chapter on language |
| 309 |
packages under advanced features. <TT>id</TT> defines an identifier that |
| 310 |
is also defined in the language package, together with the localized |
| 311 |
text to use. It is possible to use both the <TT>txt</TT> and the |
| 312 |
<TT>id</TT> attribute. In this case the text from the language package |
| 313 |
is used. If for some reason the language package is not available or the |
| 314 |
<TT>id</TT> is not defined there, the text specified with <TT>txt</TT> |
| 315 |
is used as default. |
| 316 |
<BR>
|
| 317 |
<P>
|
| 318 |
All input fields can be pre-set with a value of your choice. Although |
| 319 |
the details vary a bit from field type to field type, the <TT>set</TT> |
| 320 |
attribute is always used to accomplish this. The <TT>set</TT> attribute |
| 321 |
is of course optional. |
| 322 |
<BR>
|
| 323 |
<P>
|
| 324 |
All fields that take user input use a <TT><spec></TT> tag to define the |
| 325 |
details of the input field. In the some cases the content of this tag is |
| 326 |
rather simple. Input fields with a more complex nature tend to have |
| 327 |
accordingly complex content in this tag. Since the details vary widely, |
| 328 |
they are explained with each input field. |
| 329 |
<BR>
|
| 330 |
<P>
|
| 331 |
Any number of <TT><createForPack name=''a pack name'' /></TT> tags can be |
| 332 |
added to the <TT><panel></TT> and <TT><field></TT> sections. This tag |
| 333 |
has only one attribute and no data. The attribute is <TT>name</TT> and |
| 334 |
specifies the name of one of the installation packs that you have |
| 335 |
defined. Here is how it works: if no <TT><createForPack ...></TT> tag |
| 336 |
exists in a section, the entity is always created. However, if the tag |
| 337 |
exists, the entity is only created if one or more of the listed packs |
| 338 |
are selected for installation. As mentioned before, if you are using |
| 339 |
this feature, make sure the user input panel shows up after the packs |
| 340 |
panel. |
| 341 |
<BR>
|
| 342 |
<P>
|
| 343 |
|
| 344 |
<H1><A NAME="SECTION00830000000000000000"> |
| 345 |
Internationalization</A>
|
| 346 |
</H1>
|
| 347 |
|
| 348 |
<P>
|
| 349 |
To provide internationalization you can create a file named |
| 350 |
<TT>userInputLang.xml_xyz</TT> where <TT>xyz</TT> is the ISO3 code of the language |
| 351 |
in lowercase. Please be aware that case is significant. This file has to be inserted in the resources section |
| 352 |
of <TT>install.xml</TT> with the <TT>id</TT> and <TT>src</TT> attributes |
| 353 |
set at the name of the file. |
| 354 |
<BR>
|
| 355 |
<P>
|
| 356 |
Example: |
| 357 |
<BR>
|
| 358 |
<P>
|
| 359 |
If you have the following userInputSpec.xml |
| 360 |
and you want to internationalize <TT>input.comment</TT>, <TT>input.proxy</TT>, <TT>input.port</TT> for |
| 361 |
english and french you have to create two files named userInputLang.xml_eng and userInputLang.xml_fra: |
| 362 |
<PRE>
|
| 363 |
<userInput> |
| 364 |
<panel order="0"> |
| 365 |
<field type="staticText" align="left" txt="My comment is here." id="input.comment"/> |
| 366 |
<field type="text" variable="proxyAddress"> |
| 367 |
<spec txt="Proxy Host:" id="input.proxy" size="25" set=""/> |
| 368 |
</field> |
| 369 |
<field type="text" variable="proxyPort"> |
| 370 |
<spec txt="Proxy Port:" id="input.port" size="6" set=""/> |
| 371 |
</field> |
| 372 |
</panel> |
| 373 |
</userInput> |
| 374 |
</PRE>
|
| 375 |
|
| 376 |
<P>
|
| 377 |
userInputLang.xml_eng file contains: |
| 378 |
<PRE>
|
| 379 |
<langpack> |
| 380 |
<str id="input.comment" txt="English:My comment is here."/> |
| 381 |
<str id="input.proxy" txt="English:Proxy Host:"/> |
| 382 |
<str id="input.port" txt="English:Proxy Port:"/> |
| 383 |
</langpack> |
| 384 |
</PRE>
|
| 385 |
|
| 386 |
<P>
|
| 387 |
userInputLang.xml_fra file contains: |
| 388 |
<PRE>
|
| 389 |
<langpack> |
| 390 |
<str id="input.comment" txt="French:My comment is here."/> |
| 391 |
<str id="input.proxy" txt="French:Proxy Host:"/> |
| 392 |
<str id="input.port" txt="French:Proxy Port:"/> |
| 393 |
</langpack> |
| 394 |
</PRE>
|
| 395 |
|
| 396 |
<P>
|
| 397 |
you will also have to add the following to the install.xml file |
| 398 |
<PRE>
|
| 399 |
<resources> |
| 400 |
... |
| 401 |
<res id="userInputSpec.xml" src="userInputSpec.xml"/> |
| 402 |
<res id="userInputLang.xml_eng" src="userInputLang.xml_eng" /> |
| 403 |
<res id="userInputLang.xml_fra" src="userInputLang.xml_fra" /> |
| 404 |
... |
| 405 |
</resources> |
| 406 |
</PRE>
|
| 407 |
|
| 408 |
<P>
|
| 409 |
|
| 410 |
<H1><A NAME="SECTION00840000000000000000"> |
| 411 |
Panel Title</A>
|
| 412 |
</H1>
|
| 413 |
|
| 414 |
<P>
|
| 415 |
You can place an optional title at the top of the panel. Though it is |
| 416 |
not possible to select a font for the title that is different form the |
| 417 |
one used on the rest of the panel, it is possible to modify the font to |
| 418 |
some extent. To specify the title create a <TT><field></TT> tag and use |
| 419 |
the <TT>type</TT> attribute with the value <TT>title</TT>. In addition |
| 420 |
to the <TT>txt</TT> and <TT>id</TT> attributes, the following attributes |
| 421 |
are supported: |
| 422 |
<BR>
|
| 423 |
<P>
|
| 424 |
<SPAN CLASS="textbf">italic</SPAN> <TT>- optional</TT> |
| 425 |
<BR>
|
| 426 |
<P>
|
| 427 |
With a value of <TT>true</TT> specifies that the title font should be in italics. |
| 428 |
<BR>
|
| 429 |
<P>
|
| 430 |
<SPAN CLASS="textbf">bold</SPAN> <TT>- optional</TT> |
| 431 |
<BR>
|
| 432 |
<P>
|
| 433 |
With a value of <TT>true</TT> specifies that the title font should be bold. |
| 434 |
<BR>
|
| 435 |
<P>
|
| 436 |
<SPAN CLASS="textbf">size</SPAN> <TT>- optional</TT> |
| 437 |
<BR>
|
| 438 |
<P>
|
| 439 |
This attribute specifies the size of the title font. Please note that |
| 440 |
the size is not specified in points but as a relative size multiplier |
| 441 |
compared to the body font on the panel. The default value is 2. |
| 442 |
<BR>
|
| 443 |
<P>
|
| 444 |
|
| 445 |
<H1><A NAME="SECTION00850000000000000000"> |
| 446 |
Static Text</A>
|
| 447 |
</H1>
|
| 448 |
|
| 449 |
<P>
|
| 450 |
Static text is simply text that is placed on the panel without direct |
| 451 |
connection to any of the input elements. It is laid out to use the |
| 452 |
entire layout width available on the panel and is broken into multiple |
| 453 |
lines if necessary. To specify static text create a <TT><field></TT> tag |
| 454 |
and use the <TT>type</TT> attribute with a value of <TT>staticText</TT>. |
| 455 |
In addition to the <TT>txt</TT> and <TT>id</TT> attributes, the text can |
| 456 |
be justified <TT>left</TT>, <TT>center</TT> or <TT>right</TT> with the |
| 457 |
<TT>align</TT> attribute. It is not possible to format this text in any way. |
| 458 |
<BR>
|
| 459 |
<P>
|
| 460 |
<SPAN CLASS="textbf">Example</SPAN> |
| 461 |
<BR>
|
| 462 |
<P>
|
| 463 |
The following example inserts some static text in the panel. |
| 464 |
|
| 465 |
<P>
|
| 466 |
<PRE>
|
| 467 |
<field type="staticText" align="left"
|
| 468 |
txt="This is just some simple static text." |
| 469 |
id="staticText.text"/>
|
| 470 |
</PRE>
|
| 471 |
<P>
|
| 472 |
|
| 473 |
<H1><A NAME="SECTION00860000000000000000"> |
| 474 |
Visual Separation</A>
|
| 475 |
</H1>
|
| 476 |
|
| 477 |
<P>
|
| 478 |
Sometimes it is desirable to separate different entities visually. This |
| 479 |
can be accomplished by inserting a space or a divider. A space simply |
| 480 |
inserts a vertical separation of the average height of a single line |
| 481 |
entity, such as a line of text or a an input field. A divider inserts |
| 482 |
the same amount of space but also draws a division line which can be |
| 483 |
either aligned at the top or bottom of the separation. |
| 484 |
<TT><space></TT>, <TT><divider></TT> |
| 485 |
|
| 486 |
<P>
|
| 487 |
..... maybe I should draw the line myself and add no additional space at all ... |
| 488 |
|
| 489 |
<P>
|
| 490 |
|
| 491 |
<H1><A NAME="SECTION00870000000000000000"> |
| 492 |
Text Input</A>
|
| 493 |
</H1>
|
| 494 |
|
| 495 |
<P>
|
| 496 |
A text input field allows the user to enter and edit a single line of |
| 497 |
text, without length restriction. The input field can have a label, |
| 498 |
which will show to the left of the input field and a description, which |
| 499 |
can span multiple lines. The description is placed above the input field |
| 500 |
and uses the entire available layout width. The width of the input field |
| 501 |
must be explicitly set, otherwise it will only accommodate a single |
| 502 |
character. To specify a text input field create a <TT><field></TT> tag |
| 503 |
and use the <TT>type</TT> attribute with a value of <TT>text</TT>. The |
| 504 |
<TT>txt</TT> and <TT>id</TT> attributes are not supported here. The |
| 505 |
<TT>variable</TT> attribute specifies the variable that should be |
| 506 |
replaced with the text taken from the input field. |
| 507 |
<BR>
|
| 508 |
<P>
|
| 509 |
<SPAN CLASS="textbf">The Data</SPAN> |
| 510 |
<BR>
|
| 511 |
<P>
|
| 512 |
The data consists of two items, a description and the spec. The |
| 513 |
<TT><spec></TT> tag uses four attributes. The label text is specified with |
| 514 |
<TT>txt</TT> and/or <TT>id</TT> as described above. In addition, the |
| 515 |
width of the input field as it appears on the panel can be set with the |
| 516 |
<TT>size</TT> attribute. The value must be an integer and sets the field |
| 517 |
width based on the average character width of the active font. If this |
| 518 |
is not specified, then you will end up with a very narrow field that is |
| 519 |
practically unusable. |
| 520 |
<BR>
|
| 521 |
<P>
|
| 522 |
The fourth attribute <TT>set</TT> is optional. It takes a text string to |
| 523 |
pre-fill the input field. |
| 524 |
<BR>
|
| 525 |
<P>
|
| 526 |
<SPAN CLASS="textbf">Example</SPAN> |
| 527 |
<BR>
|
| 528 |
<P>
|
| 529 |
The following example creates a text input field with a label and |
| 530 |
description. The width of the input field will be enough to accommodate |
| 531 |
15 characters. The field will be pre-set with the text 'some text' when |
| 532 |
the UI is first presented. |
| 533 |
<BR>
|
| 534 |
<P>
|
| 535 |
<PRE>
|
| 536 |
<field type="text" variable="textInput"> |
| 537 |
<description align="left" txt="A description for a text input field"
|
| 538 |
id="description.text"/>
|
| 539 |
<spec txt="Enter some text:" id="text.label" size="15" set="some text"/> |
| 540 |
</field> |
| 541 |
</PRE>
|
| 542 |
<P>
|
| 543 |
|
| 544 |
<H1><A NAME="SECTION00880000000000000000"> |
| 545 |
Radio Buttons</A>
|
| 546 |
</H1>
|
| 547 |
|
| 548 |
<P>
|
| 549 |
The radio buttons are useful when the user needs to select a specific |
| 550 |
option out of a pre-defined list of choices. This field offers an |
| 551 |
arbitrary number of mutually exclusive buttons, each with its own label. |
| 552 |
The placement of the buttons and labels is different form other fields. |
| 553 |
First, the button is placed to the left and the label text to the right. |
| 554 |
Second, the buttons are not lined up all the way to the left as other |
| 555 |
labels are but they are indented from that location. As with other |
| 556 |
fields, the description is placed above the list of radio buttons and |
| 557 |
uses the entire available layout width. To specify a set of radio |
| 558 |
buttons create a <TT><field></TT> tag and use the <TT>type</TT> |
| 559 |
attribute with a value of <TT>radio</TT>. The <TT>txt</TT> and |
| 560 |
<TT>id</TT> attributes are <SPAN CLASS="textbf">not</SPAN> supported here. As with all |
| 561 |
other input fields, the <TT>variable</TT> attribute specifies that |
| 562 |
variable that should be replaced with the user selection. |
| 563 |
<BR>
|
| 564 |
<P>
|
| 565 |
<SPAN CLASS="textbf">The Data</SPAN> |
| 566 |
<BR>
|
| 567 |
<P>
|
| 568 |
The data consists of two items, a description and the spec. The |
| 569 |
<TT><spec></TT> tag has no attributes, instead the specification details |
| 570 |
are entered as data within the <TT><spec></TT> tag. The <TT><spec></TT> |
| 571 |
data consists of one or more <TT><choice></TT> tags. One |
| 572 |
<TT><choice></TT> tag is required for each radio button. The |
| 573 |
<TT><choice></TT> tag accepts the usual <TT>txt</TT> and <TT>id</TT> |
| 574 |
attributes, which are used to specify the label text. In addition the |
| 575 |
following attributes are supported: |
| 576 |
<BR>
|
| 577 |
<P>
|
| 578 |
<SPAN CLASS="textbf">value</SPAN> <TT>- required</TT> |
| 579 |
<BR>
|
| 580 |
<P>
|
| 581 |
The <TT>value</TT> attribute is used to specify which value to insert if |
| 582 |
this associated radio button is selected. In other words, the label text |
| 583 |
has nothing to do with the value that is actually substituted for the |
| 584 |
variable. For this reason there is never an issue if multiple languages |
| 585 |
are used, the value is always the same for a given selection. |
| 586 |
<BR>
|
| 587 |
<P>
|
| 588 |
<SPAN CLASS="textbf">set</SPAN> <TT>- optional</TT> |
| 589 |
<BR>
|
| 590 |
<P>
|
| 591 |
The <TT>set</TT> attribute accepts the values <TT>true</TT> and |
| 592 |
<TT>false</TT>. Since the attribute is optional it can also be omitted, |
| 593 |
which is interpreted as <TT>false</TT>. If a value of <TT>true</TT> is |
| 594 |
used, the associated radio button will be selected when the UI is first |
| 595 |
presented. Obviously, only one of the buttons in a set should be set to |
| 596 |
<TT>true</TT>. |
| 597 |
<BR>
|
| 598 |
<P>
|
| 599 |
<SPAN CLASS="textbf">Example</SPAN> |
| 600 |
<BR>
|
| 601 |
<P>
|
| 602 |
The following example creates a set of four radio buttons with |
| 603 |
description. The second button will be selected when the UI is first |
| 604 |
presented. |
| 605 |
<BR>
|
| 606 |
<P>
|
| 607 |
<PRE>
|
| 608 |
<field type="radio" variable="radioSelection"> |
| 609 |
<description align="left" txt="This is a description for radio buttons"
|
| 610 |
id="description.radio"/>
|
| 611 |
<spec> |
| 612 |
<choice txt="the first choice" id="radio.label.1" value="1 selected" /> |
| 613 |
<choice txt="the second choice" id="radio.label.2" value="2 selected"
|
| 614 |
set="true" />
|
| 615 |
<choice txt="the third choice" id="radio.label.3" value="3 selected" /> |
| 616 |
<choice txt="the fourth choice" id="radio.label.4" value="4 selected" /> |
| 617 |
</spec> |
| 618 |
</field> |
| 619 |
</PRE>
|
| 620 |
<P>
|
| 621 |
|
| 622 |
<H1><A NAME="SECTION00890000000000000000"> |
| 623 |
Combo Box</A>
|
| 624 |
</H1>
|
| 625 |
|
| 626 |
<P>
|
| 627 |
The combo box provides essentially the same functionality as do the |
| 628 |
radio buttons, just in a different presentation stile. The advantage of |
| 629 |
the combo box is that it is easier to deal with a long list of |
| 630 |
choices. |
| 631 |
<BR>
|
| 632 |
<P>
|
| 633 |
|
| 634 |
<H1><A NAME="SECTION008100000000000000000"> |
| 635 |
Check Box</A>
|
| 636 |
</H1>
|
| 637 |
|
| 638 |
<P>
|
| 639 |
If there are a number of choices and any combination of them could be |
| 640 |
selected, not just a single one, then radio buttons are not the way to |
| 641 |
go. You might be better off using a number of check boxes. The layout |
| 642 |
for a check box works in the same way as for radio buttons. The check |
| 643 |
box is placed indented from the left most edge and the label text is |
| 644 |
placed to the right of it. Other than with radio buttons, you cannot |
| 645 |
define any number of check boxes. This field allows the definition of |
| 646 |
only one check box, which is associated with one variable. If you need |
| 647 |
multiple check boxes you need to define one field for each of them. To |
| 648 |
make it look like a cohesive group you simply provide a description only |
| 649 |
for the first check box. All of the check boxes will be positioned in |
| 650 |
such a way that they look like a group, even though they are separate |
| 651 |
entities and their selections are conveyed to different variables. The |
| 652 |
description is placed above the check box and uses the entire available |
| 653 |
layout width. To specify a check box create a <TT><field></TT> tag and |
| 654 |
use the <TT>type</TT> attribute with a value of <TT>check</TT>. As with |
| 655 |
all other input fields, the <TT>variable</TT> attribute specifies the |
| 656 |
variable that should be replaced with the user input. |
| 657 |
<BR>
|
| 658 |
<P>
|
| 659 |
<SPAN CLASS="textbf">The Data</SPAN> |
| 660 |
<BR>
|
| 661 |
<P>
|
| 662 |
The data consists of two items, a description and the spec. The |
| 663 |
<TT><spec></TT> tag accepts the usual <TT>txt</TT> and <TT>id</TT> |
| 664 |
attributes, which are used to specify the label text. In addition, the |
| 665 |
following attributes are supported: |
| 666 |
<BR>
|
| 667 |
<P>
|
| 668 |
<SPAN CLASS="textbf">true</SPAN> <TT>- required</TT> |
| 669 |
<BR>
|
| 670 |
<P>
|
| 671 |
The <TT>true</TT> attribute specifies the value to use for substitution |
| 672 |
when the box is selected. |
| 673 |
<BR>
|
| 674 |
<P>
|
| 675 |
<SPAN CLASS="textbf">false</SPAN> <TT>- required</TT> |
| 676 |
<BR>
|
| 677 |
<P>
|
| 678 |
The <TT>false</TT> attribute specifies the value to use for substitution |
| 679 |
when the box is not selected. |
| 680 |
<BR>
|
| 681 |
<P>
|
| 682 |
<SPAN CLASS="textbf">set</SPAN> <TT>- optional</TT> |
| 683 |
<BR>
|
| 684 |
<P>
|
| 685 |
The <TT>set</TT> attribute accepts the values <TT>true</TT> and |
| 686 |
<TT>false</TT>. Since the attribute is optional it can also be omitted, |
| 687 |
which is interpreted as <TT>false</TT>. If a value of <TT>true</TT> is |
| 688 |
used, the check box will be selected when the UI is first presented. |
| 689 |
<BR>
|
| 690 |
<P>
|
| 691 |
<SPAN CLASS="textbf">Example</SPAN> |
| 692 |
<BR>
|
| 693 |
<P>
|
| 694 |
The following example creates a check box with description. The check |
| 695 |
box will not be selected when the UI is first presented. This could also |
| 696 |
be accomplished by omitting the <TT>set</TT> attribute. |
| 697 |
<BR>
|
| 698 |
<P>
|
| 699 |
<PRE>
|
| 700 |
<field type="check" variable="chekSelection.1"> |
| 701 |
<description align="left" txt="This is a description for a check box"
|
| 702 |
id="description.check.1"/>
|
| 703 |
<spec txt="check box 1" id="check.label.1" true="on" false="off"
|
| 704 |
set="false"/>
|
| 705 |
</field> |
| 706 |
</PRE>
|
| 707 |
<P>
|
| 708 |
|
| 709 |
<H1><A NAME="SECTION008110000000000000000"> |
| 710 |
Rule Input</A>
|
| 711 |
</H1>
|
| 712 |
|
| 713 |
<P>
|
| 714 |
The rule input field is the most powerful and complex one of all the |
| 715 |
input fields offered by this panel. In its most simple incarnation it |
| 716 |
looks and works like a regular text input field. There is also only an |
| 717 |
incremental increase of the complexity in the specification for this |
| 718 |
case. However, it is unlikely that you would use it for such a purpose. |
| 719 |
The real power of this input field comes from the fact that rules can be |
| 720 |
applied to it that control many aspects of its look as well as overt and |
| 721 |
covert operation. |
| 722 |
<BR>
|
| 723 |
<P>
|
| 724 |
|
| 725 |
<H2><A NAME="SECTION008111000000000000000"> |
| 726 |
Layout and Input Rules</A>
|
| 727 |
</H2>
|
| 728 |
|
| 729 |
<P>
|
| 730 |
The basic nature of this input field is that of a text input field and |
| 731 |
as mentioned before, in its most simple incarnation that is what it |
| 732 |
looks like and how it operates. However, the layout of the field can be |
| 733 |
defined in such a way that there are multiple logically interconnected |
| 734 |
text input fields, adorned with multiple labels. Further more, each of |
| 735 |
these fields can be instructed to restrict the type of input that will |
| 736 |
be accepted. Now you might ask what this could be useful for. As an |
| 737 |
answer, let me present a few examples that show how this feature can be |
| 738 |
used. Before I do this however, I would like to describe the |
| 739 |
specification syntax, so that the examples can be presented together |
| 740 |
with the specifications that make them work in a meaningful way. |
| 741 |
<BR>
|
| 742 |
<P>
|
| 743 |
The actual specification of the layout, the labels and the type of input |
| 744 |
each field accepts all happens in a single string with the |
| 745 |
<TT>layout</TT> attribute. First let us have a look at the specification |
| 746 |
format for a single field. This format consists of a triplet of |
| 747 |
information, separated by two colons ':'. A typical field spec would |
| 748 |
look like this: <TT>N:4:4</TT>, where the first item is a key that |
| 749 |
specifies the type of input this particular field will accept - numeric |
| 750 |
input in the example. The second item is an integer number that |
| 751 |
specifies the physical width of the field, this is the same as in the |
| 752 |
with of any regular text field. Therefore the field in the example will |
| 753 |
provide space to display four characters. The third item specifies the |
| 754 |
editing length of the string or in other words, the maximum length of |
| 755 |
the string that will be accepted by the field. In the <TT>layout</TT> |
| 756 |
string you can list as may fields as you need, each with its own set of |
| 757 |
limitations. In addition you can add text at the front, the end and in |
| 758 |
between the fields. The various entities must be separated by white |
| 759 |
space. The behavior of this field is such that when the editing length |
| 760 |
of a field has been reached, the cursor automatically moves on to the |
| 761 |
next field. Also, when the backspace key is used to delete characters |
| 762 |
and the beginning of a field has been reached, the cursor automatically |
| 763 |
moves on to the previous field. So let us have a look a some examples. |
| 764 |
<BR>
|
| 765 |
<P>
|
| 766 |
<SPAN CLASS="textbf">Phone Number</SPAN> |
| 767 |
|
| 768 |
<P>
|
| 769 |
The following specification will produce a pre formatted input field to |
| 770 |
accept a US phone number with in-house extension. Even though the |
| 771 |
pattern is formatted into number groups as customary, complete with |
| 772 |
parentheses '(' and dash '-', entering the number is as simple as typing
|
| 773 |
all the digits. There is no need to advance using the tab key or to enter |
| 774 |
formatting characters. Because the fields only allow numeric entry, there |
| 775 |
is a much reduced chance for entering erroneous information. |
| 776 |
<TT>"( N:3:3 ) N:3:3 - N:4:4 x N:5:5"</TT>. Each of the fields uses the |
| 777 |
'N' key, indicating that only numerals will be accepted. Also, each of |
| 778 |
the fields only accepts strings of the same length as the physical width |
| 779 |
of the field. |
| 780 |
<BR>
|
| 781 |
<P>
|
| 782 |
<DIV ALIGN="CENTER"> |
| 783 |
<!-- MATH
|
| 784 |
$\fbox{\includegraphics[scale=1.0]{img/userInput-phone}}$
|
| 785 |
-->
|
| 786 |
<SPAN CLASS="MATH"><IMG |
| 787 |
WIDTH="332" HEIGHT="122" ALIGN="MIDDLE" BORDER="0" |
| 788 |
SRC="img7.png" |
| 789 |
ALT="\fbox{\includegraphics[scale=1.0]{img/userInput-phone}}"></SPAN> |
| 790 |
</DIV>
|
| 791 |
|
| 792 |
<P>
|
| 793 |
<SPAN CLASS="textbf">E-Mail Address</SPAN> |
| 794 |
|
| 795 |
<P>
|
| 796 |
This specification creates a pattern that is useful for entering an |
| 797 |
e-mail address <TT>"AN:15:U @ AN:10:40 . A:4:4"</TT>. Even though the |
| 798 |
first field is only fifteen characters wide it will accept a string of |
| 799 |
unlimited length, because the 'U' identifier is used for the edit |
| 800 |
length. The second field is a bit more restrictive by only accepting a |
| 801 |
string up to forty characters long. |
| 802 |
<BR>
|
| 803 |
<P>
|
| 804 |
<DIV ALIGN="CENTER"> |
| 805 |
<!-- MATH
|
| 806 |
$\fbox{\includegraphics[scale=1.0]{img/userInput-email}}$
|
| 807 |
-->
|
| 808 |
<SPAN CLASS="MATH"><IMG |
| 809 |
WIDTH="453" HEIGHT="131" ALIGN="MIDDLE" BORDER="0" |
| 810 |
SRC="img8.png" |
| 811 |
ALT="\fbox{\includegraphics[scale=1.0]{img/userInput-email}}"></SPAN> |
| 812 |
</DIV>
|
| 813 |
|
| 814 |
<P>
|
| 815 |
<SPAN CLASS="textbf">IP Address</SPAN> |
| 816 |
|
| 817 |
<P>
|
| 818 |
It might not be uncommon to require entering of an IP address. The |
| 819 |
following simple specification will produce the necessary input field. |
| 820 |
All fields are the same, allowing just three digits of numerical entry. |
| 821 |
<TT>"N:3:3 . N:3:3 . N:3:3 . N:3:3"</TT> |
| 822 |
<BR>
|
| 823 |
<P>
|
| 824 |
<DIV ALIGN="CENTER"> |
| 825 |
<!-- MATH
|
| 826 |
$\fbox{\includegraphics[scale=1.0]{img/userInput-IP}}$
|
| 827 |
-->
|
| 828 |
<SPAN CLASS="MATH"><IMG |
| 829 |
WIDTH="281" HEIGHT="131" ALIGN="MIDDLE" BORDER="0" |
| 830 |
SRC="img9.png" |
| 831 |
ALT="\fbox{\includegraphics[scale=1.0]{img/userInput-IP}}"></SPAN> |
| 832 |
</DIV>
|
| 833 |
|
| 834 |
<P>
|
| 835 |
<SPAN CLASS="textbf">Serial Number or Key Code</SPAN> |
| 836 |
|
| 837 |
<P>
|
| 838 |
If you ship your product with a CD key code or serial number and require |
| 839 |
this information for registration, you might want to ask the customer to |
| 840 |
transcribe that number from the CD label, so that it is later on |
| 841 |
accessible to your application. As this is always an error prone |
| 842 |
operation, the predefined pattern with the easy editing support and |
| 843 |
restriction of accepted data helps to reduce transcription errors |
| 844 |
<TT>"H:4:4 - N:6:6 - N:3:3"</TT>. This particular specification will |
| 845 |
produce three fields, the first accepting four hexadecimal, the second |
| 846 |
six numerical and the third three numerical digits. |
| 847 |
<BR>
|
| 848 |
<P>
|
| 849 |
<DIV ALIGN="CENTER"> |
| 850 |
<!-- MATH
|
| 851 |
$\fbox{\includegraphics[scale=1.0]{img/userInput-serial}}$
|
| 852 |
-->
|
| 853 |
<SPAN CLASS="MATH"><IMG |
| 854 |
WIDTH="265" HEIGHT="131" ALIGN="MIDDLE" BORDER="0" |
| 855 |
SRC="img10.png" |
| 856 |
ALT="\fbox{\includegraphics[scale=1.0]{img/userInput-serial}}"></SPAN> |
| 857 |
</DIV>
|
| 858 |
|
| 859 |
<P>
|
| 860 |
<SPAN CLASS="textbf">Limitations</SPAN> |
| 861 |
|
| 862 |
<P>
|
| 863 |
Even though the above examples all use single character labels between |
| 864 |
fields, there is no restriction on the length of these labels. In |
| 865 |
addition, it is possible to place label text in front of the first field |
| 866 |
and after the last field and the text can even contain spaces. The only |
| 867 |
limitation in this regard is the fact that all white space in the text |
| 868 |
will be reduced to a single space on the display. This means that it is |
| 869 |
not possible to use multiple spaces or tabs in the text. |
| 870 |
<BR>
|
| 871 |
<P>
|
| 872 |
The following table lists and describes all the keys that can be used in |
| 873 |
the specification string. |
| 874 |
<BR>
|
| 875 |
<P>
|
| 876 |
<DIV ALIGN="CENTER"> |
| 877 |
<TABLE CELLPADDING=3 BORDER="1" WIDTH="100%"> |
| 878 |
<TR><TH ALIGN="LEFT"><SPAN CLASS="textit">Key</SPAN></TH> |
| 879 |
<TH ALIGN="LEFT"><SPAN CLASS="textit">Meaning</SPAN></TH> |
| 880 |
<TH ALIGN="LEFT"><SPAN CLASS="textit">Description</SPAN></TH> |
| 881 |
</TR>
|
| 882 |
<TR><TD ALIGN="LEFT">N</TD> |
| 883 |
<TD ALIGN="LEFT">numeric</TD> |
| 884 |
<TD ALIGN="LEFT">The field will accept only numerals.</TD> |
| 885 |
</TR>
|
| 886 |
<TR><TD ALIGN="LEFT">H</TD> |
| 887 |
<TD ALIGN="LEFT">hexadecimal</TD> |
| 888 |
<TD ALIGN="LEFT">The field will accept only hexadecimal numerals, that is all numbers from 0-F.</TD> |
| 889 |
</TR>
|
| 890 |
<TR><TD ALIGN="LEFT">A</TD> |
| 891 |
<TD ALIGN="LEFT">alphabetic</TD> |
| 892 |
<TD ALIGN="LEFT">The field will accept only alphabetic characters. Numerals and punctuation marks will not be accepted.</TD> |
| 893 |
</TR>
|
| 894 |
<TR><TD ALIGN="LEFT">AN</TD> |
| 895 |
<TD ALIGN="LEFT">alpha-numeric</TD> |
| 896 |
<TD ALIGN="LEFT">The field will accept alphabetic characters and numerals but no punctuation marks.</TD> |
| 897 |
</TR>
|
| 898 |
<TR><TD ALIGN="LEFT">O</TD> |
| 899 |
<TD ALIGN="LEFT">open</TD> |
| 900 |
<TD ALIGN="LEFT">The filed will accept any input, without restriction.</TD> |
| 901 |
</TR>
|
| 902 |
<TR><TD ALIGN="LEFT">U</TD> |
| 903 |
<TD ALIGN="LEFT">unlimited</TD> |
| 904 |
<TD ALIGN="LEFT">This key is only legal for specifying the editing length of a fields. If used, the field imposes no length restriction on the text entered.</TD> |
| 905 |
</TR>
|
| 906 |
</TABLE>
|
| 907 |
</DIV>
|
| 908 |
|
| 909 |
<P>
|
| 910 |
|
| 911 |
<H2><A NAME="SECTION008112000000000000000"> |
| 912 |
Setting Field Content</A>
|
| 913 |
</H2>
|
| 914 |
|
| 915 |
<P>
|
| 916 |
Like all other input fields the rule input field can also be pre-filled |
| 917 |
with data and as usual, this is accomplished thought the <TT>set</TT> |
| 918 |
attribute. As you might expect, the details of setting this field are |
| 919 |
rather on the complicated side. In fact you can set each sub field |
| 920 |
individually and you can leave some of the fields blank in the process. |
| 921 |
The <TT>set</TT> specification for all sub fields is given in a single |
| 922 |
string. Each field is addressed by its index number, with the count |
| 923 |
starting at 0. The index is followed by a colon ':' and then by the |
| 924 |
content of the field. The string "0:1234 1:af415 3:awer" would fill the |
| 925 |
first subfield with <TT>1234</TT>, the second one with <TT>af415</TT> and |
| 926 |
the fourth with <TT>awer</TT>. The third subfield would stay blank |
| 927 |
and so would any additional fields that might follow. |
| 928 |
<BR>
|
| 929 |
<P>
|
| 930 |
The individual field specs must be separated with spaces. Spaces within |
| 931 |
the pre-fill values are not allowed, otherwise the result is undefined. |
| 932 |
<BR>
|
| 933 |
<P>
|
| 934 |
|
| 935 |
<H2><A NAME="SECTION008113000000000000000"> |
| 936 |
The Output Format</A>
|
| 937 |
</H2>
|
| 938 |
|
| 939 |
<P>
|
| 940 |
The user input from all subfields is combined into one single value and |
| 941 |
used to replace the variable associated with the field. You can make a |
| 942 |
number of choices when it comes to the way how the subfield content is |
| 943 |
combined. This is done with the <TT>resultFormat</TT> and |
| 944 |
<TT>separator</TT> attributes. The <TT>resultFormat</TT> attribute can |
| 945 |
take the following values: |
| 946 |
<BR>
|
| 947 |
<P>
|
| 948 |
<DIV ALIGN="CENTER"> |
| 949 |
<TABLE CELLPADDING=3 BORDER="1" WIDTH="100%"> |
| 950 |
<TR><TH ALIGN="LEFT"><SPAN CLASS="textit">Value</SPAN></TH> |
| 951 |
<TH ALIGN="LEFT"><SPAN CLASS="textit">Meaning</SPAN></TH> |
| 952 |
</TR>
|
| 953 |
<TR><TD ALIGN="LEFT"><TT>plainString</TT></TD> |
| 954 |
<TD ALIGN="LEFT">The content of all subfields is simply concatenated into one long string.</TD> |
| 955 |
</TR>
|
| 956 |
<TR><TD ALIGN="LEFT"><TT>displayFormat</TT></TD> |
| 957 |
<TD ALIGN="LEFT">The content of all subfields and all labels -as displayed- is concatenated into one long string.</TD> |
| 958 |
</TR>
|
| 959 |
<TR><TD ALIGN="LEFT"><TT>specialSeparator</TT></TD> |
| 960 |
<TD ALIGN="LEFT">The content of all subfields is concatenated into one string, using the string specified withe the <TT>separator</TT> attribute to separate the content of the subfields.</TD> |
| 961 |
</TR>
|
| 962 |
<TR><TD ALIGN="LEFT"><TT>processed</TT></TD> |
| 963 |
<TD ALIGN="LEFT">The content is processed by Java code that you supply before replacing the variable. How to do this is described below.</TD> |
| 964 |
</TR>
|
| 965 |
</TABLE>
|
| 966 |
</DIV>
|
| 967 |
|
| 968 |
<P>
|
| 969 |
|
| 970 |
<H2><A NAME="SECTION008114000000000000000"> |
| 971 |
Validating the Field Content</A>
|
| 972 |
</H2>
|
| 973 |
|
| 974 |
<P>
|
| 975 |
You can provide runtime validation for user input into a rule field via the |
| 976 |
<TT>validator</TT> element (which is a child of the <TT>field</TT> element. |
| 977 |
There are two types of built-in validators already provided: a |
| 978 |
<TT>NotEmptyValidator</TT> and a <TT>RegularExpressionValidator</TT>. You can |
| 979 |
also easily create your own validator. In all cases, if the chosen validator |
| 980 |
returns <TT>false</TT>, a messagebox will display the contents of the |
| 981 |
<TT>txt</TT> attribute and the user will be unable to continue to the next panel. |
| 982 |
<BR>
|
| 983 |
<P>
|
| 984 |
You can specify a processor for a combobox: |
| 985 |
<PRE>
|
| 986 |
<choice processor="fully.qualified.class.name"
|
| 987 |
set="selectedValue"/>
|
| 988 |
</PRE>
|
| 989 |
so that you can fill a combobox with data on a simple way. |
| 990 |
|
| 991 |
<P>
|
| 992 |
|
| 993 |
<H3><A NAME="SECTION008114100000000000000"> |
| 994 |
NotEmptyValidator</A>
|
| 995 |
</H3>
|
| 996 |
|
| 997 |
<P>
|
| 998 |
The <TT>NotEmptyValidator</TT> simply checks that the user entered a non-null |
| 999 |
value into each subfield, and returns <TT>false</TT> otherwise. |
| 1000 |
<BR>
|
| 1001 |
<P>
|
| 1002 |
|
| 1003 |
<H3><A NAME="SECTION008114200000000000000"> |
| 1004 |
RegularExpressionValidator</A>
|
| 1005 |
</H3>
|
| 1006 |
|
| 1007 |
<P>
|
| 1008 |
The <TT>RegularExpressionValidator</TT> checks that the user entered a |
| 1009 |
value which matches a specified regular expression, as accepted by the Jakarta |
| 1010 |
Regexp library |
| 1011 |
(<TT><A NAME="tex2html28" |
| 1012 |
HREF="http://jakarta.apache.org/regexp/">http://jakarta.apache.org/regexp/</A></TT>). The syntax of this implementation |
| 1013 |
is described in the javadoc of the <TT>RE</TT> class |
| 1014 |
(<TT><A NAME="tex2html29" |
| 1015 |
HREF="http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html">http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html</A></TT>). |
| 1016 |
|
| 1017 |
<P>
|
| 1018 |
You can specify the regular |
| 1019 |
expression to be tested by passing a parameter with a name of <TT>pattern</TT> |
| 1020 |
to the validator (via the <TT>param</TT> element), with the regular expression |
| 1021 |
as the <TT>value</TT> attribute. For example, the following would validate |
| 1022 |
an e-mail address: |
| 1023 |
<BR>
|
| 1024 |
<P>
|
| 1025 |
<PRE>
|
| 1026 |
<field type="rule" variable="EMAILADDRESS"> |
| 1027 |
<spec
|
| 1028 |
txt="Your Email Address:" layout="O:12:U @ O:8:40 . A:4:4" |
| 1029 |
set="0: 1:domain 2:com" resultFormat="displayFormat" |
| 1030 |
/>
|
| 1031 |
<validator class="com.izforge.izpack.util.RegularExpressionValidator"
|
| 1032 |
txt="Invalid email address!">
|
| 1033 |
<param
|
| 1034 |
name="pattern" |
| 1035 |
value="[a-zA-Z0-9._-]{3,}@[a-zA-Z0-9._-]+([.][a-zA-Z0-9_-]+)*[.][a-zA-Z0-9._-]{2,4}"
|
| 1036 |
/>
|
| 1037 |
</validator> |
| 1038 |
</field> |
| 1039 |
</PRE>
|
| 1040 |
<P>
|
| 1041 |
You can test your own regular expressions using the handy applet at |
| 1042 |
<TT><A NAME="tex2html30" |
| 1043 |
HREF="http://jakarta.apache.org/regexp/applet.html">http://jakarta.apache.org/regexp/applet.html</A></TT> . |
| 1044 |
<BR>
|
| 1045 |
<P>
|
| 1046 |
|
| 1047 |
<H3><A NAME="SECTION008114300000000000000"> |
| 1048 |
Creation Your Own Custom Validator</A>
|
| 1049 |
</H3>
|
| 1050 |
|
| 1051 |
<P>
|
| 1052 |
You can create your own custom Validator implementation simply by creating a |
| 1053 |
new class which implements the <TT>com.izforge.izpack.panels.Validator</TT> |
| 1054 |
interface. This interface specifies a single method: |
| 1055 |
<TT>validate(ProcessingClient client)</TT> , which returns a <TT>boolean</TT> |
| 1056 |
value. You can retrieve the value entered by the user by casting the input |
| 1057 |
ProcessingClient as a <TT>RuleInputField</TT> and calling the |
| 1058 |
<BR><TT>RuleInputField.getText()</TT> method. You can also retrieve any |
| 1059 |
parameters to your custom <TT>Validator</TT> by calling the |
| 1060 |
<BR><TT>RuleInputField.getValidatorParams()</TT> which returns a <TT>java.util.Map</TT> |
| 1061 |
object containing parameter names mapped to parameter values. For an example, take a |
| 1062 |
look at |
| 1063 |
<BR><TT>com.izforge.izpack.util.RegularExpressionValidator</TT>. |
| 1064 |
<BR>
|
| 1065 |
<P>
|
| 1066 |
Set values in the RuleInputField can be preprocessed. At now you can specify a |
| 1067 |
processor class to pre process a value to be set at initial value of a |
| 1068 |
RuleInputField. Syntax: |
| 1069 |
<PRE>
|
| 1070 |
<spec set="0:defaultVal:classname" .../> |
| 1071 |
</PRE>
|
| 1072 |
The class name is an optional value. The class must implement the |
| 1073 |
<TT>Processor</TT> interface. |
| 1074 |
<BR>
|
| 1075 |
<P>
|
| 1076 |
|
| 1077 |
<H2><A NAME="SECTION008115000000000000000"> |
| 1078 |
Processing the Field Content</A>
|
| 1079 |
</H2>
|
| 1080 |
|
| 1081 |
<P>
|
| 1082 |
This feature needs to be documented. |
| 1083 |
|
| 1084 |
<P>
|
| 1085 |
|
| 1086 |
<H2><A NAME="SECTION008116000000000000000"> |
| 1087 |
Summary Example</A>
|
| 1088 |
</H2>
|
| 1089 |
|
| 1090 |
<P>
|
| 1091 |
<PRE>
|
| 1092 |
<field type="rule" variable="test1"> |
| 1093 |
<description align="left" txt="A description for a rule input field."
|
| 1094 |
id="description.rule.1"/>
|
| 1095 |
<spec txt="Please enter your phone number:"
|
| 1096 |
layout="( N:3:3 ) N:3:3 - N:4:4 x N:5:5" |
| 1097 |
resultFormat="specialSeparator" separator="."/>
|
| 1098 |
<validator class="com.izforge.izpack.util.NotEmptyValidator"
|
| 1099 |
txt="The phone number is mandatory!" />
|
| 1100 |
<!--processor class=""/--> |
| 1101 |
</field> |
| 1102 |
</PRE>
|
| 1103 |
<P>
|
| 1104 |
|
| 1105 |
<H1><A NAME="SECTION008120000000000000000"> |
| 1106 |
Search</A>
|
| 1107 |
</H1>
|
| 1108 |
|
| 1109 |
<P>
|
| 1110 |
The search input field allows the user to choose the location of files or |
| 1111 |
directories. It also supports auto-detection of the location using a list of |
| 1112 |
suggestions. The field is basically a combobox with an extra button to |
| 1113 |
trigger auto-detection (again). |
| 1114 |
|
| 1115 |
<P>
|
| 1116 |
<DIV ALIGN="CENTER"> |
| 1117 |
<!-- MATH
|
| 1118 |
$\fbox{\includegraphics[scale=0.8]{img/userInput-search}}$
|
| 1119 |
-->
|
| 1120 |
<SPAN CLASS="MATH"><IMG |
| 1121 |
WIDTH="470" HEIGHT="165" ALIGN="MIDDLE" BORDER="0" |
| 1122 |
SRC="img11.png" |
| 1123 |
ALT="\fbox{\includegraphics[scale=0.8]{img/userInput-search}}"></SPAN> |
| 1124 |
</DIV>
|
| 1125 |
|
| 1126 |
<P>
|
| 1127 |
|
| 1128 |
<H2><A NAME="SECTION008121000000000000000"> |
| 1129 |
Specification</A>
|
| 1130 |
</H2>
|
| 1131 |
|
| 1132 |
<P>
|
| 1133 |
The <TT><description></TT> tag is the same as with other fields (see |
| 1134 |
<A HREF="#userInput:descriptiontag">6.2</A> on page <A HREF="node8.html#userInput:descriptiontag"><IMG ALIGN="BOTTOM" BORDER="1" ALT="[*]" SRC="crossref.png"></A>). The |
| 1135 |
<TT><spec></TT> tag supports the following attributes: |
| 1136 |
|
| 1137 |
<P>
|
| 1138 |
|
| 1139 |
<UL>
|
| 1140 |
<LI><TT>filename</TT> - the name of the file or directory to search for |
| 1141 |
</LI>
|
| 1142 |
<LI><TT>type</TT> - what to search for |
| 1143 |
|
| 1144 |
<UL>
|
| 1145 |
<LI><TT>file</TT> - search for a file |
| 1146 |
</LI>
|
| 1147 |
<LI><TT>directory</TT> - search for a directory |
| 1148 |
|
| 1149 |
</LI>
|
| 1150 |
</UL>
|
| 1151 |
</LI>
|
| 1152 |
<LI><TT>result</TT> - what to return as the search result |
| 1153 |
|
| 1154 |
<UL>
|
| 1155 |
<LI><TT>file</TT> - result of search is whole pathname of file or directory found |
| 1156 |
</LI>
|
| 1157 |
<LI><TT>directory</TT> - only return directory where the file was found (this is the same as <TT>file</TT> when searching for directories) |
| 1158 |
</LI>
|
| 1159 |
<LI><TT>parentdir</TT> - return the full path of the parent directory where the file was found |
| 1160 |
|
| 1161 |
</LI>
|
| 1162 |
</UL>
|
| 1163 |
</LI>
|
| 1164 |
<LI><TT>checkfilename</TT> - the name of a file or directory to check for existence (this can be used to validate the user's selection) |
| 1165 |
</LI>
|
| 1166 |
</UL>
|
| 1167 |
|
| 1168 |
<P>
|
| 1169 |
|
| 1170 |
<H2><A NAME="SECTION008122000000000000000"> |
| 1171 |
Example</A>
|
| 1172 |
</H2>
|
| 1173 |
|
| 1174 |
<P>
|
| 1175 |
<PRE>
|
| 1176 |
<field type="search" variable="java_sdk_home"> |
| 1177 |
<description align="left"
|
| 1178 |
txt="This is a description for a search input field." |
| 1179 |
id="description.java_sdk_home"/>
|
| 1180 |
<spec txt="Path to Java SDK:" checkfilename="lib/tools.jar"
|
| 1181 |
type="file" result="directory">
|
| 1182 |
<choice value="/usr/lib/java/" os="unix" /> |
| 1183 |
<choice value="/opt/java" os="unix" /> |
| 1184 |
<choice value="C:\Program Files\Java" os="windows" /> |
| 1185 |
<choice value="C:\Java" os="windows" /> |
| 1186 |
</spec> |
| 1187 |
</field> |
| 1188 |
</PRE>
|
| 1189 |
<P>
|
| 1190 |
|
| 1191 |
<DIV CLASS="navigation"><HR> |
| 1192 |
<!--Navigation Panel-->
|
| 1193 |
<A NAME="tex2html479" |
| 1194 |
HREF="node9.html"> |
| 1195 |
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> |
| 1196 |
<A NAME="tex2html475" |
| 1197 |
HREF="izpack-doc.html"> |
| 1198 |
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> |
| 1199 |
<A NAME="tex2html469" |
| 1200 |
HREF="node7.html"> |
| 1201 |
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> |
| 1202 |
<A NAME="tex2html477" |
| 1203 |
HREF="node1.html"> |
| 1204 |
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> |
| 1205 |
<BR>
|
| 1206 |
<B> Next:</B> <A NAME="tex2html480" |
| 1207 |
HREF="node9.html">Custom Actions</A> |
| 1208 |
<B> Up:</B> <A NAME="tex2html476" |
| 1209 |
HREF="izpack-doc.html">izpack-doc</A> |
| 1210 |
<B> Previous:</B> <A NAME="tex2html470" |
| 1211 |
HREF="node7.html">Creating Your Own Panels</A> |
| 1212 |
<B> <A NAME="tex2html478" |
| 1213 |
HREF="node1.html">Contents</A></B> </DIV> |
| 1214 |
<!--End of Navigation Panel-->
|
| 1215 |
<ADDRESS>
|
| 1216 |
Julien Ponge |
| 1217 |
2005-04-22 |
| 1218 |
</ADDRESS>
|
| 1219 |
</BODY>
|
| 1220 |
</HTML>
|