root / import / ext3D / trunk / install-extension3d / IzPack / src / doc / UserInput.tex @ 15280
History | View | Annotate | Download (36.6 KB)
1 |
% IzPack - Documentation |
---|---|
2 |
|
3 |
% User Input |
4 |
|
5 |
\chapter{\label{chap:userinput}User Input} (by Elmar \textsc{Grom})\\ |
6 |
|
7 |
Most of the panels that come with IzPack take user input in some form. |
8 |
In some panels this is through a simple user acknowledgment in others |
9 |
the user can enter text or select a directory through a file open |
10 |
dialog. In all of those cases the user input is used for the specific |
11 |
purpose needed by the panel that takes the input. However, if you need |
12 |
user input during installation that will later on be available to your |
13 |
application then you need to use the user input panel.\\ |
14 |
|
15 |
To use this panel, list it in the install file with the class name |
16 |
\texttt{UserInputPanel}. In addition, you must write a XML specification |
17 |
and add it to the install resources. The name of this resource must be |
18 |
\texttt{userInputSpec.xml}.\\ |
19 |
|
20 |
The user input panel is a blank panel that can be populated with UI |
21 |
elements through a XML specification file. The specification supports |
22 |
text labels, input elements, explanatory text and some minor formatting |
23 |
options.\\ |
24 |
|
25 |
The following types of user input elements are supported: |
26 |
\begin{itemize} |
27 |
\item Text |
28 |
\item Combo Box |
29 |
\item Radio Buttons |
30 |
\item Check Box |
31 |
\item Rule Input Field |
32 |
\item Search Field |
33 |
\end{itemize}\ |
34 |
|
35 |
The way in which this panel conveys the user input to your application |
36 |
is through the variable substitution system. User input is not directly |
37 |
inserted into your configuration files but the variables that you |
38 |
specify for this panel are set in the variable substitution system. |
39 |
After this operation has taken place the variables and associated values |
40 |
are available for all substitutions made. This way of operation has a |
41 |
number of implications that you should be aware of.\\ |
42 |
|
43 |
First, not only can you set additional variables in this way but you can |
44 |
also modify variables that are defined elsewhere -even built in |
45 |
variables. For this reason you should be careful to avoid overlaps when |
46 |
choosing variable names. Although there might be cases when it seems |
47 |
useful to modify the value of other variables, it is generally not a |
48 |
good idea to do so. Because you might not exactly know when other |
49 |
variables are set and when and where they are used throughout the |
50 |
installation process, there might be unintended side effects.\\ |
51 |
|
52 |
Second, the panel must be shown at a point during the installation |
53 |
process before the variables are used. In most cases you will use the |
54 |
values to substitute variables in launch and configuration files that |
55 |
you supply with your installation. For this to work you place this panel |
56 |
before the install panel, because the install panel uses the variable |
57 |
substitutor to replace all such variables. Although using this panel any |
58 |
later in the process will correctly set the variables internally, there |
59 |
won't be any affect on the files written to disk. You can also use |
60 |
variables set in this way in other panels that you have written |
61 |
yourself. There is a section in the chapter on writing your own panel |
62 |
that explains how to do this. Also in this case it is important to place |
63 |
the associated input panel in the process before the variables are |
64 |
used.\\ |
65 |
|
66 |
At this point I would also like to mention that it is possible to hide |
67 |
select elements on the panel or the panel altogether if certain packs |
68 |
are not selected. For this to work you must place this panel after the |
69 |
packs panel. One side effect of using this feature is that it is not |
70 |
possible to step back once the user input panel is displayed. This is |
71 |
because the user might make changes in the packs selection that would |
72 |
require a complete rebuild of the UI. Unfortunately, building the UI is |
73 |
an irreversible process, therefore the user can not be allowed to go |
74 |
back to the packs panel.\\ |
75 |
|
76 |
|
77 |
\section{The Basic XML Structure} |
78 |
|
79 |
The top level XML section is called \texttt{<userInput>}. For most |
80 |
panels it does not make sense to present them more than once, however |
81 |
you might want to present multiple user input panels -with different |
82 |
content of course. Therefore the \texttt{<userInput>} section can |
83 |
contain multiple tags that each specify the details for one panel |
84 |
instance. The tag name for this is \texttt{<panel>}.\\ |
85 |
|
86 |
The \texttt{<panel>} tag uses the following attributes:\\ |
87 |
|
88 |
\textbf{order} \texttt{- required}\\ |
89 |
|
90 |
This is the order number of the user input panel for which this |
91 |
specification should be used. Counting starts at 0 and increments by 1 |
92 |
for each instance of the user input panel. So if a spec should be used |
93 |
for the second occurrence of the user input panel use |
94 |
\texttt{order="1"}.\\ |
95 |
|
96 |
\textbf{layout} \texttt{- optional}\\ |
97 |
|
98 |
There are three general layout rules this panel uses, they are |
99 |
\texttt{left}, \texttt{center} and \texttt{right}. While I think left is |
100 |
most commonly used, you might want to experiment with this attribute and |
101 |
see which you like best. The default is \texttt{left}.\\ |
102 |
|
103 |
|
104 |
\section{Concepts and XML Elements Common to All Fields} |
105 |
|
106 |
Before I dive into the details of defining the various UI elements I |
107 |
would like to present XML elements and general concepts that apply |
108 |
throughout. This saves me a lot of work in writing and you a lot of |
109 |
repetitive reading and maybe a tree or two.\\ |
110 |
|
111 |
The UI elements are generally laid out top to bottom in the order they |
112 |
appear in the XML file. The only exception to this rule is the title, |
113 |
which always appears at the very top. The layout pattern for the input |
114 |
fields is as follows: If a description is defined, it appears first, |
115 |
using the full available layout width. The input field is placed beneath |
116 |
the description. With fields such as the text field or the combo box, |
117 |
the label is placed to the left and the input field to the right. Fields |
118 |
such as radio buttons and check boxes are somewhat indented and have the |
119 |
label text appear to their right.\\ |
120 |
|
121 |
Each UI element is specified with a \texttt{<field>} tag. The |
122 |
\texttt{type} attribute is used to specify what kind of field you want |
123 |
to place. Obviously, the \texttt{type} attribute is not optional.\\ |
124 |
|
125 |
Each field that takes user input must also specify the variable that |
126 |
should be substituted. This is done with the \texttt{variable} |
127 |
attribute.\\ |
128 |
|
129 |
\label{userInput:descriptiontag} |
130 |
Almost all fields allow a description. When a description is allowed it |
131 |
is always added in the same way. The description is part of the data |
132 |
within the field tag. There can only be one description per field. If |
133 |
you add more than one, the first one is used and the others ignored. |
134 |
There are three attributes used with this tag. The text is specified |
135 |
through the \texttt{txt} or the \texttt{id} attribute. The details on |
136 |
using them are described below. The attributes are all optional but you |
137 |
must specify text to use, either directly or through the \texttt{id} |
138 |
attribute. In addition, you can set the text justification to |
139 |
\texttt{left}, \texttt{center} and \texttt{right} with the |
140 |
\texttt{align} attribute. \\ |
141 |
|
142 |
The following example illustrates the general pattern for field specification:\\ |
143 |
|
144 |
\footnotesize |
145 |
\begin{verbatim} |
146 |
<field type="text" variable="myFirstVariable"> |
147 |
<description align="left" txt="A description" id="description 1"/> |
148 |
. |
149 |
. |
150 |
. |
151 |
</field> |
152 |
\end{verbatim} |
153 |
\normalsize |
154 |
|
155 |
A very frequently used pattern is for the definition of text. Where ever |
156 |
text is needed (labels, descriptions, static text, choices etc.) it can |
157 |
be specified in place using the \texttt{txt} attribute. This is |
158 |
convenient if you are only supporting a single language. However, if you |
159 |
would like to separate your text definitions from the panel |
160 |
specification or if you need to support multiple languages you might |
161 |
want to use the \texttt{id} attribute instead to only specify an |
162 |
identifier. You can then add multiple XML files with the same name as |
163 |
this spec file (userInputSpec.xml) appended with an unserscore '\_' and |
164 |
the the appropriate three letter ISO3 language code. The content of |
165 |
those files must conform to the specification for IzPack language |
166 |
packages. For more details on this topic see the chapter on language |
167 |
packages under advanced features. \texttt{id} defines an identifier that |
168 |
is also defined in the language package, together with the localized |
169 |
text to use. It is possible to use both the \texttt{txt} and the |
170 |
\texttt{id} attribute. In this case the text from the language package |
171 |
is used. If for some reason the language package is not available or the |
172 |
\texttt{id} is not defined there, the text specified with \texttt{txt} |
173 |
is used as default.\\ |
174 |
|
175 |
All input fields can be pre-set with a value of your choice. Although |
176 |
the details vary a bit from field type to field type, the \texttt{set} |
177 |
attribute is always used to accomplish this. The \texttt{set} attribute |
178 |
is of course optional.\\ |
179 |
|
180 |
All fields that take user input use a \texttt{<spec>} tag to define the |
181 |
details of the input field. In the some cases the content of this tag is |
182 |
rather simple. Input fields with a more complex nature tend to have |
183 |
accordingly complex content in this tag. Since the details vary widely, |
184 |
they are explained with each input field.\\ |
185 |
|
186 |
Any number of \texttt{<createForPack name=''a pack name'' />} tags can be |
187 |
added to the \texttt{<panel>} and \texttt{<field>} sections. This tag |
188 |
has only one attribute and no data. The attribute is \texttt{name} and |
189 |
specifies the name of one of the installation packs that you have |
190 |
defined. Here is how it works: if no \texttt{<createForPack ...>} tag |
191 |
exists in a section, the entity is always created. However, if the tag |
192 |
exists, the entity is only created if one or more of the listed packs |
193 |
are selected for installation. As mentioned before, if you are using |
194 |
this feature, make sure the user input panel shows up after the packs |
195 |
panel.\\ |
196 |
|
197 |
\section{Internationalization} |
198 |
|
199 |
To provide internationalization you can create a file named |
200 |
\texttt{userInputLang.xml\_xyz} where \texttt{xyz} is the ISO3 code of the language |
201 |
in lowercase. Please be aware that case is significant. This file has to be inserted in the resources section |
202 |
of \texttt{install.xml} with the \texttt{id} and \texttt{src} attributes |
203 |
set at the name of the file.\\ |
204 |
|
205 |
Example:\\ |
206 |
|
207 |
If you have the following userInputSpec.xml |
208 |
and you want to internationalize \texttt{input.comment}, \texttt{input.proxy}, \texttt{input.port} for |
209 |
english and french you have to create two files named userInputLang.xml\_eng and userInputLang.xml\_fra: |
210 |
\begin{verbatim} |
211 |
<userInput> |
212 |
<panel order="0"> |
213 |
<field type="staticText" align="left" txt="My comment is here." id="input.comment"/> |
214 |
<field type="text" variable="proxyAddress"> |
215 |
<spec txt="Proxy Host:" id="input.proxy" size="25" set=""/> |
216 |
</field> |
217 |
<field type="text" variable="proxyPort"> |
218 |
<spec txt="Proxy Port:" id="input.port" size="6" set=""/> |
219 |
</field> |
220 |
</panel> |
221 |
</userInput> |
222 |
\end{verbatim} |
223 |
|
224 |
userInputLang.xml\_eng file contains: |
225 |
\begin{verbatim} |
226 |
<langpack> |
227 |
<str id="input.comment" txt="English:My comment is here."/> |
228 |
<str id="input.proxy" txt="English:Proxy Host:"/> |
229 |
<str id="input.port" txt="English:Proxy Port:"/> |
230 |
</langpack> |
231 |
\end{verbatim} |
232 |
|
233 |
userInputLang.xml\_fra file contains: |
234 |
\begin{verbatim} |
235 |
<langpack> |
236 |
<str id="input.comment" txt="French:My comment is here."/> |
237 |
<str id="input.proxy" txt="French:Proxy Host:"/> |
238 |
<str id="input.port" txt="French:Proxy Port:"/> |
239 |
</langpack> |
240 |
\end{verbatim} |
241 |
|
242 |
you will also have to add the following to the install.xml file |
243 |
\begin{verbatim} |
244 |
<resources> |
245 |
... |
246 |
<res id="userInputSpec.xml" src="userInputSpec.xml"/> |
247 |
<res id="userInputLang.xml_eng" src="userInputLang.xml_eng" /> |
248 |
<res id="userInputLang.xml_fra" src="userInputLang.xml_fra" /> |
249 |
... |
250 |
</resources> |
251 |
\end{verbatim} |
252 |
|
253 |
\section{Panel Title} |
254 |
|
255 |
You can place an optional title at the top of the panel. Though it is |
256 |
not possible to select a font for the title that is different form the |
257 |
one used on the rest of the panel, it is possible to modify the font to |
258 |
some extent. To specify the title create a \texttt{<field>} tag and use |
259 |
the \texttt{type} attribute with the value \texttt{title}. In addition |
260 |
to the \texttt{txt} and \texttt{id} attributes, the following attributes |
261 |
are supported:\\ |
262 |
|
263 |
\textbf{italic} \texttt{- optional}\\ |
264 |
|
265 |
With a value of \texttt{true} specifies that the title font should be in italics.\\ |
266 |
|
267 |
\textbf{bold} \texttt{- optional}\\ |
268 |
|
269 |
With a value of \texttt{true} specifies that the title font should be bold.\\ |
270 |
|
271 |
\textbf{size} \texttt{- optional}\\ |
272 |
|
273 |
This attribute specifies the size of the title font. Please note that |
274 |
the size is not specified in points but as a relative size multiplier |
275 |
compared to the body font on the panel. The default value is 2.\\ |
276 |
|
277 |
\section{Static Text} |
278 |
|
279 |
Static text is simply text that is placed on the panel without direct |
280 |
connection to any of the input elements. It is laid out to use the |
281 |
entire layout width available on the panel and is broken into multiple |
282 |
lines if necessary. To specify static text create a \texttt{<field>} tag |
283 |
and use the \texttt{type} attribute with a value of \texttt{staticText}. |
284 |
In addition to the \texttt{txt} and \texttt{id} attributes, the text can |
285 |
be justified \texttt{left}, \texttt{center} or \texttt{right} with the |
286 |
\texttt{align} attribute. It is not possible to format this text in any way.\\ |
287 |
|
288 |
\textbf{Example}\\ |
289 |
|
290 |
The following example inserts some static text in the panel. |
291 |
|
292 |
\footnotesize |
293 |
\begin{verbatim} |
294 |
<field type="staticText" align="left" |
295 |
txt="This is just some simple static text." |
296 |
id="staticText.text"/> |
297 |
\end{verbatim} |
298 |
\normalsize |
299 |
|
300 |
\section{Visual Separation} |
301 |
|
302 |
Sometimes it is desirable to separate different entities visually. This |
303 |
can be accomplished by inserting a space or a divider. A space simply |
304 |
inserts a vertical separation of the average height of a single line |
305 |
entity, such as a line of text or a an input field. A divider inserts |
306 |
the same amount of space but also draws a division line which can be |
307 |
either aligned at the top or bottom of the separation. |
308 |
\texttt{<space>}, \texttt{<divider>} |
309 |
|
310 |
..... maybe I should draw the line myself and add no additional space at all ... |
311 |
|
312 |
\section{Text Input} |
313 |
|
314 |
A text input field allows the user to enter and edit a single line of |
315 |
text, without length restriction. The input field can have a label, |
316 |
which will show to the left of the input field and a description, which |
317 |
can span multiple lines. The description is placed above the input field |
318 |
and uses the entire available layout width. The width of the input field |
319 |
must be explicitly set, otherwise it will only accommodate a single |
320 |
character. To specify a text input field create a \texttt{<field>} tag |
321 |
and use the \texttt{type} attribute with a value of \texttt{text}. The |
322 |
\texttt{txt} and \texttt{id} attributes are not supported here. The |
323 |
\texttt{variable} attribute specifies the variable that should be |
324 |
replaced with the text taken from the input field.\\ |
325 |
|
326 |
\textbf{The Data}\\ |
327 |
|
328 |
The data consists of two items, a description and the spec. The |
329 |
\texttt{<spec>} tag uses four attributes. The label text is specified with |
330 |
\texttt{txt} and/or \texttt{id} as described above. In addition, the |
331 |
width of the input field as it appears on the panel can be set with the |
332 |
\texttt{size} attribute. The value must be an integer and sets the field |
333 |
width based on the average character width of the active font. If this |
334 |
is not specified, then you will end up with a very narrow field that is |
335 |
practically unusable.\\ |
336 |
|
337 |
The fourth attribute \texttt{set} is optional. It takes a text string to |
338 |
pre-fill the input field.\\ |
339 |
|
340 |
\textbf{Example}\\ |
341 |
|
342 |
The following example creates a text input field with a label and |
343 |
description. The width of the input field will be enough to accommodate |
344 |
15 characters. The field will be pre-set with the text 'some text' when |
345 |
the UI is first presented.\\ |
346 |
|
347 |
\footnotesize |
348 |
\begin{verbatim} |
349 |
<field type="text" variable="textInput"> |
350 |
<description align="left" txt="A description for a text input field" |
351 |
id="description.text"/> |
352 |
<spec txt="Enter some text:" id="text.label" size="15" set="some text"/> |
353 |
</field> |
354 |
\end{verbatim} |
355 |
\normalsize |
356 |
|
357 |
\section{Radio Buttons} |
358 |
|
359 |
The radio buttons are useful when the user needs to select a specific |
360 |
option out of a pre-defined list of choices. This field offers an |
361 |
arbitrary number of mutually exclusive buttons, each with its own label. |
362 |
The placement of the buttons and labels is different form other fields. |
363 |
First, the button is placed to the left and the label text to the right. |
364 |
Second, the buttons are not lined up all the way to the left as other |
365 |
labels are but they are indented from that location. As with other |
366 |
fields, the description is placed above the list of radio buttons and |
367 |
uses the entire available layout width. To specify a set of radio |
368 |
buttons create a \texttt{<field>} tag and use the \texttt{type} |
369 |
attribute with a value of \texttt{radio}. The \texttt{txt} and |
370 |
\texttt{id} attributes are \textbf{not} supported here. As with all |
371 |
other input fields, the \texttt{variable} attribute specifies that |
372 |
variable that should be replaced with the user selection.\\ |
373 |
|
374 |
\textbf{The Data}\\ |
375 |
|
376 |
The data consists of two items, a description and the spec. The |
377 |
\texttt{<spec>} tag has no attributes, instead the specification details |
378 |
are entered as data within the \texttt{<spec>} tag. The \texttt{<spec>} |
379 |
data consists of one or more \texttt{<choice>} tags. One |
380 |
\texttt{<choice>} tag is required for each radio button. The |
381 |
\texttt{<choice>} tag accepts the usual \texttt{txt} and \texttt{id} |
382 |
attributes, which are used to specify the label text. In addition the |
383 |
following attributes are supported:\\ |
384 |
|
385 |
\textbf{value} \texttt{- required}\\ |
386 |
|
387 |
The \texttt{value} attribute is used to specify which value to insert if |
388 |
this associated radio button is selected. In other words, the label text |
389 |
has nothing to do with the value that is actually substituted for the |
390 |
variable. For this reason there is never an issue if multiple languages |
391 |
are used, the value is always the same for a given selection.\\ |
392 |
|
393 |
\textbf{set} \texttt{- optional}\\ |
394 |
|
395 |
The \texttt{set} attribute accepts the values \texttt{true} and |
396 |
\texttt{false}. Since the attribute is optional it can also be omitted, |
397 |
which is interpreted as \texttt{false}. If a value of \texttt{true} is |
398 |
used, the associated radio button will be selected when the UI is first |
399 |
presented. Obviously, only one of the buttons in a set should be set to |
400 |
\texttt{true}.\\ |
401 |
|
402 |
\textbf{Example}\\ |
403 |
|
404 |
The following example creates a set of four radio buttons with |
405 |
description. The second button will be selected when the UI is first |
406 |
presented.\\ |
407 |
|
408 |
\footnotesize |
409 |
\begin{verbatim} |
410 |
<field type="radio" variable="radioSelection"> |
411 |
<description align="left" txt="This is a description for radio buttons" |
412 |
id="description.radio"/> |
413 |
<spec> |
414 |
<choice txt="the first choice" id="radio.label.1" value="1 selected" /> |
415 |
<choice txt="the second choice" id="radio.label.2" value="2 selected" |
416 |
set="true" /> |
417 |
<choice txt="the third choice" id="radio.label.3" value="3 selected" /> |
418 |
<choice txt="the fourth choice" id="radio.label.4" value="4 selected" /> |
419 |
</spec> |
420 |
</field> |
421 |
\end{verbatim} |
422 |
\normalsize |
423 |
|
424 |
\section{Combo Box} |
425 |
|
426 |
The combo box provides essentially the same functionality as do the |
427 |
radio buttons, just in a different presentation stile. The advantage of |
428 |
the combo box is that it is easier to deal with a long list of |
429 |
choices.\\ |
430 |
|
431 |
\section{Check Box} |
432 |
|
433 |
If there are a number of choices and any combination of them could be |
434 |
selected, not just a single one, then radio buttons are not the way to |
435 |
go. You might be better off using a number of check boxes. The layout |
436 |
for a check box works in the same way as for radio buttons. The check |
437 |
box is placed indented from the left most edge and the label text is |
438 |
placed to the right of it. Other than with radio buttons, you cannot |
439 |
define any number of check boxes. This field allows the definition of |
440 |
only one check box, which is associated with one variable. If you need |
441 |
multiple check boxes you need to define one field for each of them. To |
442 |
make it look like a cohesive group you simply provide a description only |
443 |
for the first check box. All of the check boxes will be positioned in |
444 |
such a way that they look like a group, even though they are separate |
445 |
entities and their selections are conveyed to different variables. The |
446 |
description is placed above the check box and uses the entire available |
447 |
layout width. To specify a check box create a \texttt{<field>} tag and |
448 |
use the \texttt{type} attribute with a value of \texttt{check}. As with |
449 |
all other input fields, the \texttt{variable} attribute specifies the |
450 |
variable that should be replaced with the user input.\\ |
451 |
|
452 |
\textbf{The Data}\\ |
453 |
|
454 |
The data consists of two items, a description and the spec. The |
455 |
\texttt{<spec>} tag accepts the usual \texttt{txt} and \texttt{id} |
456 |
attributes, which are used to specify the label text. In addition, the |
457 |
following attributes are supported:\\ |
458 |
|
459 |
\textbf{true} \texttt{- required}\\ |
460 |
|
461 |
The \texttt{true} attribute specifies the value to use for substitution |
462 |
when the box is selected.\\ |
463 |
|
464 |
\textbf{false} \texttt{- required}\\ |
465 |
|
466 |
The \texttt{false} attribute specifies the value to use for substitution |
467 |
when the box is not selected.\\ |
468 |
|
469 |
\textbf{set} \texttt{- optional}\\ |
470 |
|
471 |
The \texttt{set} attribute accepts the values \texttt{true} and |
472 |
\texttt{false}. Since the attribute is optional it can also be omitted, |
473 |
which is interpreted as \texttt{false}. If a value of \texttt{true} is |
474 |
used, the check box will be selected when the UI is first presented.\\ |
475 |
|
476 |
\textbf{Example}\\ |
477 |
|
478 |
The following example creates a check box with description. The check |
479 |
box will not be selected when the UI is first presented. This could also |
480 |
be accomplished by omitting the \texttt{set} attribute.\\ |
481 |
|
482 |
\footnotesize |
483 |
\begin{verbatim} |
484 |
<field type="check" variable="chekSelection.1"> |
485 |
<description align="left" txt="This is a description for a check box" |
486 |
id="description.check.1"/> |
487 |
<spec txt="check box 1" id="check.label.1" true="on" false="off" |
488 |
set="false"/> |
489 |
</field> |
490 |
\end{verbatim} |
491 |
\normalsize |
492 |
|
493 |
\section{Rule Input} |
494 |
|
495 |
The rule input field is the most powerful and complex one of all the |
496 |
input fields offered by this panel. In its most simple incarnation it |
497 |
looks and works like a regular text input field. There is also only an |
498 |
incremental increase of the complexity in the specification for this |
499 |
case. However, it is unlikely that you would use it for such a purpose. |
500 |
The real power of this input field comes from the fact that rules can be |
501 |
applied to it that control many aspects of its look as well as overt and |
502 |
covert operation.\\ |
503 |
|
504 |
\subsection{Layout and Input Rules} |
505 |
|
506 |
The basic nature of this input field is that of a text input field and |
507 |
as mentioned before, in its most simple incarnation that is what it |
508 |
looks like and how it operates. However, the layout of the field can be |
509 |
defined in such a way that there are multiple logically interconnected |
510 |
text input fields, adorned with multiple labels. Further more, each of |
511 |
these fields can be instructed to restrict the type of input that will |
512 |
be accepted. Now you might ask what this could be useful for. As an |
513 |
answer, let me present a few examples that show how this feature can be |
514 |
used. Before I do this however, I would like to describe the |
515 |
specification syntax, so that the examples can be presented together |
516 |
with the specifications that make them work in a meaningful way.\\ |
517 |
|
518 |
The actual specification of the layout, the labels and the type of input |
519 |
each field accepts all happens in a single string with the |
520 |
\texttt{layout} attribute. First let us have a look at the specification |
521 |
format for a single field. This format consists of a triplet of |
522 |
information, separated by two colons ':'. A typical field spec would |
523 |
look like this: \texttt{N:4:4}, where the first item is a key that |
524 |
specifies the type of input this particular field will accept - numeric |
525 |
input in the example. The second item is an integer number that |
526 |
specifies the physical width of the field, this is the same as in the |
527 |
with of any regular text field. Therefore the field in the example will |
528 |
provide space to display four characters. The third item specifies the |
529 |
editing length of the string or in other words, the maximum length of |
530 |
the string that will be accepted by the field. In the \texttt{layout} |
531 |
string you can list as may fields as you need, each with its own set of |
532 |
limitations. In addition you can add text at the front, the end and in |
533 |
between the fields. The various entities must be separated by white |
534 |
space. The behavior of this field is such that when the editing length |
535 |
of a field has been reached, the cursor automatically moves on to the |
536 |
next field. Also, when the backspace key is used to delete characters |
537 |
and the beginning of a field has been reached, the cursor automatically |
538 |
moves on to the previous field. So let us have a look a some examples.\\ |
539 |
|
540 |
\textbf{Phone Number} |
541 |
|
542 |
The following specification will produce a pre formatted input field to |
543 |
accept a US phone number with in-house extension. Even though the |
544 |
pattern is formatted into number groups as customary, complete with |
545 |
parentheses '(' and dash '-', entering the number is as simple as typing |
546 |
all the digits. There is no need to advance using the tab key or to enter |
547 |
formatting characters. Because the fields only allow numeric entry, there |
548 |
is a much reduced chance for entering erroneous information. |
549 |
\texttt{"( N:3:3 ) N:3:3 - N:4:4 x N:5:5"}. Each of the fields uses the |
550 |
'N' key, indicating that only numerals will be accepted. Also, each of |
551 |
the fields only accepts strings of the same length as the physical width |
552 |
of the field.\\ |
553 |
|
554 |
\begin{center} |
555 |
\fbox{\includegraphics[scale=1.0]{img/userInput-phone}} |
556 |
\end{center} |
557 |
|
558 |
\textbf{E-Mail Address} |
559 |
|
560 |
This specification creates a pattern that is useful for entering an |
561 |
e-mail address \texttt{"AN:15:U @ AN:10:40 . A:4:4"}. Even though the |
562 |
first field is only fifteen characters wide it will accept a string of |
563 |
unlimited length, because the 'U' identifier is used for the edit |
564 |
length. The second field is a bit more restrictive by only accepting a |
565 |
string up to forty characters long.\\ |
566 |
|
567 |
\begin{center} |
568 |
\fbox{\includegraphics[scale=1.0]{img/userInput-email}} |
569 |
\end{center} |
570 |
|
571 |
\textbf{IP Address} |
572 |
|
573 |
It might not be uncommon to require entering of an IP address. The |
574 |
following simple specification will produce the necessary input field. |
575 |
All fields are the same, allowing just three digits of numerical entry. |
576 |
\texttt{"N:3:3 . N:3:3 . N:3:3 . N:3:3"}\\ |
577 |
|
578 |
\begin{center} |
579 |
\fbox{\includegraphics[scale=1.0]{img/userInput-IP}} |
580 |
\end{center} |
581 |
|
582 |
\textbf{Serial Number or Key Code} |
583 |
|
584 |
If you ship your product with a CD key code or serial number and require |
585 |
this information for registration, you might want to ask the customer to |
586 |
transcribe that number from the CD label, so that it is later on |
587 |
accessible to your application. As this is always an error prone |
588 |
operation, the predefined pattern with the easy editing support and |
589 |
restriction of accepted data helps to reduce transcription errors |
590 |
\texttt{"H:4:4 - N:6:6 - N:3:3"}. This particular specification will |
591 |
produce three fields, the first accepting four hexadecimal, the second |
592 |
six numerical and the third three numerical digits.\\ |
593 |
|
594 |
\begin{center} |
595 |
\fbox{\includegraphics[scale=1.0]{img/userInput-serial}} |
596 |
\end{center} |
597 |
|
598 |
\textbf{Limitations} |
599 |
|
600 |
Even though the above examples all use single character labels between |
601 |
fields, there is no restriction on the length of these labels. In |
602 |
addition, it is possible to place label text in front of the first field |
603 |
and after the last field and the text can even contain spaces. The only |
604 |
limitation in this regard is the fact that all white space in the text |
605 |
will be reduced to a single space on the display. This means that it is |
606 |
not possible to use multiple spaces or tabs in the text.\\ |
607 |
|
608 |
The following table lists and describes all the keys that can be used in |
609 |
the specification string.\\ |
610 |
|
611 |
\begin{center} |
612 |
\begin{tabularx}{\textwidth}{|l|l|X|} |
613 |
\hline \textit{Key} & \textit{Meaning} & \textit{Description} \\ |
614 |
\hline N & numeric & The field will accept only numerals.\\ |
615 |
\hline H & hexadecimal & The field will accept only hexadecimal numerals, that is all numbers from 0-F.\\ |
616 |
\hline A & alphabetic & The field will accept only alphabetic characters. Numerals and punctuation marks will not be accepted.\\ |
617 |
\hline AN & alpha-numeric & The field will accept alphabetic characters and numerals but no punctuation marks.\\ |
618 |
\hline O & open & The filed will accept any input, without restriction.\\ |
619 |
\hline U & unlimited & 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.\\ |
620 |
\hline |
621 |
\end{tabularx}\ |
622 |
\end{center} |
623 |
|
624 |
\subsection{Setting Field Content} |
625 |
|
626 |
Like all other input fields the rule input field can also be pre-filled |
627 |
with data and as usual, this is accomplished thought the \texttt{set} |
628 |
attribute. As you might expect, the details of setting this field are |
629 |
rather on the complicated side. In fact you can set each sub field |
630 |
individually and you can leave some of the fields blank in the process. |
631 |
The \texttt{set} specification for all sub fields is given in a single |
632 |
string. Each field is addressed by its index number, with the count |
633 |
starting at 0. The index is followed by a colon ':' and then by the |
634 |
content of the field. The string "0:1234 1:af415 3:awer" would fill the |
635 |
first subfield with \texttt{1234}, the second one with \texttt{af415} and |
636 |
the fourth with \texttt{awer}. The third subfield would stay blank |
637 |
and so would any additional fields that might follow.\\ |
638 |
|
639 |
The individual field specs must be separated with spaces. Spaces within |
640 |
the pre-fill values are not allowed, otherwise the result is undefined.\\ |
641 |
|
642 |
\subsection{The Output Format} |
643 |
|
644 |
The user input from all subfields is combined into one single value and |
645 |
used to replace the variable associated with the field. You can make a |
646 |
number of choices when it comes to the way how the subfield content is |
647 |
combined. This is done with the \texttt{resultFormat} and |
648 |
\texttt{separator} attributes. The \texttt{resultFormat} attribute can |
649 |
take the following values:\\ |
650 |
|
651 |
\begin{center} |
652 |
\begin{tabularx}{\textwidth}{|l|X|} |
653 |
\hline \textit{Value} & \textit{Meaning}\\ |
654 |
\hline \texttt{plainString} & The content of all subfields is simply concatenated into one long string.\\ |
655 |
\hline \texttt{displayFormat} & The content of all subfields and all labels -as displayed- is concatenated into one long string.\\ |
656 |
\hline \texttt{specialSeparator} & The content of all subfields is concatenated into one string, using the string specified withe the \texttt{separator} attribute to separate the content of the subfields.\\ |
657 |
\hline \texttt{processed} & The content is processed by Java code that you supply before replacing the variable. How to do this is described below.\\ |
658 |
\hline |
659 |
\end{tabularx}\ |
660 |
\end{center} |
661 |
|
662 |
\subsection{Validating the Field Content} |
663 |
|
664 |
You can provide runtime validation for user input into a rule field via the |
665 |
\texttt{validator} element (which is a child of the \texttt{field} element. |
666 |
There are two types of built-in validators already provided: a |
667 |
\texttt{NotEmptyValidator} and a \texttt{RegularExpressionValidator}. You can |
668 |
also easily create your own validator. In all cases, if the chosen validator |
669 |
returns \texttt{false}, a messagebox will display the contents of the |
670 |
\texttt{txt} attribute and the user will be unable to continue to the next panel.\\ |
671 |
|
672 |
You can specify a processor for a combobox: |
673 |
\begin{verbatim} |
674 |
<choice processor="fully.qualified.class.name" |
675 |
set="selectedValue"/> |
676 |
\end{verbatim} |
677 |
so that you can fill a combobox with data on a simple way. |
678 |
|
679 |
\subsubsection{NotEmptyValidator} |
680 |
|
681 |
The \texttt{NotEmptyValidator} simply checks that the user entered a non-null |
682 |
value into each subfield, and returns \texttt{false} otherwise.\\ |
683 |
|
684 |
\subsubsection{RegularExpressionValidator} |
685 |
|
686 |
The \texttt{RegularExpressionValidator} checks that the user entered a |
687 |
value which matches a specified regular expression, as accepted by the Jakarta |
688 |
Regexp library |
689 |
(\url{http://jakarta.apache.org/regexp/}). The syntax of this implementation |
690 |
is described in the javadoc of the \texttt{RE} class |
691 |
(\url{http://jakarta.apache.org/regexp/apidocs/org/apache/regexp/RE.html}). |
692 |
|
693 |
You can specify the regular |
694 |
expression to be tested by passing a parameter with a name of \texttt{pattern} |
695 |
to the validator (via the \texttt{param} element), with the regular expression |
696 |
as the \texttt{value} attribute. For example, the following would validate |
697 |
an e-mail address:\\ |
698 |
|
699 |
\footnotesize |
700 |
\begin{verbatim} |
701 |
<field type="rule" variable="EMAILADDRESS"> |
702 |
<spec |
703 |
txt="Your Email Address:" layout="O:12:U @ O:8:40 . A:4:4" |
704 |
set="0: 1:domain 2:com" resultFormat="displayFormat" |
705 |
/> |
706 |
<validator class="com.izforge.izpack.util.RegularExpressionValidator" |
707 |
txt="Invalid email address!"> |
708 |
<param |
709 |
name="pattern" |
710 |
value="[a-zA-Z0-9._-]{3,}@[a-zA-Z0-9._-]+([.][a-zA-Z0-9_-]+)*[.][a-zA-Z0-9._-]{2,4}" |
711 |
/> |
712 |
</validator> |
713 |
</field> |
714 |
\end{verbatim} |
715 |
\normalsize |
716 |
|
717 |
You can test your own regular expressions using the handy applet at |
718 |
\url{http://jakarta.apache.org/regexp/applet.html} . \\ |
719 |
|
720 |
\subsubsection{Creation Your Own Custom Validator} |
721 |
|
722 |
You can create your own custom Validator implementation simply by creating a |
723 |
new class which implements the \texttt{com.izforge.izpack.panels.Validator} |
724 |
interface. This interface specifies a single method: |
725 |
\texttt{validate(ProcessingClient client)} , which returns a \texttt{boolean} |
726 |
value. You can retrieve the value entered by the user by casting the input |
727 |
ProcessingClient as a \texttt{RuleInputField} and calling the \\ |
728 |
\texttt{RuleInputField.getText()} method. You can also retrieve any |
729 |
parameters to your custom \texttt{Validator} by calling the \\ |
730 |
\texttt{RuleInputField.getValidatorParams()} which returns a \texttt{java.util.Map} |
731 |
object containing parameter names mapped to parameter values. For an example, take a |
732 |
look at \\ |
733 |
\texttt{com.izforge.izpack.util.RegularExpressionValidator}.\\ |
734 |
|
735 |
Set values in the RuleInputField can be preprocessed. At now you can specify a |
736 |
processor class to pre process a value to be set at initial value of a |
737 |
RuleInputField. Syntax: |
738 |
\begin{verbatim} |
739 |
<spec set="0:defaultVal:classname" .../> |
740 |
\end{verbatim} |
741 |
The class name is an optional value. The class must implement the |
742 |
\texttt{Processor} interface.\\ |
743 |
|
744 |
\subsection{Processing the Field Content} |
745 |
|
746 |
This feature needs to be documented. |
747 |
|
748 |
\subsection{Summary Example} |
749 |
|
750 |
\footnotesize |
751 |
\begin{verbatim} |
752 |
<field type="rule" variable="test1"> |
753 |
<description align="left" txt="A description for a rule input field." |
754 |
id="description.rule.1"/> |
755 |
<spec txt="Please enter your phone number:" |
756 |
layout="( N:3:3 ) N:3:3 - N:4:4 x N:5:5" |
757 |
resultFormat="specialSeparator" separator="."/> |
758 |
<validator class="com.izforge.izpack.util.NotEmptyValidator" |
759 |
txt="The phone number is mandatory!" /> |
760 |
<!--processor class=""/--> |
761 |
</field> |
762 |
\end{verbatim} |
763 |
\normalsize |
764 |
|
765 |
\section{Search} |
766 |
|
767 |
The search input field allows the user to choose the location of files or |
768 |
directories. It also supports auto-detection of the location using a list of |
769 |
suggestions. The field is basically a combobox with an extra button to |
770 |
trigger auto-detection (again). |
771 |
|
772 |
\begin{center} |
773 |
\fbox{\includegraphics[scale=0.8]{img/userInput-search}} |
774 |
\end{center} |
775 |
|
776 |
\subsection{Specification} |
777 |
|
778 |
The \texttt{<description>} tag is the same as with other fields (see |
779 |
\ref{userInput:descriptiontag} on page \pageref{userInput:descriptiontag}). The |
780 |
\texttt{<spec>} tag supports the following attributes: |
781 |
|
782 |
\begin{itemize} |
783 |
\item \texttt{filename} - the name of the file or directory to search for |
784 |
\item \texttt{type} - what to search for |
785 |
\begin{itemize} |
786 |
\item \texttt{file} - search for a file |
787 |
\item \texttt{directory} - search for a directory |
788 |
\end{itemize} |
789 |
\item \texttt{result} - what to return as the search result |
790 |
\begin{itemize} |
791 |
\item \texttt{file} - result of search is whole pathname of file or directory found |
792 |
\item \texttt{directory} - only return directory where the file was found (this is the same as \texttt{file} when searching for directories) |
793 |
\item \texttt{parentdir} - return the full path of the parent directory where the file was found |
794 |
\end{itemize} |
795 |
\item \texttt{checkfilename} - the name of a file or directory to check for existence (this can be used to validate the user's selection) |
796 |
\end{itemize} |
797 |
|
798 |
\subsection{Example} |
799 |
|
800 |
\footnotesize |
801 |
\begin{verbatim} |
802 |
<field type="search" variable="java_sdk_home"> |
803 |
<description align="left" |
804 |
txt="This is a description for a search input field." |
805 |
id="description.java_sdk_home"/> |
806 |
<spec txt="Path to Java SDK:" checkfilename="lib/tools.jar" |
807 |
type="file" result="directory"> |
808 |
<choice value="/usr/lib/java/" os="unix" /> |
809 |
<choice value="/opt/java" os="unix" /> |
810 |
<choice value="C:\Program Files\Java" os="windows" /> |
811 |
<choice value="C:\Java" os="windows" /> |
812 |
</spec> |
813 |
</field> |
814 |
\end{verbatim} |
815 |
\normalsize |