root / trunk / install / IzPack / src / doc / UserInput.tex @ 11445
History | View | Annotate | Download (35.8 KB)
1 | 5819 | cesar | % 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 |